openswmm_edit.h File Reference

OpenSWMM Engine — Model editing C API (deletion and type conversion). More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_edit.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SWMM_ImpactEntry
	One object that references the deletion target. More...
struct	SWMM_ImpactReport
	Aggregate impact report for a deletion operation. More...
struct	SWMM_ConversionResult
	Result of a node or link type conversion. More...

Typedefs
typedef enum SWMM_RefType	SWMM_RefType
	Category of an object that holds a cross-reference to a deleted object.
typedef struct SWMM_ImpactEntry	SWMM_ImpactEntry
	One object that references the deletion target.
typedef struct SWMM_ImpactReport	SWMM_ImpactReport
	Aggregate impact report for a deletion operation.
typedef struct SWMM_ConversionResult	SWMM_ConversionResult
	Result of a node or link type conversion.

Enumerations
enum	SWMM_RefType {   SWMM_REF_NODE = 0 ,   SWMM_REF_LINK = 1 ,   SWMM_REF_SUBCATCH = 2 ,   SWMM_REF_GAGE = 3 ,   SWMM_REF_TABLE = 4 ,   SWMM_REF_TRANSECT = 5 ,   SWMM_REF_INLET_USAGE = 6 }
	Category of an object that holds a cross-reference to a deleted object. More...

Functions
SWMM_ENGINE_API void	swmm_impact_report_free (SWMM_ImpactReport *report)
	Release heap memory owned by an impact report.
SWMM_ENGINE_API int	swmm_node_analyze_impact (SWMM_Engine engine, int idx, SWMM_ImpactReport *report_out)
	Analyse which objects reference a given node, without deleting it.
SWMM_ENGINE_API int	swmm_link_analyze_impact (SWMM_Engine engine, int idx, SWMM_ImpactReport *report_out)
	Analyse which objects reference a given node, without deleting it.
SWMM_ENGINE_API int	swmm_subcatch_analyze_impact (SWMM_Engine engine, int idx, SWMM_ImpactReport *report_out)
	Analyse which objects reference a given node, without deleting it.
SWMM_ENGINE_API int	swmm_gage_analyze_impact (SWMM_Engine engine, int idx, SWMM_ImpactReport *report_out)
	Analyse which objects reference a given node, without deleting it.
SWMM_ENGINE_API int	swmm_table_analyze_impact (SWMM_Engine engine, int idx, SWMM_ImpactReport *report_out)
	Analyse which objects reference a given node, without deleting it.
SWMM_ENGINE_API int	swmm_transect_analyze_impact (SWMM_Engine engine, int idx, SWMM_ImpactReport *report_out)
	Analyse which objects reference a given node, without deleting it.
SWMM_ENGINE_API int	swmm_node_delete (SWMM_Engine engine, int idx, SWMM_ImpactReport *cascade_out)
	Delete a node and cascade-delete or nullify all referencing objects.
SWMM_ENGINE_API int	swmm_link_delete (SWMM_Engine engine, int idx, SWMM_ImpactReport *cascade_out)
	Delete a link and cascade-delete or nullify all referencing objects.
SWMM_ENGINE_API int	swmm_subcatch_delete (SWMM_Engine engine, int idx, SWMM_ImpactReport *cascade_out)
	Delete a subcatchment and nullify all referencing objects.
SWMM_ENGINE_API int	swmm_gage_delete (SWMM_Engine engine, int idx, SWMM_ImpactReport *cascade_out)
	Delete a rain gage and nullify subcatchment gage references.
SWMM_ENGINE_API int	swmm_table_delete (SWMM_Engine engine, int idx, SWMM_ImpactReport *cascade_out)
	Delete a time series or curve and nullify all referencing objects.
SWMM_ENGINE_API int	swmm_transect_delete (SWMM_Engine engine, int idx, SWMM_ImpactReport *cascade_out)
	Delete a transect and nullify link xsect_curve references.
SWMM_ENGINE_API void	swmm_conversion_result_free (SWMM_ConversionResult *result)
	Release heap memory owned by a conversion result.
SWMM_ENGINE_API int	swmm_node_convert (SWMM_Engine engine, int idx, int new_type, SWMM_ConversionResult *result_out)
	Convert a node to a different type in-place.
SWMM_ENGINE_API int	swmm_link_convert (SWMM_Engine engine, int idx, int new_type, SWMM_ConversionResult *result_out)
	Convert a link to a different type in-place.

Detailed Description

OpenSWMM Engine — Model editing C API (deletion and type conversion).

Provides two capabilities for interactive model editing:

1. Object deletion — remove any node, link, subcatchment, rain gage, table/curve, or transect from the model while the engine is in BUILDING or OPENED state. A pre-deletion impact-analysis function is provided so callers can inspect what would be affected before committing.

2. Type conversion — convert a node between JUNCTION/OUTFALL/STORAGE/ DIVIDER, or a link between CONDUIT/PUMP/ORIFICE/WEIR/OUTLET, in-place. Common properties are preserved; type-specific properties are cleared and sensible defaults are applied.

Safety guards

All mutating operations (delete, convert) require the engine to be in SWMM_STATE_BUILDING or SWMM_STATE_OPENED. The impact-analysis functions are read-only and work in any state where data is present (not CREATED, CLOSED, or ERROR).

See also

openswmm_engine.h

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n MIT License

Typedef Documentation

SWMM_ConversionResult

typedef struct SWMM_ConversionResult SWMM_ConversionResult

Result of a node or link type conversion.

Lists type-specific fields that were cleared and any topology warnings generated. Caller must pass to swmm_conversion_result_free when done.

SWMM_ImpactEntry

typedef struct SWMM_ImpactEntry SWMM_ImpactEntry

One object that references the deletion target.

field is a static string literal naming the specific cross- reference field (e.g. "node1", "outlet_node", "pump_curve"). The caller must NOT free it.

SWMM_ImpactReport

typedef struct SWMM_ImpactReport SWMM_ImpactReport

Aggregate impact report for a deletion operation.

entries is heap-allocated by the engine. The caller must pass this struct to swmm_impact_report_free when done.

SWMM_RefType

typedef enum SWMM_RefType SWMM_RefType

Category of an object that holds a cross-reference to a deleted object.

Enumeration Type Documentation

SWMM_RefType

enum SWMM_RefType

Category of an object that holds a cross-reference to a deleted object.

Enumerator
SWMM_REF_NODE	A node holds a reference.
SWMM_REF_LINK	A link holds a reference.
SWMM_REF_SUBCATCH	A subcatchment holds a reference.
SWMM_REF_GAGE	A rain gage holds a reference.
SWMM_REF_TABLE	A time series or curve holds a reference.
SWMM_REF_TRANSECT	A transect holds a reference.
SWMM_REF_INLET_USAGE	An inlet usage entry holds a reference.

Function Documentation

swmm_conversion_result_free()

SWMM_ENGINE_API void swmm_conversion_result_free

(

SWMM_ConversionResult *

result

)

Release heap memory owned by a conversion result.

Does not free the struct itself. Safe to call on a zero-initialised struct.

swmm_gage_analyze_impact()

SWMM_ENGINE_API int swmm_gage_analyze_impact	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	report_out
	)

Analyse which objects reference a given node, without deleting it.

Parameters

engine	Engine handle.
idx	Zero-based node index.
report_out	Receives the impact report (may be NULL if not needed).

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_gage_delete()

SWMM_ENGINE_API int swmm_gage_delete	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	cascade_out
	)

Delete a rain gage and nullify subcatchment gage references.

Here is the call graph for this function:

swmm_impact_report_free()

SWMM_ENGINE_API void swmm_impact_report_free

(

SWMM_ImpactReport *

report

)

Release heap memory owned by an impact report.

Does not free the struct itself (typically stack-allocated by the caller). Safe to call on a zero-initialised struct.

swmm_link_analyze_impact()

SWMM_ENGINE_API int swmm_link_analyze_impact	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	report_out
	)

Analyse which objects reference a given node, without deleting it.

Parameters

engine	Engine handle.
idx	Zero-based node index.
report_out	Receives the impact report (may be NULL if not needed).

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_link_convert()

SWMM_ENGINE_API int swmm_link_convert	(	SWMM_Engine	engine,
		int	idx,
		int	new_type,
		SWMM_ConversionResult *	result_out
	)

Convert a link to a different type in-place.

Common properties (node1, node2, offset1, offset2, q0, q_limit, setting, comments) are preserved. Type-specific fields are cleared and new-type defaults applied.

Parameters

engine	Engine handle.
idx	Zero-based link index.
new_type	Target SWMM_LinkType value.
result_out	If non-NULL, receives the conversion result.

Returns

SWMM_OK on success, SWMM_ERR_BADPARAM if new_type equals current type, SWMM_ERR_LIFECYCLE, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_link_delete()

SWMM_ENGINE_API int swmm_link_delete	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	cascade_out
	)

Delete a link and cascade-delete or nullify all referencing objects.

Divider node divider_link fields that reference this link are nullified. Inlet usage entries whose link_index equals idx are deleted.

Here is the call graph for this function:

swmm_node_analyze_impact()

SWMM_ENGINE_API int swmm_node_analyze_impact	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	report_out
	)

Analyse which objects reference a given node, without deleting it.

Parameters

engine	Engine handle.
idx	Zero-based node index.
report_out	Receives the impact report (may be NULL if not needed).

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_node_convert()

SWMM_ENGINE_API int swmm_node_convert	(	SWMM_Engine	engine,
		int	idx,
		int	new_type,
		SWMM_ConversionResult *	result_out
	)

Convert a node to a different type in-place.

Common properties (invert_elev, full_depth, init_depth, sur_depth, ponded_area, coordinates) are preserved. Type-specific fields for the old type are cleared and type-specific defaults for the new type are applied. Topology warnings are generated but conversion still proceeds.

Parameters

engine	Engine handle.
idx	Zero-based node index.
new_type	Target SWMM_NodeType value.
result_out	If non-NULL, receives the conversion result. Caller must free with swmm_conversion_result_free.

Returns

SWMM_OK on success, SWMM_ERR_LIFECYCLE if not BUILDING/OPENED, SWMM_ERR_BADPARAM if new_type is invalid or equals current type, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_node_delete()

SWMM_ENGINE_API int swmm_node_delete	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	cascade_out
	)

Delete a node and cascade-delete or nullify all referencing objects.

Links that reference the node as node1 or node2 are deleted. Subcatchment outlet_node and inlet_usage node_index references are nullified (set to -1). All remaining integer cross-references whose value is greater than idx are decremented by 1.

Parameters

engine	Engine handle.
idx	Zero-based node index.
cascade_out	If non-NULL, receives the cascade report describing what was deleted or nullified. Caller must free with swmm_impact_report_free.

Returns

SWMM_OK on success, SWMM_ERR_LIFECYCLE if not BUILDING/OPENED, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_subcatch_analyze_impact()

SWMM_ENGINE_API int swmm_subcatch_analyze_impact	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	report_out
	)

Analyse which objects reference a given node, without deleting it.

Parameters

engine	Engine handle.
idx	Zero-based node index.
report_out	Receives the impact report (may be NULL if not needed).

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_subcatch_delete()

SWMM_ENGINE_API int swmm_subcatch_delete	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	cascade_out
	)

Delete a subcatchment and nullify all referencing objects.

Other subcatchments' outlet_subcatch fields and outfall nodes' outfall_route_to fields that reference this subcatchment are nullified.

Here is the call graph for this function:

swmm_table_analyze_impact()

SWMM_ENGINE_API int swmm_table_analyze_impact	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	report_out
	)

Analyse which objects reference a given node, without deleting it.

Parameters

engine	Engine handle.
idx	Zero-based node index.
report_out	Receives the impact report (may be NULL if not needed).

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_table_delete()

SWMM_ENGINE_API int swmm_table_delete	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	cascade_out
	)

Delete a time series or curve and nullify all referencing objects.

Affected references: gage ts_index, node storage_curve / outfall_param (TIDAL/TIMESERIES) / divider_curve, link pump_curve / xsect_curve.

Here is the call graph for this function:

swmm_transect_analyze_impact()

SWMM_ENGINE_API int swmm_transect_analyze_impact	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	report_out
	)

Analyse which objects reference a given node, without deleting it.

Parameters

engine	Engine handle.
idx	Zero-based node index.
report_out	Receives the impact report (may be NULL if not needed).

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, or SWMM_ERR_BADINDEX.

Here is the call graph for this function:

swmm_transect_delete()

SWMM_ENGINE_API int swmm_transect_delete	(	SWMM_Engine	engine,
		int	idx,
		SWMM_ImpactReport *	cascade_out
	)

Delete a transect and nullify link xsect_curve references.

Links with IRREGULAR cross-section shape whose xsect_curve equals idx have their xsect_curve set to -1 and shape reset to CIRCULAR.

Here is the call graph for this function: