NCalc

NCalc is a mathematical expressions evaluator in .NET. NCalc can parse any expression and evaluate the result, including static or dynamic parameters and custom functions.

Project Description

NCalc is a .NET library for evaluating mathematical expressions. It can handle various types of expressions, including those with static or dynamic parameters, as well as custom functions. It is supported by any target framework that accommodates .NET Standard 2.0.

For additional information on the technique we used to create this framework please read this article: https://www.codeproject.com/Articles/18880/State-of-the-Art-Expression-Evaluation.

For documentation here is the table of content:

• description: overall concepts, usage and extensibility points
• operators: available standard operators and structures
• values: authorized values like types, functions, ...
• functions: list of already implemented functions
• parameters: on how to use parameters expressions

Important

If you need help, please open an issue and include the expression to help us better understand the problem. Providing this information will aid in resolving the issue effectively.

Functionalities

Simple Expressions

Expression e = new Expression("2 + 3 * 5");
Debug.Assert(17 == e.Evaluate());

Evaluates .NET data types

Debug.Assert(123456 == new Expression("123456").Evaluate()); // integers
Debug.Assert(new DateTime(2001, 01, 01) == new Expression("#01/01/2001#").Evaluate()); // date and times
Debug.Assert(123.456 == new Expression("123.456").Evaluate()); // floating point numbers
Debug.Assert(true == new Expression("true").Evaluate()); // booleans
Debug.Assert("azerty" == new Expression("'azerty'").Evaluate()); // strings

Handles mathematical functional from System.Math

Debug.Assert(0 == new Expression("Sin(0)").Evaluate());
Debug.Assert(2 == new Expression("Sqrt(4)").Evaluate());
Debug.Assert(0 == new Expression("Tan(0)").Evaluate());

Evaluates custom functions

Expression e = new Expression("SecretOperation(3, 6)");
e.EvaluateFunction += delegate(string name, FunctionArgs args)
    {
        if (name == "SecretOperation")
            args.Result = (int)args.Parameters[0].Evaluate() + (int)args.Parameters[1].Evaluate();
    };

Debug.Assert(9 == e.Evaluate());

Handles unicode characters

Debug.Assert("経済協力開発機構" == new Expression("'経済協力開発機構'").Evaluate());
Debug.Assert("Hello" == new Expression(@"'\u0048\u0065\u006C\u006C\u006F'").Evaluate());
Debug.Assert("だ" == new Expression(@"'\u3060'").Evaluate());
Debug.Assert("\u0100" == new Expression(@"'\u0100'").Evaluate());

Define parameters, even dynamic or expressions

Expression e = new Expression("Round(Pow([Pi], 2) + Pow([Pi2], 2) + [X], 2)");

e.Parameters["Pi2"] = new Expression("Pi * [Pi]");
e.Parameters["X"] = 10;

e.EvaluateParameter += delegate(string name, ParameterArgs args)
  {
    if (name == "Pi")
    args.Result = 3.14;
  };

Debug.Assert(117.07 == e.Evaluate());

Caching in a distributed cache

This example uses Newtonsoft.Json.

Serializing

var compiled = Expression.Compile(expression, true);
var serialized = JsonConvert.SerializeObject(compiled, new JsonSerializerSettings
{
    TypeNameHandling = TypeNameHandling.All // We need this to allow serializing abstract classes
});

Deserializing

var deserialized = JsonConvert.DeserializeObject<LogicalExpression>(serialized, new JsonSerializerSettings
{
    TypeNameHandling = TypeNameHandling.All
});

Expression.CacheEnabled = false; // We cannot use NCalc's built in cache at the same time.
var exp = new Expression(deserialized);
exp.Parameters = new Dictionary<string, object> {
    {"waterlevel", inputValue}
};

var evaluated = exp.Evaluate();

Related projects

NCalc-Async

Pure asynchronous implementation of NCalc by Peter Liljenberg.

PanoramicData.NCalcExtensions

Extension functions for NCalc to handle many general functions,
including string functions, switch, if, in, typeOf, cast etc.
Developed by David, Dan and all at Panoramic Data.

Jint

Javascript Interpreter for .NET by Sébastien Ros, the author of NCalc library.
Runs on any modern .NET platform as it supports .NET Standard 2.0 and .NET 4.6.1 targets (and up).

NCalcJS

A Typescript/Javascript port of NCalc.

NCalc101

NCalc 101 is a simple web application that allows you to try out the NCalc expression evaluator, developed by Panoramic Data.

JJMasterData.NCalc

Plugin of NCalc to JJMasterData, a runtime form generator from database metadata.

NCalc versioning

The project uses Nerdbank.GitVersioning tool to manage versions.
Each library build can be traced back to the original git commit.

Preparing and publishing a new release

1. Make sure that nbgv dotnet CLI tool is installed and is up-to-date
2. Run nbgv prepare-release to create a stable branch for the upcoming release, i.e. release/v1.0
3. Switch to the release branch: git checkout release/v1.0
4. Execute unit tests, update the README, release notes in csproj file, etc. Commit and push your changes.
5. Run dotnet pack -c Release and check that it builds Nuget packages with the right version number.
6. Run nbgv tag release/v1.0 to tag the last commit on the release branch with your current version number, i.e. v1.0.7.
7. Push tags as suggested by nbgv tool: git push origin v1.0.7
8. Go to GitHub project page and create a release out of the last tag v1.0.7.
9. Verify that github workflow for publishing the nuget package has completed.
10. Switch back to master and merge the release branch.