Skip to main content

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​

String

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​

FormulaSyntaxResult

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​

FormulaSyntaxResult

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​

Double

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

Returns​

Object