Allows the values of parameters to be defined by equations. More...
Classes | |
| struct | ParseParameterExpressionResult |
| Holds the result of an attempt to parse a parameter expression string. More... | |
| struct | IParameterExpressionContext |
| Interface adopted by an object which can serve as the context for operations involving parsing or evaluation of parameter expressions. More... | |
| struct | IParseParameterExpressionContext |
| Interface adopted by an object which serves as the context for parsing parameter expressions. More... | |
| struct | IEvaluateParameterExpressionContext |
| Interface adopted by an object which serves as the context for evaluating parameter expressions. More... | |
| struct | IParameterExpression |
| Abstract representation of an expression involving parameters. More... | |
| struct | ParameterExpressionHandlerId |
| HandlerId identifying an IParameterExpressionHandler. More... | |
| struct | IParameterExpressionHandler |
| Interface adopted by an object which can parse and deserialize parameter expressions. More... | |
Enumerations | |
| enum | ParameterExpressionStatus { Success = SUCCESS, IncompatibleType, IncompatibleUnits, WrongNumberOfArguments, DivisionByZero, NullValue, FailedToObtainParameterValue, UnexpectedEndOfInput, UnknownSymbol, MismatchedDelimiters, MaxArgumentCountExceeded, FailedToParseValue, CircularDependency, FailedToAssignValue, Error = ERROR } |
| Possible return values from methods which manipulate parameter expressions. More... | |
Allows the values of parameters to be defined by equations.
The value of a parameter can be expressed as an equation using IParameterExpression. Equations can combine parameters, arithmetic operators, constants like pi, and a number of functions. A parametric model has an associated IParameterExpressionHandler which defines the syntax of such expressions and provides facilities for parsing and evaluating expressions within the context of the model. Expressions are stored in a compact compiled binary format such that the expression can be very efficiently evaluated without having to deserialize or re-parse it.
The syntax of the expressions supported by the default platform-supplied IParameterExpressionHandler is described below.
Parameters within an expression are referenced by their user-visible name. Because names can contain nearly any combination of unicode characters, including whitespace, they are greedily-parsed by necessity. Names are case-sensitive.
An expression cannot reference the parameter to which it is assigned, whether directly or indirectly. For example, the following are invalid:
Whitespace between symbols and operators is ignored. When the expression is round-tripped from string to persistent representation and back again, whitespace is not preserved - instead canonical whitespace is inserted between symbols and operators for readability.
Constant names are case-sensitive.
| Name | Type | Value |
|---|---|---|
| PI | Scalar | pi |
| E | Scalar | e |
| true | Boolean | true |
| false | Boolean | false |
| SQRT2 | Scalar | square root of 2 |
| SQRT1_2 | Scalar | 1 divided by the square root of 2 |
| LN2 | Scalar | natural logarithm of 2 |
| LN10 | Scalar | natural logarithm of 10 |
| LOG2E | Scalar | log2(e) |
| LOG10E | Scalar | log10(e) |
| Operation | Result | Notes |
|---|---|---|
| x + y | Addition | x and y must have like units; result has same units |
| x - y | Subtraction | x and y must have like units; result has same units |
| x * y | Multiplication | if one operand is scalar, result has the units of the other operand; if x and y are distances, result is an area; any other combination of units is prohibited. |
| x / y | Division | if one operand is scalar, result has the units of the other operand; if x and y have like units, result is unitless; if x is an area and y a distance, result is a distance; any other combination of units is prohibited |
| x % y | Modulo Division | x and y must be integers; result is the integer remainder of the division |
| x ^ y | x raised to power of y | Units of x are preserved - they are not raised to the power of y |
| -x | Negation of x | Units are preserved |
Comparison operators compare two operands of like types and return a boolean value.
| Operation | Comparison | Notes |
|---|---|---|
| x == y | Equality | Supported by all types |
| x != y | Inequality | Supported by all types |
| x < y | Less than | Numeric types only |
| x <= y | Less than or equal to | Numeric types only |
| x > y | Greater than | Numeric types only |
| x >= y | Greater or equal | Numeric types only |
Logical operators compare two boolean values or expressions and return a boolean.
| Operation | Meaining | Result |
|---|---|---|
| x && y | AND | true if both x and y are true |
| x || y | OR | true if either x or y is true |
| !x | NOT | true if x is false; false if x is true |
The ternary conditional operator allows an expression to choose between two values based on the value of a boolean expression. The expressions on either side of the colon symbol must be of the same type. The expression to the left of the question mark symbol must evaluate to a boolean value.
Example: "odd(x) ? y : z" evaluates to y if x is odd; otherwise it evaluates to z.
The types of literal numeric values like "12.34" within expressions are interpreted within the context in which they appear. Values interpreted as distances or areas are assumed to be expressed in master units; angles, in degrees. The conversion functions like area() and dist() can be used to explicitly state the type of a literal.
Additionally, literal values can be specified in a format which can be parsed according to the model's unit settings.
The parsed value will be stored in invariant units, but when converted back into a string will again be formatted according to the model's unit settings.
Function names are case-sensitive and must be followed by parentheses. Function arguments can consist of expressions of any complexity.
Examples:
| Name | Arguments | Type | Result |
|---|---|---|---|
| sqrt(x) | x:numeric | type of x | square root of x |
| limit(x, min, max) | all the same numeric type | type of x | min, if x < min; max, if x > max; else, x |
| sin(x) | x:angle | scalar | sine of x |
| cos(x) | x:angle | scalar | cosine of x |
| tan(x) | x:angle | scalar | tangent of x |
| acos(x) | x:scalar | angle | arccosine of x |
| asin(x) | x:scalar | angle | arcsine of x |
| atan(x) | x:scalar | angle | arctangent of x |
| log(x) | x:numeric | type of x | natural logarithm of x |
| log10(x) | x:numeric | type of x | base-10 logarithm of x |
| abs(x) | x:numeric | type of x | absolute value of x |
| floor(x) | x:numeric | type of x | value of x, rounded down to the nearest whole number |
| ceil(x) | x:numeric | type of x | value of x, rounded up to the nearest whole number |
| trunc(x) | x:numeric | type of x | value of x, with decimal portion truncated |
| round(x) | x:numeric | type of x | value of x, rounded to the nearest whole number |
| max(x, y, ...) | 2-20 arguments of same numeric type | type of x | maximum of the supplied arguments. |
| min(x, y, ...) | 2-20 arguments of same numeric type | type of x | minimum of the supplied arguments. |
| int(x) | x:numeric | integer | reinterprets the specified value as an integer, truncating any decimal portion |
| num(x) | x:numeric | scalar | reinterprets the specified value as a unitless floating point value |
| dist(x) | x:numeric | distance | reinterprets the specified value as a distance in working units |
| area(x) | x:numeric | area | reinterprets the specified value as an area in square working units |
| ang(x) | x:numeric | angle | reinterprets the specified value as an angle in degrees |
| degrees(x) | x:scalar | angle | an angle, in degrees, equivalent to x radians |
| odd(x) | x:numeric | boolean | true if x is odd |
| sign(x) | x:numeric | integer | -1, if x < 0; 0, if x == 0; 1, if x > 0 |
|
strong |
Possible return values from methods which manipulate parameter expressions.
| Enumerator | |
|---|---|
| Success |
Indicates operation was successful. |
| IncompatibleType |
An operation involved a parameter of a type not supported by that operation. |
| IncompatibleUnits |
An operation involved a parameter with units not supported by that operation. |
| WrongNumberOfArguments |
An operator or function was invoked with incorrect number of arguments. |
| DivisionByZero |
Attempt to divide by zero. |
| NullValue |
A null value was encountered in a context in which null values are not supported. |
| FailedToObtainParameterValue |
A requested parameter value was not found to exist. |
| UnexpectedEndOfInput |
A malformed expression string. |
| UnknownSymbol |
A symbol in an expression could not be resolved to a function, parameter, or constant. |
| MismatchedDelimiters |
Open and closed delimiters such as parentheses are not balanced within an expression. |
| MaxArgumentCountExceeded |
The internal limit for number of arguments to functions accepting indeterminite number of arguments (such as max()) was exceeded. Limit is 20. |
| FailedToParseValue |
A literal value such as a number could not be parsed. |
| CircularDependency |
An expression assigned to a parameter uses that parameter either directly or indirectly, resulting in an insoluble equation. |
| FailedToAssignValue |
The result of an expression could not be assigned to the associated parameter. |
| Error |
An unspecified error. |