AlphaX.FormulaEngine 2.0.0

AlphaX.FormulaEngine

A strong and fast library to parse and evaluate formulas. It also supports custom formulas. This library is built using 'AlphaX.Parserz' library.

Using AlphaXFormulaEngine

For evaluating formulas using AlphaXFormulaEngine, you can simply initialize the engine and start using its Evaluate method:

AlphaX.FormulaEngine.AlphaXFormulaEngine engine = new AlphaX.FormulaEngine.AlphaXFormulaEngine();
AlphaX.FormulaEngine.IEvaluationResult result = engine.Evaluate("SUM(1,2,12.3,5.9099)");
Console.WriteLine(result.Value); // 21.2099

AlphaXFormulaEngine comes with a limited number (not many) of inbuilt formulas i.e.

• SUM - Returns sum of provided values. For example: SUM(1,2,4) // 7
• AVERAGE - Returns average of provided values. For example: AVERAGE(3,2,4) // 3
• LOWER - Returns lower cased string. For example: LOWER("TESTSTRING") // teststring
• UPPER - Returns upper cased string. For example: UPPER("teststring") // TESTSTRING
• TEXTSPLIT - Returns splitted string using a seperator. For example: TEXTSPLIT(".", "John.Doe") // John Doe
• TODAY - Returns system date. For example: TODAY() // 28-04-2023
• CONCAT - Joins multiple strings into one string: For example: CONCAT("Test","String","1") // TestString1
• NOW - Returns system date time // 28-04-2023 10:52:53 PM

Note : More formulas will be added in future updates.

Creating a Custom Formula

This is one of the best feature of AlphaXFormulaEngine. It provides you enough flexibility to write your own formula and easily integrate it with the engine.

1. Create a new MyFormula class which inherits from AlphaX.FormulaEngine.Formula class

public class MyFormula : AlphaX.FormulaEngine.Formula
{
        public MyFormula() : base("MyFormula")
        {
        }

        public override object Evaluate(params object[] args)
        {
            throw new NotImplementedException();
        }

        protected override FormulaInfo GetFormulaInfo()
        {
            throw new NotImplementedException();
        }
}

In the above code, the base() call accepts the name of the formula to be used in formula string.

2. Let's just say our formula will return a number raised to a power. For example. 2^2 = 4. So, we'll start by writing the code in the above evaluate method as follows:

public override object Evaluate(params object[] args)
{
            double result = 0;
            if (args.Length != 2)
            {
                double number = (double)args[0];
                double power = (double)args[1];
                result = Math.Pow(number, power);
            }
            return result;
}

3. We also need to provide some additional metadata for our formula using the GetFormulaInfo method as follows:

protected override FormulaInfo GetFormulaInfo()
{
    return new FormulaInfo("Returns the number raised to the power.", 2, 2,
        new FormulaArgument("number", typeof(double), true, 0, "The number"),
        new FormulaArgument("power", typeof(double), true, 1, "Power"));
}

The above code defines that our formula:

• Will have min/max 2 arguments.
• First argument is a number of type double, It is required and will be present at 0 index in formula arguments.
• Second argument is a number of type double, It is required and will be present at 1 index in formula arguments.

4. Now our formula is ready and the only thing left is to integrate it with the engine by using AlphaXFormulaEngine's AddFormula method as follows:

AlphaX.FormulaEngine.AlphaXFormulaEngine engine = new AlphaX.FormulaEngine.AlphaXFormulaEngine();
engine.AddFormula(new MyFormula());
AlphaX.FormulaEngine.IEvaluationResult result = engine.Evaluate("MyFormula(4,3)");
Console.WriteLine(result.Value); // 64

Customizing Engine Settings

AlphaXFormulaEngine allows you to customize the formula string format. By, default the formula format is :

FormulaName(argument1, argument2, argument3......)

However, you can customize this as per your needs. For example, you can change it to:

FormulaName[argument1 | argument 2 | argument 3....]

Doing this is a piece of cake using engine settings as follows:

AlphaX.FormulaEngine.AlphaXFormulaEngine engine = new AlphaX.FormulaEngine.AlphaXFormulaEngine();
engine.Settings.ArgumentsSeparatorSymbol = "|";
engine.Settings.OpenBracketSymbol = "[";
engine.Settings.CloseBracketSymbol = "]";
engine.Settings.Update();

engine.AddFormula(new MyFormula());
AlphaX.FormulaEngine.IEvaluationResult result = engine.Evaluate("MyFormula[4|3]");
Console.WriteLine(result.Value); // 64

Nested Formulas

To make your life easy, we have also added support for nested formulas. So, you can use a formula as a formula argument for another formula as follows:

AlphaX.FormulaEngine.IEvaluationResult result = engine.Evaluate("MyFormula(4, MyFormula(2,2))");
Console.WriteLine(result.Value); // 256

That's all of it 😃

Feedback is very much appreciated : https://forms.gle/dfv8E8zpC2qPJS7i7