NCalc.NetCore 1.0.1

NCalc.NetCore

NCalc.NetCore is a fast, lightweight, and extensible mathematical and logical expression evaluator for .NET.

Targeting .NET Standard 2.0, it runs seamlessly across modern .NET runtimes (.NET 6, 7, 8, 9, 10), .NET Core 2.0+, and .NET Framework 4.6.1+.

It allows developers to parse, compile, and dynamically evaluate expressions at runtime with parameter substitution, custom functions, vector operations, and high-performance in-memory caching.

Table of Contents

• Features
• Installation
• Quick Start
• Usage Guide
  • Basic Arithmetic & Calculations
  • Working with Parameters
  • Dynamic Parameters via Events
  • Custom Functions
  • Conditionals and Flow Control
  • Vector Evaluation (IterateParameters)
  • Syntax Checking and Error Handling
  • Data Types and Literals
  • Cache Management
  • Case Sensitivity
  • Rounding Options
• Reference Tables
  • Built-in Functions
  • Supported Operators
  • Evaluation Options
• Compatibility
• License & Credits

Features

• Full Mathematical Capabilities: Arithmetic operations, powers, roots, trigonometry, logarithms, and scientific notation.
• Precision Preservation: Smart numeric coercion supporting decimal, double, float, long, and int without silent loss of precision.
• Rich Boolean & Relational Logic: Short-circuit evaluation (&&, ||, and, or, not), comparisons (==, !=, <, <=, >, >=), and ternary logic (? :).
• Built-in Functions: Core mathematical functions plus control-flow functions like if(...) and membership test in(...).
• Dynamic Extensibility: Subscribe to EvaluateFunction and EvaluateParameter events to hook custom functions and resolve variables on demand.
• High Performance Caching: Automatic thread-safe parsed expression cache utilizing weak references to avoid redundant parsing overhead.
• Batch / Vector Operations: Evaluate an expression across arrays of parameters simultaneously with EvaluateOptions.IterateParameters.
• Pre-evaluation Syntax Checking: Validate expression grammar prior to execution using HasErrors().
• No External Dependencies (outside ANTLR): Lightweight and self-contained.

Installation

Install the package via NuGet:

.NET CLI

dotnet add package NCalc.NetCore

Package Manager Console

Install-Package NCalc.NetCore

PackageReference

<PackageReference Include="NCalc.NetCore" Version="1.0.1" />

Quick Start

using System;
using NCalc;

// 1. Simple arithmetic
var expr1 = new Expression("2 * (3 + 5)");
Console.WriteLine(expr1.Evaluate()); // 16

// 2. Parameters
var expr2 = new Expression("[radius] * [radius] * [pi]");
expr2.Parameters["radius"] = 5;
expr2.Parameters["pi"] = Math.PI;
Console.WriteLine(expr2.Evaluate()); // 78.5398...

// 3. Conditionals
var expr3 = new Expression("if(score >= 70, 'Passed', 'Failed')");
expr3.Parameters["score"] = 85;
Console.WriteLine(expr3.Evaluate()); // "Passed"

Usage Guide

Basic Arithmetic & Calculations

Standard operator precedence applies (parentheses, multiplication/division, addition/subtraction):

var expression = new Expression("1 + 2 + 3 * 4 / 2");
var result = expression.Evaluate(); // 9.0

Scientific notation is natively supported:

var expression = new Expression("1.22e1 + 1e2");
var result = expression.Evaluate(); // 112.2

Working with Parameters

Parameters can be enclosed in square brackets [parameter] or used directly by identifier name if they follow standard naming conventions:

var expr = new Expression("([UnitPrice] * [Quantity]) * (1 - [Discount])");
expr.Parameters["UnitPrice"] = 29.99m;
expr.Parameters["Quantity"] = 3;
expr.Parameters["Discount"] = 0.10m;

decimal total = (decimal)expr.Evaluate();

Nested Sub-expressions

Parameters can themselves be other Expression objects. They will be evaluated recursively:

var volumeExpr = new Expression("[Area] * [Height]");
var areaExpr = new Expression("[Width] * [Length]");

areaExpr.Parameters["Width"] = 5;
areaExpr.Parameters["Length"] = 10;

volumeExpr.Parameters["Area"] = areaExpr;
volumeExpr.Parameters["Height"] = 2;

Console.WriteLine(volumeExpr.Evaluate()); // 100

Dynamic Parameters via Events

If you have lazy-loaded or context-dependent variables that should only be fetched if the expression reaches them, subscribe to the EvaluateParameter event:

var expr = new Expression("if([UserIsAdmin], [SecretKey], 'Access Denied')");

expr.EvaluateParameter += (name, args) =>
{
    if (name == "UserIsAdmin")
    {
        args.Result = CurrentUser.IsAdmin();
    }
    else if (name == "SecretKey")
    {
        args.Result = Vault.GetSecretKey(); // Only evaluated if condition is true!
    }
};

var output = expr.Evaluate();

Custom Functions

Extend NCalc with your own business logic or custom domain methods using the EvaluateFunction event:

var expr = new Expression("SecretOperation(5, 10) + 1");

expr.EvaluateFunction += (name, args) =>
{
    if (string.Equals(name, "SecretOperation", StringComparison.OrdinalIgnoreCase))
    {
        int a = Convert.ToInt32(args.Parameters[0].Evaluate());
        int b = Convert.ToInt32(args.Parameters[1].Evaluate());

        args.Result = (a * b) + 42;
    }
};

Console.WriteLine(expr.Evaluate()); // (5 * 10) + 42 + 1 = 93

Note: args.Parameters[i] yields an Expression instance. This allows parameters to be evaluated lazily, avoiding redundant calculations if the function does not need all arguments.

Conditionals and Flow Control

if(condition, thenValue, elseValue)

Short-circuit evaluation is guaranteed: the inactive branch is not executed, preventing unintended side effects or division-by-zero exceptions.

var expr = new Expression("if([divider] != 0, [total] / [divider], 0)");
expr.Parameters["divider"] = 0;
expr.Parameters["total"] = 100;

Console.WriteLine(expr.Evaluate()); // 0 (no DivideByZeroException!)

Ternary Operator condition ? thenValue : elseValue

var expr = new Expression("score > 50 ? 'Pass' : 'Fail'");
expr.Parameters["score"] = 75;

Console.WriteLine(expr.Evaluate()); // "Pass"

in(value, item1, item2, ...)

Evaluates whether a value exists within a given sequence:

var expr = new Expression("in([status], 'Pending', 'InReview', 'Approved')");
expr.Parameters["status"] = "Approved";

Console.WriteLine(expr.Evaluate()); // true

Vector Evaluation (IterateParameters)

When calculating results over large arrays or data sets, enable EvaluateOptions.IterateParameters. NCalc will evaluate the compiled syntax tree across corresponding items in collections:

var expr = new Expression("[x] * [y]", EvaluateOptions.IterateParameters);
expr.Parameters["x"] = new[] { 1, 2, 3, 4, 5 };
expr.Parameters["y"] = new[] { 10, 20, 30, 40, 50 };

var results = (IList)expr.Evaluate();
// results contains: [10, 40, 90, 160, 250]

All IEnumerable parameters passed under this mode must contain the same number of elements.

Syntax Checking and Error Handling

You can validate expression syntax without executing the expression:

var expr = new Expression("2 * (5 +");

if (expr.HasErrors())
{
    Console.WriteLine($"Syntax Error: {expr.Error}");
}
else
{
    var result = expr.Evaluate();
}

If an invalid expression is evaluated directly, an EvaluationException is thrown:

try
{
    new Expression("4. + 2").Evaluate();
}
catch (EvaluationException ex)
{
    Console.WriteLine($"Evaluation failed: {ex.Message}");
}

Data Types and Literals

Date Comparisons

var expr = new Expression("#2026-10-22# >= #2026-01-01#");
Console.WriteLine(expr.Evaluate()); // true

String Concatenation

The + operator concatenates if either operand is a string:

var expr = new Expression("'Hello ' + [Name]");
expr.Parameters["Name"] = "World";
Console.WriteLine(expr.Evaluate()); // "Hello World"

Cache Management

NCalc automatically compiles expressions into an Abstract Syntax Tree (AST) and caches them in memory using WeakReference to maximize execution speed while avoiding memory leaks.

// Disable caching globally if needed:
Expression.CacheEnabled = false;

// Or disable cache for a single expression instance:
var expr = new Expression("2 + 2", EvaluateOptions.NoCache);

Case Sensitivity

By default, NCalc enforces case sensitivity for functions and parameters. Use EvaluateOptions.IgnoreCase to match case-insensitively:

var expr = new Expression("abs([MyParam])", EvaluateOptions.IgnoreCase);
expr.Parameters["myparam"] = -42;
Console.WriteLine(expr.Evaluate()); // 42

Rounding Options

Standard .NET Math.Round defaults to banker's rounding (round to nearest even). If you require arithmetic rounding away from zero (halfway rounded away from zero), pass EvaluateOptions.RoundAwayFromZero:

var expr = new Expression("Round(22.5, 0)", EvaluateOptions.RoundAwayFromZero);
Console.WriteLine(expr.Evaluate()); // 23 (instead of 22)

Reference Tables

Built-in Functions

Supported Operators

Evaluation Options

Available through the EvaluateOptions bitwise enum:

Compatibility

NCalc.NetCore targets .NET Standard 2.0, providing broad compatibility across runtimes:

• .NET (Modern): .NET 6.0, .NET 7.0, .NET 8.0, .NET 9.0, .NET 10.0+
• .NET Core: .NET Core 2.0, 2.1, 3.0, 3.1
• .NET Framework: .NET Framework 4.6.1, 4.6.2, 4.7.x, 4.8.x
• Mono / Xamarin / Unity: Any platform implementing .NET Standard 2.0.

License & Credits

This project is licensed under the terms of the MIT License.

Acknowledgments & Lineage

NCalc.NetCore is the product of continuous community development:

• Original NCalc: Created and developed by Sébastien Ros. Copyright © 2011 Sébastien Ros.
• NCalc-Edge: Forked and modernized by Peter Marx (pitermarx) and contributors. Copyright © 2016-2019 Peter Marx.
• NCalc-NetCore: Ported to .NET Core / .NET Standard by Alterdata Software and maintained by The Noobs. Copyright © 2017-2026 Alterdata Software, The Noobs and contributors.

All original copyrights and licenses are maintained in accordance with the MIT License requirements.