NoStringEvaluating

NoStringEvaluating copied to clipboard

Fast low memory consuming mathematical evaluation without endless string parsing! Parses string formula once and uses its object sequence in each evaluation. Moreover provides user defined functions and variables.

Microsoft.Extensions.DependencyInjection

Quick Links

• Features
• Performance
  • Testing formulas
  • 1 000 000 calculations
  • Benchmark results
  • Conclusion
• Quick start
  • Initialization
  • Usage
  • User defined functions
• Extra types
  • List description
• Variables
  • Simple variable
  • Bordered variable
  • Precompiled variables
• Operators
• Boolean operators
• Functions
  • Math
  • Trigonometry
  • Logic
  • Excel
    • DateTime
    • Word
  • Null
• Options
• Documentation
  • IFormulaParser
  • IFunctionReader
  • IFormulaCache
  • IFormulaChecker
  • IVariablesContainer
  • IFunction
  • NoStringEvaluatorOptions
  • INoStringEvaluator
  • INoStringEvaluatorNullable
  • NoStringEvaluator
  • NoStringEvaluatorNullable
• Thanks for contribution :octocat:
• TODO

Features

• Fast math evaluation
• Zero-allocation code (object pooling)
• User defined functions
• User defined variables with any chars
• Mixed result type

Performance

Compared with a good solution mXparser

• In general, x5 faster!

Testing formulas

1 000 000 calculations

Less is better

Benchmark results

Conclusion

As you can see this solution is faster in all cases, furthermore there isn't any garbage collection.

Benchmark code - ConsoleApp/Benchmark/BenchmarkNumberService.cs

Benchmark excel - BenchResults/Benchmark.xlsx

Quick start

Initialization

There are two ways to use evaluator:

1. Static initialization

public void SomeMethod()
{
    var facade = NoStringEvaluator.CreateFacade();
    var evaluator = facade.Evaluator;
}

2. DI from the package

public void ConfigureServices(IServiceCollection services)
{
    // ......
    services.AddNoStringEvaluator();
}

Usage

Add INoStringEvaluator to your controller, service, etc...

And just send string or FormulaNodes to evaluation:

public class MyService
{
    private INoStringEvaluator _noStringEvaluator;

    public MyService(INoStringEvaluator noStringEvaluator)
    {
        _noStringEvaluator = noStringEvaluator;
    }

    public double CalcNumber(string formula)
    {
        return _noStringEvaluator.CalcNumber(formula);
    }
    
    public string CalcWord(string formula)
    {
        return _noStringEvaluator.CalcWord(formula);
    }
    
    public EvaluatorValue Calc(string formula)
    {
        return _noStringEvaluator.Calc(formula);
    }
}

If you have variables, you can send IDictionary or your IVariablesContainer implementation:

public class MyService
{
    private INoStringEvaluator _noStringEvaluator;

    public MyService(INoStringEvaluator noStringEvaluator)
    {
        _noStringEvaluator = noStringEvaluator;
    }

    public double Calc(string formula, IDictionary<string, EvaluatorValue> variables)
    {
        return _noStringEvaluator.CalcNumber(formula, variables);
    }
}

User defined functions

If you need your function, just implement the interface IFunction If you want to returnt extra type, use factory.

As an argument's separator can be:

• ;
• ,

For instance, usage function "YouAre('Vitaly'; 26)":

public class MyFunction : IFunction
{
    public string Name { get; } = "YouAre";

    public bool CanHandleNullArguments { get; }

    public InternalEvaluatorValue Execute(List<InternalEvaluatorValue> args, ValueFactory factory)
    {
        var name = args[0].Word;
        var age = args[1];

        var ageAfterDecade = age + 10;
        var result = $"Hello, {name}. After 10 years you will be {ageAfterDecade} y.o.";

        return factory.Word.Create(result);
    }
}

And don't forget to initialize your functions via options or directly in IFunctionReader

public void SomeMethod()
{
    // NoStringEvaluator.CreateFacade(opt => opt.WithFunctionsFrom(<type from source assembly>));
    // NoStringEvaluator.CreateFacade(opt => opt.WithFunctionsFrom(<source assembly>));
    // NoStringEvaluator.CreateFacade(opt => opt.WithFunctions(new MyFunction()));

    // same with DI
    // services.AddNoStringEvaluator(opt => opt.WithFunctions(new MyFunction()));
}

Extra types

Apart from double calculations you can work with types:

• Boolean
• DateTime
• String
• List of string
• List of double
• Null
• Object

Object is a special type to allow using, for example, services inside function.

public void Should_Evaluate_Service()
{
    // arrange
    var service = _serviceFactory(null);
    var args = new Dictionary<string, EvaluatorValue>
    {
        ["myService"] = new EvaluatorValue(new MyService()),
        ["myNum"] = 10
    };
    var expected = 50.5;

    // act
    var actual = service.CalcNumber("TestService(myService; myNum)", args);

    // assert
    actual.Should().BeApproximatelyNumber(expected);
}

private class ServiceFunction : IFunction
{
    public string Name { get; } = "TestService";

    public bool CanHandleNullArguments { get; }

    public InternalEvaluatorValue Execute(List<InternalEvaluatorValue> args, ValueFactory factory)
    {
        return args[0].GetObject<MyService>().GetTemperature() + args[1];
    }
}

private class MyService
{
    public double GetTemperature()
    {
        return 40.5;
    }
}

List description

You can describe a list inside the formula

Variables

You can use two types of variables:

• Simple variable
• Bordered variable

Simple variable

Simple variable means that it named without unique symbols and starts with a letter. Only one extra symbol is possible, it's "_"

Some examples:

• "25 + myArgument - 1"
• "25 + myArg1 - 2"
• "arg5684argArg_arg"
• "25 + myArgument_newAge - 3"

Bordered variable

Bordered variable means that it has a tricky name with any symbols, except for square brackets.

Some examples:

• "25 + [myVariable and some words] - 1"
• "25 + [Provider("my provider").Month(1).Price] - 2"
• "[myVariable ♥]"
• "[simpleVariable]"

Needless to say, you can write simple variable with brackets as well.

Precompiled variables

There are some known variables, you shouldn't send them to Calc method.

These variables are register independent, you can write Pi, [PI], pI, True, etc...

Operators

Boolean operators

Functions

Math

Trigonometry

Logic

Excel

I've implemented some of excel functions. If you wanna see more, just send me a message.

DateTime

Word

Null

Options

When you use AddNoStringEvaluator or CreateFacade you can configure evaluator.

To illustrate, I change floating point from default dot to comma:

public void ConfigureServices(IServiceCollection services)
{
    // ......
    services.AddNoStringEvaluator(opt => opt.SetFloatingPointSymbol(FloatingPointSymbol.Comma));
}

Documentation

IFormulaParser

IFunctionReader

IFormulaCache

IFormulaChecker

IVariablesContainer

IFunction

NoStringEvaluatorOptions

INoStringEvaluator

INoStringEvaluatorNullable

Referenced methods are same as in INoStringEvaluator

NoStringEvaluator

Static initialization if you don't have DI

NoStringEvaluatorNullable

Static initialization if you don't have DI

Thanks for contribution

:octocat: IvoTops

TODO

• Add more functions
• Any idea?