openswmm::mathexpr Namespace Reference

Classes
struct	Expression
struct	Token

Enumerations
enum class	TokenType : int {   NUMBER = 0 ,   VARIABLE = 1 ,   ADD = 2 ,   SUB = 3 ,   MUL = 4 ,   DIV = 5 ,   POW = 6 ,   NEG = 7 ,   LPAREN = 8 ,   RPAREN = 9 ,   FUNC_ABS = 10 ,   FUNC_SGN = 11 ,   FUNC_SQRT = 12 ,   FUNC_LOG = 13 ,   FUNC_EXP = 14 ,   FUNC_SIN = 15 ,   FUNC_COS = 16 ,   FUNC_TAN = 17 ,   FUNC_ASIN = 18 ,   FUNC_ACOS = 19 ,   FUNC_ATAN = 20 ,   FUNC_STEP = 21 ,   FUNC_MIN = 22 ,   FUNC_MAX = 23 ,   COMMA = 24 ,   FUNC_COT = 25 ,   FUNC_SINH = 26 ,   FUNC_COSH = 27 ,   FUNC_TANH = 28 ,   FUNC_COTH = 29 ,   FUNC_LOG10 = 30 ,   FUNC_ACOT = 31 }

Functions
const std::vector< std::string > &	function_names ()
	Return recognized built-in function names in stable token order.
int	parse (const std::string &expr_str, Expression &result)
	Tokenize an infix expression and construct its postfix representation.
double	evaluate (const Expression &expr, const std::function< double(const std::string &)> &var_lookup)
	Evaluate postfix tokens with a synchronous named-variable callback.
double	evaluate (const Expression &expr, const double *vars, int n_vars)
	Evaluate using variable indices stored in a compiled expression.
int	bind_variables (Expression &expr, const char *const *name_table, int n_vars)
	Bind each variable token to the first matching table entry.
int	compute_max_stack_depth (const Expression &expr)
	Compute the peak operand-stack occupancy implied by postfix tokens.
double	evaluate_fast (const Expression &expr, const double *vars) noexcept
	Evaluate the supported postfix subset with a fixed 32-value stack.

Enumeration Type Documentation

TokenType

enum class openswmm::mathexpr::TokenType : int

strong

Enumerator
NUMBER
VARIABLE
ADD
SUB
MUL
DIV
POW
NEG
LPAREN
RPAREN
FUNC_ABS
FUNC_SGN
FUNC_SQRT
FUNC_LOG
FUNC_EXP
FUNC_SIN
FUNC_COS
FUNC_TAN
FUNC_ASIN
FUNC_ACOS
FUNC_ATAN
FUNC_STEP
FUNC_MIN
FUNC_MAX
COMMA
FUNC_COT	cot(x) = 1/tan(x)
FUNC_SINH	sinh(x)
FUNC_COSH	cosh(x)
FUNC_TANH	tanh(x)
FUNC_COTH	coth(x) = 1/tanh(x)
FUNC_LOG10	log10(x)
FUNC_ACOT	acot(x) = atan(1/x)

Function Documentation

bind_variables()

int openswmm::mathexpr::bind_variables	(	Expression &	expr,
		const char *const *	name_table,
		int	n_vars )

Bind each variable token to the first matching table entry.

Parameters

[in,out]	expr	Expression whose variable indices are reset to -1 before resolution; variable names and postfix order remain unchanged.
[in]	name_table	Borrowed array of n_vars non-null, null-terminated names. Each table name is matched as a case-insensitive prefix of the expression's variable name; ordering determines which prefix wins.
[in]	n_vars	Nonnegative number of table entries.

Returns

Number of variable token occurrences bound, including repeated uses of the same name. Unmatched tokens retain var_idx == -1.

Note

Names and the table are not retained. This legacy prefix convention is used by groundwater expressions; it is not an exact-name match.

Here is the call graph for this function:

compute_max_stack_depth()

int openswmm::mathexpr::compute_max_stack_depth

(

const Expression &

expr

)

Compute the peak operand-stack occupancy implied by postfix tokens.

Parameters

[in]

expr

Compiled expression; not modified or validated.

Returns

Maximum cumulative stack depth; zero for an empty sequence.

Note

This counts stack effects only. It does not detect underflow, unsupported fast-evaluator functions, or malformed operand counts.

evaluate() [1/2]

double openswmm::mathexpr::evaluate	(	const Expression &	expr,
		const double *	vars,
		int	n_vars )

Evaluate using variable indices stored in a compiled expression.

Parameters

[in]	expr	Well-formed postfix expression; not modified. The first variable token matching each name supplies the index for that name.
[in]	vars	Borrowed array of n_vars values, non-null whenever a bound index in [0, n_vars) is read. No pointer is retained.
[in]	n_vars	Nonnegative number of available variable values.

Returns

Expression value; missing, negative, and out-of-range indices contribute zero. Empty expressions evaluate to zero.

Precondition

Operand arity satisfies the named-callback evaluate() contract.

See also

evaluate(const Expression&, const std::function<double(const std::string&)>&)

Here is the call graph for this function:

evaluate() [2/2]

double openswmm::mathexpr::evaluate	(	const Expression &	expr,
		const std::function< double(const std::string &)> &	var_lookup )

Evaluate postfix tokens with a synchronous named-variable callback.

Parameters

[in]	expr	Well-formed postfix expression with sufficient operands for every operation; the valid flag is not checked by this overload.
[in]	var_lookup	Nonempty callback returning a value for each variable name, invoked once per occurrence. It is not retained.

Returns

Top stack value, or zero for an empty expression.

Division by zero, a negative square-root argument, and nonpositive logarithm arguments produce zero. Other math domain and range behavior follows the standard library. Callback and allocation exceptions propagate.

Precondition

Every postfix operation has enough operands; malformed input can access an empty stack. Values use the caller's chosen units.

Here is the caller graph for this function:

evaluate_fast()

double openswmm::mathexpr::evaluate_fast ( const Expression & expr, const double * vars )

noexcept

Evaluate the supported postfix subset with a fixed 32-value stack.

Parameters

[in]	expr	Well-formed expression with bound variable indices and maximum stack depth <= 32; not modified.
[in]	vars	Borrowed array large enough for every nonnegative var_idx; non-null whenever such an index is read. Negative indices contribute zero.

Returns

Zero for invalid or empty expressions, otherwise the resulting value.

Precondition

Each operation has sufficient operands. Indices and stack bounds are unchecked. Supported functions end at FUNC_MAX; cot, sinh, cosh, tanh, coth, log10 and acot are not implemented by this fast evaluator.

Performs no heap allocation and retains no arrays. Division by zero, negative square roots and nonpositive natural logarithms produce zero, as in evaluate(). Other math operations follow standard-library floating-point behavior. compute_max_stack_depth() can check the depth.

function_names()

const std::vector< std::string > & openswmm::mathexpr::function_names

(

)

Return recognized built-in function names in stable token order.

Returns

Borrowed immutable process-lifetime vector of lowercase names: abs, sgn, sqrt, log, exp, sin, cos, tan, asin, acos, atan, step, min, max, cot, sinh, cosh, tanh, coth, log10, acot.

Note

min and max take two operands; the other functions take one. The caller must not delete or modify the returned storage.

Here is the caller graph for this function:

parse()

int openswmm::mathexpr::parse	(	const std::string &	expr_str,
		Expression &	result )

Tokenize an infix expression and construct its postfix representation.

Parameters

[in]	expr_str	Expression text; built-in function names are case-insensitive and variable names retain their original spelling.
[out]	result	Cleared before parsing. On success valid is true; on failure valid is false and postfix may contain a partial expression.

Returns

Zero after conversion, or -1 for unmatched parentheses.

Exceptions

std::invalid_argument	A numeric token cannot be converted by stod.
std::out_of_range	A numeric token exceeds stod's representable range.

Note

Conversion does not validate operand arity or reject every unknown character. A successful return alone does not make arbitrary input safe to evaluate; consumers must ensure a well-formed expression.

Here is the caller graph for this function: