NoStringEvaluating.Extensions.Microsoft.DependencyInjection 1.0.2

NoStringEvaluating

Fast and easy 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. From v2.0 it can evaluate string, DateTime, etc...

Microsoft.Extensions.DependencyInjection

• Features
• Performance
  • Testing formulas
  • 1 000 000 calculations
  • Benchmark results
  • Conclusion
• Quick start
  • Initializing
  • 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
• Options
• Documentation
  • IFormulaParser
  • IFunctionReader
  • IFormulaCache
  • IFormulaChecker
  • INoStringEvaluator
• 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, x7 faster!

Testing formulas

1 000 000 calculations

Less is better

Benchmark results

NoStringEvaluator

MxParser

Both

Conclusion

As you can see, this solution faster in all cases, what's more, there isn't any garbage collection.

Benchmark code you can find in ConsoleApp.Benchmark.BenchmarkNumberService.

Benchmark excel sheet you can find here - BenchResults.Benchmark.xlsx.

Quick start

Initializing

Basically, this solution has developed for web api projects, so you should add implementations in Startup.cs:

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.

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

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

    public InternalEvaluatorValue Execute(List<InternalEvaluatorValue> args, ValueFactory factory)
    {
        var name = args[0].GetWord();
        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 add this function to IFunctionReader

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...
    var functionReader = app.ApplicationServices.GetRequiredService<IFunctionReader>();
    functionReader.AddFunction(new MyFunction());

    // If you don't want to write the each function directly, use this:
    // Just send type from assembly where you have functions
    // NoStringFunctionsInitializer.InitializeFunctions(functionReader, typeof(Startup));
}

Extra types

From v2.0 you can evaluate some of types. I strongly recommend, if you know a function's result type, use method kinda CalcNumber or CalcWord. For case if you have no idea about a result's type, use Calc. It returns struct with aggregated types. Just look at property TypeKey and you'll know about a type.

List description

From v2.1 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 difficult 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

Options

When you use AddNoStringEvaluator in startup.cs you can configure evaluator.

There are several options:

• FloatingTolerance (default is 0.0001)
• FloatingPointSymbol (default is FloatingPointSymbol.Dot)
• WordQuotationMark (default is null)

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

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

Documentation

Solution contains five following services:

• IFormulaParser
• IFunctionReader
• IFormulaCache
• IFormulaChecker
• INoStringEvaluator

One optional interface, you can implement if IDictionary is inconvenient.

• IVariablesContainer

Furthermore, three object pools:

• ObjectPool.Create<Stack<InternalEvaluatorValue>>
• ObjectPool.Create<List<InternalEvaluatorValue>>
• ObjectPool.Create<ExtraTypeIdContainer>

IFormulaParser

Performs two functions:

• Parsing from char collection to object sequence
• Reversing sequence as Reverse Polish notation

Contains three methods:

• FormulaNodes Parse(string formula)
• FormulaNodes Parse(ReadOnlySpan<char> formula)
• List<IFormulaNode> ParseWithoutRpn(ReadOnlySpan<char> formula)

IFunctionReader

Performs using user defined functions.

Contains three methods:

• void AddFunction(IFunction func, bool replace = false)
• void RemoveFunction(string functionName)
• bool TryProceedFunction(List<IFormulaNode> nodes, ReadOnlySpan<char> formula, ref int index)

IFormulaCache

Performs formula caching. It is used by default INoStringEvaluator implementation. It uses IFormulaParser which parses string formula to object sequence.

Contains one method:

• FormulaNodes GetFormulaNodes(string formula)

IFormulaChecker

Performs syntax checking.

Contains two methods:

• CheckFormulaResult CheckSyntax(string formula)
• CheckFormulaResult CheckSyntax(ReadOnlySpan<char> formula)

INoStringEvaluator

Performs evaluating ☺️

Contains methods:

• double CalcNumber(string formula, IVariablesContainer variables)
• double CalcNumber(FormulaNodes formulaNodes, IVariablesContainer variables)
• double CalcNumber(string formula, IDictionary<string, EvaluatorValue> variables)
• double CalcNumber(FormulaNodes formulaNodes, IDictionary<string, EvaluatorValue> variables)
• double CalcNumber(string formula)
• double CalcNumber(FormulaNodes formulaNodes)
• string CalcWord(...
• DateTime CalcDateTime(...
• List<string> CalcWordList(...
• List<double> CalcNumberList(...
• bool CalcBoolean(...
• EvaluatorValue Calc(...

TODO

• Add more functions
• Any idea?