IFormulaEngine
Namespace: Meshmakers.Octo.Runtime.Contracts.Formulas
Shared formula engine over the mXparser dialect used across OctoMesh
(adapter DataPointMapping expressions, archive computed columns, runtime-query
@-expressions). A single implementation wraps OctoExpression; consumers depend
on this interface so they need no direct mXparser reference.
public interface IFormulaEngine
Remarks:
NULL operands (a replacement engine, e.g. Must keep these semantics): a
caller binds an operand without a value (SQL NULL, an attribute the row does not carry) as
Double.NaN instead of leaving it unbound. An unhandled NULL in arithmetic, a
comparison or a function yields NULL (IFormulaEngine.EvaluateRaw(String, IReadOnlyDictionary<String, Double>) returns null). if(cond, a, b)
yields the branch it takes, so a NULL in the other branch does not matter; a NULL condition yields
NULL. coalesce(x, default, …) returns the first argument that is not NaN, so it replaces a
NULL operand but not the null constant (negative infinity); isnull(x) recognizes both
and is 1 for a NULL operand or the null constant, otherwise 0.
Methods
NormalizeTernary(String)
Converts C-style ternary operators (cond ? a : b) to mXparser if(cond, a, b)
syntax. A no-op for expressions that contain no ternary.
string NormalizeTernary(string expression)
Parameters
expression String
Returns
Validate(String, IReadOnlyDictionary<String, Double>)
Validates an expression by binding the supplied test values to their argument names and
checking syntax plus that it evaluates to a finite number. The keys of
arguments are the column / variable names the formula is allowed to
reference; the values are test bindings (e.g. 42.0 per column, or a caller-supplied
preview value). An expression referencing a name not present here fails the syntax check.
FormulaSyntaxResult Validate(string expression, IReadOnlyDictionary<string, double> arguments)
Parameters
expression String
arguments IReadOnlyDictionary<String, Double>
Returns
CheckSyntax(String, IReadOnlyCollection<String>)
Checks an expression's syntax and that every referenced name is in
argumentNames — without evaluating it. Unlike IFormulaEngine.Validate(String, IReadOnlyDictionary<String, Double>)
this never fails for a finite-but-undefined-at-probe-values result (e.g. a division that is
zero only for the dummy values). Use for schema-time validation where only syntax and
reference resolution matter.
FormulaSyntaxResult CheckSyntax(string expression, IReadOnlyCollection<string> argumentNames)
Parameters
expression String
argumentNames IReadOnlyCollection<String>
Returns
EvaluateRaw(String, IReadOnlyDictionary<String, Double>)
Evaluates the expression to a raw Double. Returns Double.NaN when the
formula yields no value (invalid syntax, an unbound or NULL operand, a division by zero);
Double.NegativeInfinity is the engine's null sentinel. Throws
FormulaEvaluationException when the evaluation was aborted by an exception (e.g. out of
memory) — the value is then unknown, and a caller must not store it as NULL.
double EvaluateRaw(string expression, IReadOnlyDictionary<string, double> arguments)
Parameters
expression String
arguments IReadOnlyDictionary<String, Double>
Returns
Remarks:
Thread-safe. The parsed formula is cached per thread and reused, so evaluating the same formula for
many rows allocates almost nothing. Only the names the formula references are bound; other entries of
arguments are ignored.
Evaluate(String, IReadOnlyDictionary<String, Double>, FormulaResultType)
Evaluates the expression and casts the Double result back to
resultType. Returns null for the null sentinel
(Double.NegativeInfinity) or a Double.NaN result. Throws
FormulaEvaluationException like IFormulaEngine.EvaluateRaw(String, IReadOnlyDictionary<String, Double>).
object Evaluate(string expression, IReadOnlyDictionary<string, double> arguments, FormulaResultType resultType)
Parameters
expression String
arguments IReadOnlyDictionary<String, Double>
resultType FormulaResultType