Formula Engine

In This Topic

Formulas are strings, which can be parsed and evaluated at runtime. A valid formula is such a string, which is lexically and grammatically correct. A valid formula string is called formula expression or simply expression. Expressions are parsed and evaluated by an instance the NFormulaEngine class. The following code example evaluates formula expressions:

C#	Copy Code
NVariant res; // create the formula engine NFormulaEngine engine = new NFormulaEngine(); // define the a and b variables engine.Variables.Add("a", new NVariant(10)); engine.Variables.Add("b", new NVariant(20)); // evaluate an expression (res is 50) res = engine.ParseAndEvaluate("a+b2"); // evaluate another expression (res is 40.5) res = engine.ParseAndEvaluate("20.5+(102)*COS(0)");

Copy Code

NVariant res;
// create the formula engine
NFormulaEngine engine = new NFormulaEngine();
// define the a and b variables
engine.Variables.Add("a", new NVariant(10));
engine.Variables.Add("b", new NVariant(20));
// evaluate an expression (res is 50)
res = engine.ParseAndEvaluate("a+b*2");
// evaluate another expression (res is 40.5)
res = engine.ParseAndEvaluate("20.5+(10*2)*COS(0)");

Visual Basic	Copy Code
Dim res As NVariant ' create the formula engine Dim engine As New NFormulaEngine ' define the a and b variables engine.Variables.Add("a", New NVariant(10)) engine.Variables.Add("b", New NVariant(20)) ' evaluate an expression (res is 50) res = engine.ParseAndEvaluate("a+b2") ' evaluate another expression (res is 40.5) res = engine.ParseAndEvaluate("20.5+(102)*COS(0)")

Visual Basic

Copy Code

Dim res As NVariant
' create the formula engine
Dim engine As New NFormulaEngine
' define the a and b variables
engine.Variables.Add("a", New NVariant(10))
engine.Variables.Add("b", New NVariant(20))
' evaluate an expression (res is 50)
res = engine.ParseAndEvaluate("a+b*2")
' evaluate another expression (res is 40.5)
res = engine.ParseAndEvaluate("20.5+(10*2)*COS(0)")

Following is some background information about the way in which the formula engine works.

How it Works

Expressions are constructed from tokens. Tokens are such substrings from the initial expression, which cannot be broken into other tokens. A lexically correct expression consists of correct tokens. Currently recognized are the following types of tokens:

Parenthesis - the '(' and ')' characters, which can be used to change the operators privilege, and enclose the functions arguments.
Operator - the predefined operators, which you can use (+,-,*,\,<,> etc.)
Comma - the ',' character
Constant - this is a constant value embedded in the expression. Currently it can be a number, boolean value or string (discussed later in this topic).
Function - this is an identifier, which is resolved as a function
Variable - this is an identifier, which is resolved as a variable
Reference - this is an identifier, which is resolved as a reference

An identifier is such a substring from the expression, which starts with a letter or the '_' char and is followed by a sequence of letters, digits or the '_', '.' and '!' characters.

The process of cracking the expression to a list of tokens is called tokenization (lexical analysis). The formula engine performs the tokenization internally and uses its output to build a formula elements tree (grammatical analysis). You can use the Parse method of the NFormulaEngine to obtain the root of the formula elements tree (the elements of this tree are discussed later in this topic).

The evaluation of the formula elements tree uses variants. Variants are represented by the NVariant class. In essence this a value-type pair, which facilitates the type conversion of values, as well as arithmetic and comparison operations with values of different type. The result of a formula evaluation is a variant (e.g. a value of certain type - see Variants for more information).

Formula Elements

Each grammatically correct expression can be represented as a tree of formula elements. All types of formula elements derive from the base NFormulaElement class. A formula expression can contain one of the following formula elements:

Numbers - these are integer and floating point numbers. In the elements tree they are represented by an instance of the NConstantElement class, which contains a variant of numeric type. Following are some correctly formatted numbers:

12
0.1
145.23
7.5E-17
8.234E+13
Boolean values - these are the true and false boolean constants. In the elements tree they are represented by an instance of the NConstantElement class, which contains a variant of boolean type. Following are some correctly formatted boolean values:

true
false
True
False
TRUE
FALSE
Strings - these are substrings of the formula expression, which are enclosed in " characters. In the elements tree they are represented by an instance of the NConstantElement class, which contains a variant of string type. Following are some correctly formatted strings:

"hello"
"world"
Operators - ssupported is a common set of binary and unary operators (+. -, *, \, ^, =, <, >, <=, >=, <> and &). In the elements tree they are represented by an instance of the NOperatorElement class, which contains a reference to an object, which implements the INOperator interface. The current set of recognized operators is enumerated by the OperatorType enumeration. The current set of objects implementing the supported operators can be obtained from the UsedOperators property of the NFormulaEngine class (returns an instance of the NOperatorContainer class). See Operators for more information.
Parenthesis - the '(' and ')' characters can be used to change the operators precedence. In the elements tree, blocks enclosed in parenthesis are represented by an instance of the NParenthesisElement class. For example:

"(10 + 20) * 2" - evaluates to 60
"10 + 20 * 2" - evaluates to 50
Functions - supported is a large set of mathematical, trigonometrical, logical, text and bitwise functions. Function arguments must be enclosed in parenthesis and divided by commas. In the elements tree they are represented by an instance of the NFunctionElement class, which stores a reference to an object which implements the INFunction interface. The current set of functions which formula engine can recognize is exposed by the UsedFunctions property. For example:

"MIN(10, 20)" - evaluates to 10
"COS(0)" - evaluates to 1

See Functions for more information.
Variables - variables are valid identifiers to which you can assign a value. The recognized set of variables is defined by the NVariableCollection class accessible from the Variables property. See Variables for more information.
References - any identifier, which cannot be classified as a function or variable name, is a potential reference element. Reference elements are identified by the DelegateIsReferenceName delegate of the NFormulaEngine class. If a token is identified as a reference, its value must be provided by the DelegateGetReferenceValue delegate. See References for more information.