openswmm_tables_impl.cpp File Reference

C API implementation — tables (time series, curves) and patterns. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_tables.h"

Include dependency graph for openswmm_tables_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_table_count (SWMM_Engine engine)
	Get the total number of tables (time series + curves) in the model.
SWMM_ENGINE_API int	swmm_table_index (SWMM_Engine engine, const char *id)
	Look up a table's zero-based index by its string identifier.
SWMM_ENGINE_API const char *	swmm_table_id (SWMM_Engine engine, int idx)
	Get the string identifier of a table by index.
SWMM_ENGINE_API int	swmm_table_get_type (SWMM_Engine engine, int idx, int *type)
	Get a table's type code.
SWMM_ENGINE_API int	swmm_timeseries_add (SWMM_Engine engine, const char *id)
	Add a new time series to the model.
SWMM_ENGINE_API int	swmm_curve_add (SWMM_Engine engine, const char *id, int type)
	Add a new curve to the model.
SWMM_ENGINE_API int	swmm_table_add_point (SWMM_Engine engine, int idx, double x, double y)
	Append a data point (x, y) to a table.
SWMM_ENGINE_API int	swmm_table_get_point_count (SWMM_Engine engine, int idx, int *count)
	Get the number of data points in a table.
SWMM_ENGINE_API int	swmm_table_get_point (SWMM_Engine engine, int idx, int pt_idx, double *x, double *y)
	Get a specific data point from a table.
SWMM_ENGINE_API int	swmm_table_clear (SWMM_Engine engine, int idx)
	Remove all data points from a table.
SWMM_ENGINE_API int	swmm_table_lookup (SWMM_Engine engine, int idx, double x, double *y)
	Interpolate a Y value from a table for a given X.
SWMM_ENGINE_API int	swmm_pattern_add (SWMM_Engine engine, const char *id, int type)
	Add a new time pattern to the model.
SWMM_ENGINE_API int	swmm_pattern_set_factors (SWMM_Engine engine, int idx, const double *factors, int count)
	Set the multiplier factors for a time pattern.
SWMM_ENGINE_API int	swmm_pattern_count (SWMM_Engine engine)
	Get the total number of time patterns in the model.
SWMM_ENGINE_API int	swmm_pattern_index (SWMM_Engine engine, const char *id)
	Look up a pattern's zero-based index by its string identifier.
SWMM_ENGINE_API const char *	swmm_pattern_id (SWMM_Engine engine, int idx)
	Get the string identifier of a pattern by index.
SWMM_ENGINE_API int	swmm_pattern_get_type (SWMM_Engine engine, int idx, int *type)
	Get a pattern's type code.
SWMM_ENGINE_API int	swmm_pattern_get_factor_count (SWMM_Engine engine, int idx, int *count)
	Get the number of multiplier factors stored for a pattern.
SWMM_ENGINE_API int	swmm_pattern_get_factor (SWMM_Engine engine, int idx, int i, double *v)
	Get one multiplier factor from a pattern.
SWMM_ENGINE_API int	swmm_pattern_remove (SWMM_Engine engine, int idx)
	Remove a time pattern by index, clearing any reference sites.
SWMM_ENGINE_API int	swmm_pattern_rename (SWMM_Engine engine, int idx, const char *newId)
	Rename a time pattern; updates every stored reference to the previous name across inflows, DWF, aquifer ET, and options.

Detailed Description

C API implementation — tables (time series, curves) and patterns.

See also

include/openswmm/engine/openswmm_tables.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

Function Documentation

swmm_curve_add()

SWMM_ENGINE_API int swmm_curve_add	(	SWMM_Engine	engine,
		const char *	id,
		int	type
	)

Add a new curve to the model.

Curve types: 0=STORAGE, 1=DIVERSION, 2=TIDAL, 3=RATING, 4=CONTROL, 5=SHAPE, 6=PUMP1..PUMP4, etc.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING).
id	Unique null-terminated identifier.
type	Curve type code.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_pattern_add()

SWMM_ENGINE_API int swmm_pattern_add	(	SWMM_Engine	engine,
		const char *	id,
		int	type
	)

Add a new time pattern to the model.

Pattern types: 0=MONTHLY, 1=DAILY, 2=HOURLY, 3=WEEKEND.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING).
id	Unique null-terminated identifier.
type	Pattern type code.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_pattern_count()

SWMM_ENGINE_API int swmm_pattern_count

(

SWMM_Engine

engine

)

Get the total number of time patterns in the model.

Parameters

engine

Engine handle.

Returns

Number of patterns, or -1 on error.

swmm_pattern_get_factor()

SWMM_ENGINE_API int swmm_pattern_get_factor	(	SWMM_Engine	engine,
		int	idx,
		int	i,
		double *	v
	)

Get one multiplier factor from a pattern.

Parameters

	engine	Engine handle.
	idx	Zero-based pattern index.
	i	Zero-based factor index within the pattern.
[out]	v	Receives the multiplier value.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_pattern_get_factor_count()

SWMM_ENGINE_API int swmm_pattern_get_factor_count	(	SWMM_Engine	engine,
		int	idx,
		int *	count
	)

Get the number of multiplier factors stored for a pattern.

Parameters

	engine	Engine handle.
	idx	Zero-based pattern index.
[out]	count	Receives the factor count (typically 12, 7, or 24).

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_pattern_get_type()

SWMM_ENGINE_API int swmm_pattern_get_type	(	SWMM_Engine	engine,
		int	idx,
		int *	type
	)

Get a pattern's type code.

Pattern types: 0=MONTHLY, 1=DAILY, 2=HOURLY, 3=WEEKEND. Used by the GUI to filter pattern pickers by pattern kind (e.g. the four DWF picker rows each accept a specific type).

Parameters

	engine	Engine handle.
	idx	Zero-based pattern index.
[out]	type	Receives the pattern type code.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_pattern_id()

SWMM_ENGINE_API const char * swmm_pattern_id	(	SWMM_Engine	engine,
		int	idx
	)

Get the string identifier of a pattern by index.

Parameters

engine	Engine handle.
idx	Zero-based pattern index.

Returns

Null-terminated string owned by the engine, or NULL on error.

swmm_pattern_index()

SWMM_ENGINE_API int swmm_pattern_index	(	SWMM_Engine	engine,
		const char *	id
	)

Look up a pattern's zero-based index by its string identifier.

Parameters

engine	Engine handle.
id	Null-terminated pattern identifier.

Returns

Zero-based index, or -1 if not found.

swmm_pattern_remove()

SWMM_ENGINE_API int swmm_pattern_remove	(	SWMM_Engine	engine,
		int	idx
	)

Remove a time pattern by index, clearing any reference sites.

Walks every place the engine stores a pattern name and clears any entry matching the removed pattern: external inflows (ext_inflows.pattern_name), dry-weather-flow patterns (dwf.pat1..pat4), aquifer ET patterns (aquifers.upper_evap_pat), and the evaporation recovery option (options.evap_recovery_pat). The removal itself shifts subsequent pattern indices down by one — callers that hold cached pattern indices must re-resolve via swmm_pattern_index.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
idx	Zero-based pattern index.

Returns

SWMM_OK on success (idempotent: returns SWMM_OK if idx is out of range, matching the GUI's repeated-click expectations); SWMM_ERR_LIFECYCLE if not editable.

Here is the call graph for this function:

swmm_pattern_rename()

SWMM_ENGINE_API int swmm_pattern_rename	(	SWMM_Engine	engine,
		int	idx,
		const char *	newId
	)

Rename a time pattern; updates every stored reference to the previous name across inflows, DWF, aquifer ET, and options.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
idx	Zero-based pattern index.
newId	New null-terminated identifier; must not already be in use.

Returns

SWMM_OK on success; SWMM_ERR_BADPARAM if newId is empty or collides with an existing pattern; SWMM_ERR_LIFECYCLE if not editable; SWMM_ERR_BADINDEX if idx is out of range.

Here is the call graph for this function:

swmm_pattern_set_factors()

SWMM_ENGINE_API int swmm_pattern_set_factors	(	SWMM_Engine	engine,
		int	idx,
		const double *	factors,
		int	count
	)

Set the multiplier factors for a time pattern.

Parameters

engine	Engine handle.
idx	Zero-based pattern index.
factors	Array of multiplier values.
count	Number of factors (e.g., 12 for MONTHLY, 24 for HOURLY).

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_table_add_point()

SWMM_ENGINE_API int swmm_table_add_point	(	SWMM_Engine	engine,
		int	idx,
		double	x,
		double	y
	)

Append a data point (x, y) to a table.

For time series, x is in decimal days; for curves, x depends on the curve type (e.g., depth for storage curves).

Parameters

engine	Engine handle.
idx	Zero-based table index.
x	X value (independent variable).
y	Y value (dependent variable).

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_table_clear()

SWMM_ENGINE_API int swmm_table_clear	(	SWMM_Engine	engine,
		int	idx
	)

Remove all data points from a table.

Parameters

engine	Engine handle.
idx	Zero-based table index.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_table_count()

SWMM_ENGINE_API int swmm_table_count

(

SWMM_Engine

engine

)

Get the total number of tables (time series + curves) in the model.

Parameters

engine

Engine handle.

Returns

Number of tables, or -1 on error.

swmm_table_get_point()

SWMM_ENGINE_API int swmm_table_get_point	(	SWMM_Engine	engine,
		int	idx,
		int	pt_idx,
		double *	x,
		double *	y
	)

Get a specific data point from a table.

Parameters

	engine	Engine handle.
	idx	Zero-based table index.
	pt_idx	Zero-based point index within the table.
[out]	x	Receives the X value.
[out]	y	Receives the Y value.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_table_get_point_count()

SWMM_ENGINE_API int swmm_table_get_point_count	(	SWMM_Engine	engine,
		int	idx,
		int *	count
	)

Get the number of data points in a table.

Parameters

	engine	Engine handle.
	idx	Zero-based table index.
[out]	count	Receives the point count.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_table_get_type()

SWMM_ENGINE_API int swmm_table_get_type	(	SWMM_Engine	engine,
		int	idx,
		int *	type
	)

Get a table's type code.

Tables are stored in a single unified array; this lets callers partition the array into time series vs. each curve type (e.g. for the GUI's Data Objects browser). Type values mirror openswmm::TableType: 0 = TIMESERIES 1 = CURVE_STORAGE 2 = CURVE_DIVERSION 3 = CURVE_RATING 4 = CURVE_SHAPE 5 = CURVE_CONTROL 6 = CURVE_TIDAL 7..11 = CURVE_PUMP1..PUMP5

Parameters

	engine	Engine handle.
	idx	Zero-based table index.
[out]	type	Receives the type code.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_table_id()

SWMM_ENGINE_API const char * swmm_table_id	(	SWMM_Engine	engine,
		int	idx
	)

Get the string identifier of a table by index.

Parameters

engine	Engine handle.
idx	Zero-based table index.

Returns

Null-terminated string owned by the engine, or NULL on error.

Here is the call graph for this function:

swmm_table_index()

SWMM_ENGINE_API int swmm_table_index	(	SWMM_Engine	engine,
		const char *	id
	)

Look up a table's zero-based index by its string identifier.

Parameters

engine	Engine handle.
id	Null-terminated table identifier.

Returns

Zero-based index, or -1 if not found.

swmm_table_lookup()

SWMM_ENGINE_API int swmm_table_lookup	(	SWMM_Engine	engine,
		int	idx,
		double	x,
		double *	y
	)

Interpolate a Y value from a table for a given X.

Uses cursor-based lookup for efficient sequential access (e.g., during time-stepping through a time series).

Parameters

	engine	Engine handle.
	idx	Zero-based table index.
	x	X value to look up.
[out]	y	Receives the interpolated Y value.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function:

swmm_timeseries_add()

SWMM_ENGINE_API int swmm_timeseries_add	(	SWMM_Engine	engine,
		const char *	id
	)

Add a new time series to the model.

Parameters

engine	Engine handle (SWMM_STATE_BUILDING).
id	Unique null-terminated identifier.

Returns

SWMM_OK on success, or an error code.

Here is the call graph for this function: