ShYCalculator 0.9.3

ShYCalculator

ShYCalculator is a high-performance, thread-safe, and extensible mathematical expression evaluator for .NET, based on the Shunting-Yard algorithm.

Features

• 🚀 High Performance: Optimized for low allocation (Zero-Allocation paths where possible).
• 🧵 Thread Safe: Stateless execution model designed for high-concurrency environments (Web APIs, Services).
• 🧩 Extensible: Add custom functions, operators, and constants.
• 🏗️ Builder Pattern: Fluent API for easy configuration.
• 🛡️ Safe: No eval() or dynamic compilation risks; strictly parsed.
• 🔁 Compiled Mode: Parse once, execute many times for maximum performance.
• 📅 Date & Time: Robust support for date parsing, culture-specific formats, and time adjustments.
• 🌳 Deep Nesting: Supports complex nested expressions (ifs, ternaries, functions).

Quick Start

Installation

dotnet add package ShYCalculator

Basic Usage (Stateless / Thread-Safe)

Recommended for Web APIs or shared services.

var calculator = new ShYCalculatorBuilder()
    .WithAllExtensions()
    .Build();

var context = new Dictionary<string, double> {
    { "x", 10 },
    { "y", 20 }
};

var result = calculator.Calculate("x * y + sqrt(x)", context);
Console.WriteLine($"Result: {result.Value.Nvalue}"); // Output: 203.16...

Advanced Usage (Custom Functions)

var calculator = new ShYCalculatorBuilder()
    .WithMathematics()
    .WithConstant("TaxRate", 0.2)
    .Build();

var result = calculator.Calculate("100 * (1 + TaxRate)");

Dependency Injection

// Program.cs
builder.Services.AddShYCalculator(options => {
    options.WithAllExtensions();
});

// MyService.cs
public class MyService(ShYCalculator calculator) {
    public double CalculatePrice(double basePrice) {
        var context = new Dictionary<string, double> { { "basePrice", basePrice } };
        return calculator.Calculate("basePrice * 1.2", context).Value.Nvalue.Value;
    }
}

Compiled Mode (High Performance)

For scenarios where the formula is constant but variables change, use Compile to avoid reparsing.

var compiled = ShYCalculator.Compile("score * multiplier");
if (compiled.Success) {
    var runner = compiled.Value;
    var result = runner.Calculate(new Dictionary<string, double> { { "score", 100 }, { "multiplier", 1.5 } });
}

AST & Expression Validation

Retrieve the parsed AST for analysis or validate syntax without execution.

// AST
var result = calculator.Calculate("1 + 2 * 3", includeAst: true);
var nodeType = result.Ast?.Type; // "binary"

// Validation
var validation = ShYCalculator.Compile("1 + (2"); 
if (!validation.Success) Console.WriteLine(validation.Errors[0].Message);

License

Distributed under the MIT License. See LICENSE for more information.