math / function / boolean /string expression evaluator

• Source and demo files VS2005 - 16 Kb
• Source and demo files VS2003 - 16.6 Kb

Introduction

I've come across several expression evaluators on this site. They utilize several clever ideas to implement them, but each of them had their "gotchas". I needed one that was flexible (handled more than one data type), that didn't compile code (too slow and wasted resources), that worked (one couldn't handle any unary operator), and could be easily adapted for other needs.

Thus, I've developed a set of simple classes called ExpressionEval and FunctionEval. These evaluators handle numeric, string, boolean, and datetime datatypes, and they support all the unary and binary operators available in C#. They also support functions (through the utilization of FunctionEval class) and have the ability to add custom functions by attaching an event handler that fires when a function name is not found.

About the project files

Included in the project zip(s) are the .cs files that implement regular expressions, expression evaluation, and function evaluation. Also included is a console based tester application that will allow you to enter and manually test particular expressions.

Simply select the version of the project (VS 2005 or 2003) from the versions above.

API

The API is really simple. You have two main classes: ExpressionEval, and FunctionEval. Both utilize each other to evaluate functions in an expression, or expressions in function parameters.

ExpressionEval has a default constructor and a special constructor to initialize the Expression property. Everything pretty much centers around the Expression property, the SetVariable and ClearVariable methods, the AdditionalFunctionEventHandler event, and the Evaluate() method. There are also some special evaluate methods (i.e. EvaluateBool()) that return a specific data type.

The first time Evaluate() is called, the object creates a graph of the expression to improve performance during subsequent calls of the Evaluate() method. However, if the Expression property changes, it will release the graph and form a new one the next time Evaluate() is called. Therefore, if you are using a consistent expression with changing values, use the SetVariable method so that it will not destroy the graph for the expression.

FunctionEval has a default constructor and a special constructor to initialize the Expression property. Calling Evaluate() will cause the object to find the first function in the Expression property and return its evaluation. Calling the static (or Shared in VB) Replace(string strInput) will cause the object to find all the functions in the input string, and replace them with their evaluations in the output (returned) string. (Note: I added a non-static parameter-less Replace() method that does the same thing, but it uses the Expression property as the source string.)

Both the ExpressionEval class and the FunctionEval class have a public event for handing custom functions. This event fires if a function name in the expression string has no built-in function associated. The event is named AdditionalFunctionEventHandler.

Expression strings

Expression strings are easy to construct. Standard operator precedence applies. (See C# documentation) Parenthesis work. The !, -, and ~ unary operators are functional. To call a function in the expression string use the following syntax: $functioname(param1, param2, ...).

To get a list of the built-in functions, look at the ExecuteFunction method in FunctionEval.cs.

Here are some examples of expression strings:

(1 + 1) * 17 / 3

$now() >= $today()

$pi() == $e()

"Today is " + $fmtdate($today(), "dddd, MMMM d, yyyy")

@(Variable1) == @(Variable2)

!true == false

• Valid unary operators: -, !, ~.
• Valid binary operators: *, /, %, +, -, <, <=, >, >=, == (also =), !=, &, ^, !, &&, ||.
• Parenthesis are evaluated first.
• E-notation (7.511E-10) is allowed for numbers and...
• Hexadecimal as well (0xaaf1).
• Expressions in the form @dt(mm/dd/yyyy hh:mm:ss (AM/PM)) will return a datetime datatype.
• Expressions in the form @ts([d.]h:m[:s[.ms]]) will return a timespan datatype. tokens in [] are optional.
• Expressions in the form @(VariableName) will attempt to look up a variable set by SetVariable.

Sample code

In the unit test project, you will see a lot of sample expressions. Here are some example codes for usage:

Construction and evaluation

ExpressionEval expr = new ExpressionEval("1+1");
object val = expr.Evaluate();

Creating a custom function handler

static void eval_AdditionalFunctionEventHandler(
      object sender, AdditionalFunctionEventArgs e)
{
    object[] parameters = e.GetParameters();
    switch (e.Name)
    {
        case "brent":   
            e.ReturnValue = "This Library Rocks!";
            break;

        case "liljohn": 
            e.ReturnValue = "WWWWWWWWHHHHHAT? YEAYAH! OKAY!";
            break;

        case "strcat":
            string ret = "";
            foreach (object parameter in parameters)
                ret += parameter.ToString();
            e.ReturnValue = ret;
            break;

        case "setvar":
            (sender as FunctionEval).SetVariable(
                "" + parameters[0],
                parameters[1]
            );
            break;
    }
}

Using the tester application

Make sure the tester application is set as the startup project. Hit F5 to build and run. You will see a blank console screen. Type in an expression and hit Enter. Its evaluation will appear below it, otherwise an error will be displayed. Type "clr" to clear the console, and type "exit" to quit the application.

Known issues

There is one issue that I am aware of. If you place two binary operators in a row, no error is returned. Instead, the first in the list is used, and the rest until the right operand (w/ or w/o unary operator) are ignored.

Example: (1 * + -1). This will ignore '+' and execute (1 * -1).

Note: I've improved the error handling to catch unused tokens and missing binary operators.

Updates

• 3/16/2006
  • Added timespan functionality and recognition: @ts([d].h:m[:s[.mmm]]). [] indicates optional components.
  • Added more robust error handling to catch unused tokens and missing binary operators.
• 12/30/2005
  • Completely updated the code libraries (and verified that it works with the release of VS2005 Pro) and description with bug fixes and modifications that I've been sending to those who had requested for it. Also updated the custom function handling event to .NET event standards. (with sender and eventarg params)
• 01/05/2005
  • Changed functionality so that upon first execution of an expression (with a created object, not the static (Shared) method), it parses it and creates a graph. As long as the Expression property is not changed, it will keep the graph and, subsequent calls to Evaluate() will not parse the expression, but re-execute the graph.
  • Also added a .NET 2003 ready .zip file.