Class ExpressionFieldEvaluator

Encapsulates the code required to parse and compute formulas. Hash table properties maintain a Formula Library of functions as well as a list of dependent cells.

You can add and remove library functions.

Inheritance

System.Object

ExpressionFieldEvaluator

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

Namespace: Syncfusion.Windows.Forms.Grid.Formulas

Assembly: Syncfusion.Grid.Windows.dll

Syntax

public class ExpressionFieldEvaluator

Constructors

ExpressionFieldEvaluator(GridModel)

Initializes a new instance of the ExpressionFieldEvaluator class.

Declaration

public ExpressionFieldEvaluator(GridModel _model)

Parameters

Type	Name	Description
GridModel	_model	The contents of the grid can be rendered to the screen.

Fields

FormulaErrorStrings

String array that holds the strings used in error messages within the Formula Engine.

Declaration

public string[] FormulaErrorStrings

Field Value

Type
System.String[]

Remarks

If you want to change the error messages displayed within the Formula Engine, you can set your new strings into the appropriate position in the FormulaErrorStrings array. Here is the code that shows the default settings. You should assign your new strings to the corresponding positions.

Examples

Here is the code that shows position of each string in FormulaErrorStrings.

       public string[] FormulaErrorStrings = new string[]
       {
           "binary operators cannot start an expression",    //0
           "cannot parse",                                    //1
           "bad library",                                    //2
           "invalid char in front of",                        //3
           "number contains 2 decimal points",                //4
           "expression cannot end with an operator",        //5
           "invalid characters following an operator",        //6
           "invalid character in number",                    //7
           "mismatched parentheses",                        //8
           "unknown formula name",                            //9
           "requires a single argument",                    //10
           "requires 3 arguments",                            //11
           "invalid Math argument",                        //12
           "requires 2 arguments",                            //13
           "bad index",                                    //14
           "too complex",                                    //15
           "circular reference: ",                            //16
           "missing formula",                                //17
           "improper formula",                                //18
           "invalid expression",                            //19
           "cell empty",                                    //20
           "empty expression",                                //21
        "mismatched string tics",                        //22
        "named functions not supported in expressions",    //23
        "not a formula",                                //24
        "missing operand"                                //25
       };

number

Used for formatting and parsing numeric values

Declaration

public NumberFormatInfo number

Field Value

Type
System.Globalization.NumberFormatInfo

text

Gets the text properties and behaviors that are specific to the writing system.

Declaration

public TextInfo text

Field Value

Type
System.Globalization.TextInfo

Properties

Culture

Gets the culture information.

Declaration

public CultureInfo Culture { get; }

Property Value

Type
System.Globalization.CultureInfo

FunctionNames

A hash table whose keys are function names and whose values are LibraryFunction delegates.

Declaration

public Hashtable FunctionNames { get; }

Property Value

Type
System.Collections.Hashtable

MaximumRecursiveCalls

Specifies the maximum number of recursive calls that can be used to compute a value.

Declaration

public int MaximumRecursiveCalls { get; set; }

Property Value

Type
System.Int32

Remarks

This property comes into play when you have a calculated formula cell that depends on
another calculated formula that depends on another calculated formula and so on. If the number of 'depends on another formula' exceeds MaximumRecursiveCalls, you will see a Too Complex message displayed in the cell. The default value is 20, but you can set it higher or lower depending upon your expected needs. The purpose of the limit is to avoid a circular reference locking up your application.

Examples

This example shows how to use the MaximumRecursiveCalls property.

// Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel. 
ExpressionFieldEvaluator expression = new ExpressionFieldEvaluator(this.gridControl1.Model);
int call = expression.MaximumRecursiveCalls = 5;
Console.WriteLine("The maximum recursive calls allowed is   " + call);

' Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel. 
Dim expression As New ExpressionFieldEvaluator(Me.gridControl1.Model)
Dim[call] As Integer = expression.MaximumRecursiveCalls = 5
Console.WriteLine("The maximum recursive calls allowed is   " & [call])

Methods

AddFunction(String, ExpressionFieldEvaluator.LibraryFunction)

Adds a function to the Function Library.

Declaration

public bool AddFunction(string name, ExpressionFieldEvaluator.LibraryFunction func)

Parameters

Type	Name	Description
System.String	name	The name of the function to be added.
ExpressionFieldEvaluator.LibraryFunction	func	The function to be added.

Returns

Type	Description
System.Boolean	True if successfully added, False otherwise.

Remarks

LibraryFunction is a delegate the defines the signature of functions that you can add to the Function Library. Adding a custom function requires two steps. The first is to register a name and LibraryFunction delegate with the ExpressionFielEvaluator object. The second step is to add a method to your code that implements the LibraryFunction delegate to perform the calculations you want done.

There are restrictions on the use Functions within expressions. Functions can only be used stand-alone. They cannot be used as part of a more complex expression. So, "Func([Col1], 2*[Col2]+1)" is a valid use of a function named Func that accepts two arguments. But "2 * Func([Col1], 2*[Col2]+1) + 1" is not valid. If you need to use functions in algebraic expressions, then first add an Expression field that uses the function stand-alone. Then in your algebraic expression, you can refer to this Expression field. Argument used in library function calls, can be any algebraic combination of fields and constants, but they cannot contain function references. During calculations, the arguments are fully evaluated before being passed into the method you implement.

Examples

In the sample below, ComputeFunc is the name of the method we add to our code to compute the function value. Func is the string name that we use in an expression to reference the custom function as in "Func([Col1], [Col2])".

// step 1 - register the function name and delegate
ExpressionFieldEvaluator evaluator = this.groupingEngine.TableDescriptor.ExpressionFieldEvaluator;//.CreateExpressionFieldEvaluator(this.groupingEngine.TableDescriptor);
evaluator.AddFunction("Func", new ExpressionFieldEvaluator.LibraryFunction(ComputeFunc));

//. . . 

// step 1 - defining the method
// Computes the absolute value of arg1-2*arg2
  // parameter s- a list of 2 arguments 
// returns string holding computed value
public string ComputeFunc(string s)
{
   //get the list delimiter (for en-us, its is a comma)
   char comma = Convert.ToChar(this.gridGroupingControl1.Culture.TextInfo.ListSeparator);
   string[] ss = s.Split(comma);
   if(ss.GetLength(0) != 2)
       throw new ArgumentException("Requires 2 arguments.");
   double arg1, arg2;
   if(double.TryParse(ss[0], System.Globalization.NumberStyles.Any, null, out arg1)
       && double.TryParse(ss[1], System.Globalization.NumberStyles.Any, null, out arg2))
   {
       return Math.Abs(arg1 - 2 * arg2).ToString();
   }
   return "";
}

' step 1 - register the function name and delegate
Dim evaluator As ExpressionFieldEvaluator = Me.groupingEngine.TableDescriptor.ExpressionFieldEvaluator
evaluator.AddFunction("Func", New ExpressionFieldEvaluator.LibraryFunction(AddressOf ComputeFunc)) 

'. . .

' step 1 - defining the method
' Computes the absolute value of arg1-2*arg2
' parameter s- a list of 2 arguments 
' returns string holding computed value
Public Function ComputeFunc(s As String) As String
   'get the list delimiter (for en-us, its is a comma)
   Dim comma As Char = Convert.ToChar(Me.gridGroupingControl1.Culture.TextInfo.ListSeparator)
   Dim ss As String() = s.Split(comma)
   If ss.GetLength(0) <> 2 Then
          Throw New ArgumentException("Requires 2 arguments.")
   End If
    Dim arg1, arg2 As Double
   If Double.TryParse(ss(0), System.Globalization.NumberStyles.Any, Nothing, arg1) _ 
          AndAlso Double.TryParse(ss(1), System.Globalization.NumberStyles.Any, Nothing, arg2) Then
       Return Math.Abs((arg1 - 2 * arg2)).ToString()
   End If
   Return ""
End Function 'ComputeFunc

ComputeFormulaValueAt(String)

Compute values for the record of inner formulas.

Declaration

public string ComputeFormulaValueAt(string formula)

Parameters

Type	Name	Description
System.String	formula	The pre-compiled formula expression.

Returns

Type	Description
System.String	The resulting value.

Examples

This example shows how to compute the value of the given parsed value.

// Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel. 
ExpressionFieldEvaluator expression = new ExpressionFieldEvaluator(this.gridControl1.Model);
Parses the given valid string.
string parsedString = expression.Parse("=((8+6)*(2))");
Console.WriteLine("The parsed string from the given string is  " + parsedString);
// Computes the parsed given string into the required result.
parsedString = expression.ComputeFormulaValueAt(parsedString);
Console.WriteLine("The parsed string from the given string is  " + parsedString);

' Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
Dim expression As New ExpressionFieldEvaluator(Me.gridControl1.Model)
' Parses the given valid string.
Dim parsedString As String = expression.Parse("=((8+6)*(2))")
Console.WriteLine("The parsed string from the given string is  " & parsedString)
' Computes the parsed given string into the required result.
parsedString = expression.ComputeFormulaValueAt(parsedString)
Console.WriteLine("The parsed string from the given string is  " & parsedString)

ComputeFormulaValueAt(String, Int32, Int32)

Compute values for the record in the datasource.

Declaration

public string ComputeFormulaValueAt(string formula, int rowindex, int colindex)

Parameters

Type	Name	Description
System.String	formula	The pre-compiled formula expression.
System.Int32	rowindex	The row value of the record.
System.Int32	colindex	The column value of the record.

Returns

Type	Description
System.String	The resulting value.

Examples

This example shows how to compute the value at a specific cell index with the parsed string value.

void gridControl1_CellClick(object sender, GridCellClickEventArgs e)
{
   // Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
   ExpressionFieldEvaluator expression = new ExpressionFieldEvaluator(this.gridControl1.Model);
   this.gridControl1[e.RowIndex, e.ColIndex].CellValue = "=((8+6)*(2))";
   // Parses the given string at the specified cell index.
   string parsedFormula = expression.Parse(this.gridControl1[e.RowIndex, e.ColIndex].CellValue.ToString());
   // Computes the parsed given string into the required result.
   string parsedString = expression.ComputeFormulaValueAt(parsedFormula,e.RowIndex, e.ColIndex);
   Console.WriteLine("The parsed string from the given string is  " + parsedString);
}

Private Sub gridControl1_CellClick(ByVal sender As Object, ByVal e As GridCellClickEventArgs)
   ' Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
   Dim expression As New ExpressionFieldEvaluator(Me.gridControl1.Model)
   Me.gridControl1(e.RowIndex, e.ColIndex).CellValue = "=((8+6)*(2))"
   ' Parses the given string at the specified cell index.
   Dim parsedFormula As String = expression.Parse(Me.gridControl1(e.RowIndex, e.ColIndex).CellValue.ToString())
   ' Computes the parsed given string into the required result.
   Dim parsedString As String = expression.ComputeFormulaValueAt(parsedFormula,e.RowIndex, e.ColIndex)
   Console.WriteLine("The parsed string from the given string is  " & parsedString)
End Sub

ComputeFormulaValueAt(String, Int32, Int32, String)

Compute values for the record in the datasource.

Declaration

public string ComputeFormulaValueAt(string formula, int rowindex, int colindex, string expressionName)

Parameters

Type	Name	Description
System.String	formula	The pre-compiled formula expression.
System.Int32	rowindex	The row value of the record.
System.Int32	colindex	The column value of the record
System.String	expressionName	The name of the expression being computed.

Returns

Type	Description
System.String	The resulting value.

Examples

This example shows how compute the value of the parsed value with the given cell index and parsed value.

void gridControl1_CellClick(object sender, GridCellClickEventArgs e)
{
    // Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
    ExpressionFieldEvaluator expression = new ExpressionFieldEvaluator(this.gridControl1.Model);
    // The expression to be parsed.
    string expressionName = "=((8+6)*(2))";
    // The parsed value of the expression.
    string parsedValue = expression.Parse(expressionName);
    // The resultant value.
    string computedValue = expression.ComputeFormulaValueAt(parsedValue, e.RowIndex, e.ColIndex, expressionName);
    Console.WriteLine("The parsed string from the given string is  " + computedValue);
}

Private Sub gridControl1_CellClick(ByVal sender As Object, ByVal e As GridCellClickEventArgs)
    ' Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
    Dim expression As New ExpressionFieldEvaluator(Me.gridControl1.Model)
    ' The expression to be parsed.
    Dim expressionName As String = "=((8+6)*(2))"
    ' The parsed value of the expression.
    Dim parsedValue As String = expression.Parse(expressionName)
    ' The resultant value.
    Dim computedValue As String = expression.ComputeFormulaValueAt(parsedValue, e.RowIndex, e.ColIndex, expressionName)
    Console.WriteLine("The parsed string from the given string is  " & computedValue)
End Sub

GetValueFromDataTable(String)

Returns the value for the specified field / token from the record.

Declaration

public virtual string GetValueFromDataTable(string token)

Parameters

Type	Name	Description
System.String	token	The column token.

Returns

Type	Description
System.String	The value from the record.

InitializeTableFormulaTokens()

Loads item properties from the table descriptor and creates tokens that can be used in compiled expressions.

Declaration

public void InitializeTableFormulaTokens()

IsExpressionValid(String, String, out String)

Checks if an expression formula is valid for a particular host expression.

Declaration

public bool IsExpressionValid(string expressionFieldName, string formula, out string errorString)

Parameters

Type	Name	Description
System.String	expressionFieldName	The name of the host ExpressionFieldDescriptor.
System.String	formula	The formula.
System.String	errorString	Returns the error string, if any.

Returns

Type	Description
System.Boolean	True if formula is valid, false otherwise.

Parse(String)

Used to split the string

Declaration

public string Parse(string text)

Parameters

Type	Name	Description
System.String	text	Gets the string

Returns

Type	Description
System.String	Returns the parsed string.

Examples

This example shows how to use the Parse method.

// Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
ExpressionFieldEvaluator expression = new ExpressionFieldEvaluator(this.gridControl1.Model);
// Parses the given valid string.
string parsedString = expression.Parse("=((8+6)*(2))");
Console.WriteLine("The parsed string from the given string is  " + parsedString);

' Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
Dim expression As New ExpressionFieldEvaluator(Me.gridControl1.Model)
' Parses the given valid string.
Dim parsedString As String = expression.Parse("=((8+6)*(2))")
Console.WriteLine("The parsed string from the given string is  " & parsedString)

PutTokensInFormula(String)

Replaces column references with tokens.

Declaration

public string PutTokensInFormula(string formula)

Parameters

Type	Name	Description
System.String	formula	The formula expression.

Returns

Type	Description
System.String	A prepared expression string.

RemoveFunction(String)

Removes a function from the Function Library.

Declaration

public bool RemoveFunction(string name)

Parameters

Type	Name	Description
System.String	name	The name of the function to be removed.

Returns

Type	Description
System.Boolean	True if successfully removed, False otherwise.

Examples

This example shows how to remove the function with the specified Function name.

// Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
ExpressionFieldEvaluator expression = new ExpressionFieldEvaluator(this.gridControl1.Model);
// Removes the function from the library.
expression.RemoveFunction("Add");

' Creating the instances of the ExpressionFieldEvaluator and assigning the GridModel.
Dim expression As New ExpressionFieldEvaluator(Me.gridControl1.Model)
' Removes the function from the library.
expression.RemoveFunction("Add")

ToString()

Displays information on the cell currently being calculated.

Declaration

public override string ToString()

Returns

Type	Description
System.String	String with information on the cell currently being calculated.

Overrides

System.Object.ToString()