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

#include "openswmm_api_common.hpp"
#include "../edit/ObjectDeleter.hpp"
#include "../../../include/openswmm/engine/openswmm_tables.h"
#include "StringCase.hpp"

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_timeseries_get_relative_info (SWMM_Engine engine, int idx, int n_relative, double anchor)
	Get a timeseries' time-only (relative) row info.

SWMM_ENGINE_API int	swmm_timeseries_set_relative_info (SWMM_Engine engine, int idx, int n_relative, double anchor)
	Declare a timeseries' leading rows as time-only (relative).

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 Apache-2.0

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 or SWMM_STATE_OPENED).
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 or SWMM_STATE_OPENED).
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 or SWMM_STATE_OPENED).
id	Unique null-terminated identifier.

Returns: SWMM_OK on success, or an error code.

Here is the call graph for this function:

◆ swmm_timeseries_get_relative_info()

SWMM_ENGINE_API int swmm_timeseries_get_relative_info	(	SWMM_Engine	engine,
		int	idx,
		int *	n_relative,
		double *	anchor )

Get a timeseries' time-only (relative) row info.

Rows authored without a date in a [TIMESERIES] section are elapsed times anchored at the simulation start (legacy SWMM seeds every series' date anchor with START_DATE + START_TIME). The engine stores those rows as absolute date/times after resolution; this reports how many leading rows were authored that way and the start_date offset currently baked into their x-values, so a caller can recover the authored elapsed times as x - anchor and the .inp writer emits them back in time-only form.

Parameters

	engine	Engine handle.
	idx	Zero-based table index (must be a TIMESERIES).
[out]	n_relative	Leading rows authored as elapsed time (0 = all rows carry explicit dates).
[out]	anchor	OADate offset baked into those rows' x-values.

Returns: SWMM_OK on success, or an error code.

Here is the call graph for this function:

◆ swmm_timeseries_set_relative_info()

SWMM_ENGINE_API int swmm_timeseries_set_relative_info	(	SWMM_Engine	engine,
		int	idx,
		int	n_relative,
		double	anchor )

Declare a timeseries' leading rows as time-only (relative).

Use after rebuilding a series through swmm_table_clear() / swmm_table_add_point() to restore its authored time-only format: the first n_relative points' x-values are treated as absolute date/times containing anchor as their simulation-start offset, and the .inp writer emits them as elapsed times (x - anchor) rather than dates. Pass 0 to mark every row as explicitly dated.

Parameters

engine	Engine handle.
idx	Zero-based table index (must be a TIMESERIES).
n_relative	Leading rows authored as elapsed time (clamped to the current point count).
anchor	OADate offset baked into those rows' x-values.

Returns: SWMM_OK on success, or an error code.

Here is the call graph for this function:

Functions

Detailed Description

Function Documentation

◆ swmm_curve_add()

◆ swmm_pattern_add()

◆ swmm_pattern_count()

◆ swmm_pattern_get_factor()

◆ swmm_pattern_get_factor_count()

◆ swmm_pattern_get_type()

◆ swmm_pattern_id()

◆ swmm_pattern_index()

◆ swmm_pattern_remove()

◆ swmm_pattern_rename()

◆ swmm_pattern_set_factors()

◆ swmm_table_add_point()

◆ swmm_table_clear()

◆ swmm_table_count()

◆ swmm_table_get_point()

◆ swmm_table_get_point_count()

◆ swmm_table_get_type()

◆ swmm_table_id()

◆ swmm_table_index()

◆ swmm_table_lookup()

◆ swmm_timeseries_add()

◆ swmm_timeseries_get_relative_info()

◆ swmm_timeseries_set_relative_info()