Merge pull request #2 from miroiu/feature/math-expr

feat(StringMath): New API design

Author: miroiu

README.md

@@ -1,59 +1,103 @@
-# String Math [![NuGet](https://img.shields.io/nuget/v/StringMath?style=flat-square&logo=nuget)](https://www.nuget.org/packages/StringMath/) [![Downloads](https://img.shields.io/nuget/dt/StringMath?label=downloads&style=flat-square&logo=nuget)](https://www.nuget.org/packages/StringMath) ![.NET](https://img.shields.io/static/v1?label=%20&message=standard%202.0&color=5C2D91&style=flat-square&logo=.net) ![](https://img.shields.io/static/v1?label=%20&message=documentation&color=yellow&style=flat-square)
+# String Math [![NuGet](https://img.shields.io/nuget/v/StringMath?style=flat-square&logo=nuget)](https://www.nuget.org/packages/StringMath/) [![Downloads](https://img.shields.io/nuget/dt/StringMath?label=downloads&style=flat-square&logo=nuget)](https://www.nuget.org/packages/StringMath) ![.NET](https://img.shields.io/static/v1?label=%20&message=Framework%204.6.1%20to%20NET%206&color=5C2D91&style=flat-square&logo=.net) ![](https://img.shields.io/static/v1?label=%20&message=documentation&color=yellow&style=flat-square)
+
 Calculates the value of a math expression from a string returning a double.
 Supports variables and user defined operators.
 
-### Creating and using a calculator
 ```csharp
-ICalculator myCalculator = new Calculator();
-double result = myCalculator.Evaluate("1 * (2 - 3) ^ 2"); // 1
+double result = "1 * (2 - 3) ^ 2".Eval(); // 1
+```
+
+## Variables
+
+```csharp
+double result = "{a} + 2 * {b}".Substitute("a", 2).Substitute("b", 3).Result; // 8
+```
+
+### Global variables
+
+These variables are inherited and cannot be substituted.
+
+```csharp
+MathExpr.AddVariable("PI", 3.1415926535897931);
+double result = "1 + {PI}".Eval(); // 4.1415926535897931
+```
+
+## Custom operators
+
+### Global operators
+
+These operators are inherited and can be overidden.
+
+```csharp
+MathExpr.AddOperator("abs", a => a > 0 ? a : -a);
+double result = "abs -5".Eval(); // 5
+
+// Operator precedence (you can specify an int for precedence)
+MathExpr.AddOperator("max", (a, b) => a > b ? a : b, Precedence.Power);
+double result = new MathExpr("2 * 3 max 4").Result; // 8
+```
+
+### Local operators
+
+These are applied only to the target expression.
+
+```csharp
+MathExpr expr = "{PI} + 1";
+expr.SetOperator("+", (a, b) => Math.Pow(a, b));
+double result = expr; // 3.1415926535897931
 
-// Using custom operators
-myCalculator.AddOperator("abs", a => a > 0 ? a : -a);
-double result = myCalculator.Evaluate("abs -5"); // 5
+double result2 = "{PI} + 1".Eval(); // 4.1415926535897931
+```
 
-// Using custom operator precedence (you can specify an int for precedence)
-myCalculator.AddOperator("max", (a, b) => a > b ? a : b, Precedence.Power);
-double result = myCalculator.Evaluate("2 * 3 max 4"); // 8
+## Advanced
+
+### Extract variables
+
+```csharp
+var expr = "{a} + {b} + {PI}".ToMathExpr();
+var variables = expr.Variables;	// { "a", "b", "PI" }
+var localVariables = expr.LocalVariables; // { "a", "b" }
 ```
 
-### Creating and using variables
+### Conditional substitution
+
 ```csharp
-// Default variables collection is optional
-ICalculator myCalculator = new Calculator(new VariablesCollection
-{
-	["a"] = 5,
-	["PI"] = 3.1415926535897931
-});
-
-// Setting or creating variables
-myCalculator.SetValue("a", 2);
-myCalculator["b"] = 1;
-
-double result = myCalculator.Evaluate("{a} + 2 * {b} + {PI}"); // 7.1415926535897931
+MathExpr expr = "1 / {a}".Substitute("a", 1);
+
+double temp = expr.Result; // 1
+
+if (someCondition) 	// true
+	expr.Substitute("a", 2);
+
+double final = expr.Result; // 0.5
 ```
 
-### Creating and reusing operations
+### Sharing math context
+
 ```csharp
-myCalculator.SetValue("a", 5);
+MathExpr expr = "{PI} + 1";
+expr.SetOperator("+", (a, b) => Math.Pow(a, b));
 
-// Creating operations (expression tree is optimized and cached)
-OperationInfo op = myCalculator.CreateOperation("2 * {a}");
-double result1 = myCalculator.Evaluate(op); // 10
+MathExpr expr2 = "3 + 2".ToMathExpr(expr.Context);
 
-myCalculator["a"] = 3;
-// Reusing the operation (improved performance)
-double result2 = myCalculator.Evaluate(op); // 6
+double result = "1 + 2 + 3".Eval(expr.Context);
 ```
 
-### Using the static api: SMath
+### Custom math context
+
 ```csharp
-// Same API as a calculator instance
-double result = SMath.Evaluate("1 + 1"); // 2
-SMath.SetValue("myVar", 1);
-double result = SMath.Evaluate("1 + {myVar}", ); // 2
+var context = new MathContext();	// new MathContext(MathContext.Default); // to inherit from global
+context.RegisterBinary("+", (a, b) => Math.Pow(a, b));
+
+MathExpr expr = new MathExpr("{PI} + 1", context);
+MathExpr expr2 = "3 + 2".ToMathExpr(context);
+double result = "1 + 2 + 3".Eval(context);
 ```
 
-#### Default binary operators
+## Default operators
+
+### Binary
+
 ```csharp
 + (addition)
 - (subtraction)
@@ -66,14 +110,20 @@ max (maximum)
 min (minimum)
 ```
 
-#### Default unary operators
+### Unary
+
 ```csharp
 - (negation)
 ! (factorial)
 sqrt (square root)
-sin (sinus)
-cos (cosinus)
+sin (sine)
+asin (arcsine)
+cos (cosine)
+acos (arccosine)
 tan (tangent)
+atan (arctangent)
+rad (convert degrees to radians)
+deg (convert radians to degrees)
 ceil (ceiling)
 floor (floor)
 round (rounding)

StringMath.Expressions.Tests/ExpressionsTests.cs

@@ -0,0 +1,34 @@
+namespace StringMath.Expressions.Tests
+{
+    public class ExpressionsTests
+    {
+        [Theory]
+        [InlineData("5 * (3 + 2)", "5 * 3 + 5 * 2")]
+        [InlineData("5 * (3 - 2)", "5 * 3 - 5 * 2")]
+        [InlineData("5 * (-3 - 2)", "5 * -3 - 5 * 2")]
+        [InlineData("5 * -(-3 - 2)", "5 * 3 + 5 * 2")]
+        [InlineData("{a} * (3 + {b})", "{a} * 3 + {a} * {b}")]
+        [InlineData("{a} * (3 - {b})", "{a} * 3 - {a} * {b}")]
+        public void Expand(string input, string expected)
+        {
+            var actual = input.Expand();
+
+            Assert.Equal(expected, actual.Text);
+        }
+
+        [Theory]
+        [InlineData("5^2", "25")]
+        [InlineData("(5 - 2) * {a}", "3 * {a}")]
+        [InlineData("(-5 + 2) * {a}", "-3 * {a}")]
+        [InlineData("-(-5 + 2) * {a}", "3 * {a}")]
+        [InlineData("-(-5 + 1)", "4")]
+        [InlineData("-(-5 + -1)", "6")]
+        [InlineData("-{a} + 2", "-{a} + 2")]
+        public void Simplify(string input, string expected)
+        {
+            var actual = input.Simplify();
+
+            Assert.Equal(expected, actual.Text);
+        }
+    }
+}

StringMath.Expressions.Tests/StringMath.Expressions.Tests.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net6.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.1.0" />
+    <PackageReference Include="xunit" Version="2.4.1" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.3">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="coverlet.collector" Version="3.1.2">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\StringMath.Expressions\StringMath.Expressions.csproj" />
+    <ProjectReference Include="..\StringMath\StringMath.csproj" />
+  </ItemGroup>
+
+</Project>

StringMath.Expressions.Tests/Usings.cs

@@ -0,0 +1 @@
+global using Xunit;

StringMath.Expressions/Expand.cs

@@ -0,0 +1,82 @@
+namespace StringMath.Expressions;
+
+public static partial class Extensions
+{
+    public static Expr Expand(this Expr expr)
+    {
+        static Expr E(Expr e) => e switch
+        {
+            // 5 * (a + b) => 5 * a + 5 * b
+            Mul(Number num, Sum sum) => num * E(sum.Left) + num * E(sum.Right),
+
+            // (a + b) * 5 => 5 * a + 5 * b
+            Mul(Sum sum, Number num) => num * E(sum.Left) + num * E(sum.Right),
+
+            // (a - b) * 5 => 5 * a - 5 * b
+            Mul(Number num, Diff diff) => num * E(diff.Left) - num * E(diff.Right),
+
+            // 5 * (a - b) => 5 * a - 5 * b
+            Mul(Diff diff, Number num) => num * E(diff.Left) - num * E(diff.Right),
+
+            // c * (a + b) => c * a + c * b
+            Mul(Variable num, Sum sum) => num * E(sum.Left) + num * E(sum.Right),
+
+            // (a + b) * c => c * a + c * b
+            Mul(Sum sum, Variable num) => num * E(sum.Left) + num * E(sum.Right),
+
+            // c * (a - b) => c * a - c * b
+            Mul(Variable num, Diff diff) => num * E(diff.Left) - num * E(diff.Right),
+
+            // (a - b) * c => c * a - c * b
+            Mul(Diff diff, Variable num) => num * E(diff.Left) - num * E(diff.Right),
+
+            // -a * -b => a * b
+            Mul(Neg(Expr a), Neg(Expr b)) => E(a) * E(b),
+
+            // -(a - b) => -a + b
+            Neg(Neg(Expr a)) => E(a),
+
+            // -(a - b) => -a + b
+            Neg(Diff(Expr a, Expr b)) => -E(a) + E(b),
+
+            // -(a + b) => -a - b
+            Neg(Sum(Expr a, Expr b)) => -E(a) - E(b),
+
+            // -a / -b => a / b
+            Div(Neg(Expr a), Neg(Expr b)) => E(a) * E(b),
+
+            // x^(m + n) => x^m * x^n
+            Pow(Expr x, Sum(Expr m, Expr n)) => (E(x) ^ E(m)) * (E(x) ^ E(n)),
+
+            // x^(m - n) => x^m / x^n
+            Pow(Expr x, Diff(Expr m, Expr n)) => (E(x) ^ E(m)) / (E(x) ^ E(n)),
+
+            // (x^m)^n => x^(m*n)
+            Pow(Pow(Expr x, Expr m), Expr n) => E(x) ^ (E(m) * E(n)),
+
+            // (x/y)^-m => (y/x)^m
+            Pow(Div(Expr x, Expr y), Neg(Expr m)) => (E(y) / E(x)) ^ E(m),
+
+            // (x*y)^m => x^m & y^m
+            Pow(Mul(Expr x, Expr y), Expr m) => (E(x) ^ E(m)) * (E(y) ^ E(m)),
+
+            // (x/y)^m => x^m / y^m
+            Pow(Div(Expr x, Expr y), Expr m) => (E(x) ^ E(m)) / (E(y) ^ E(m)),
+
+            // x^-m => 1 / x^m
+            Pow(Expr x, Neg(Expr m)) => 1 / (E(x) ^ E(m)),
+
+            // x^2 => x * x
+            Pow(Expr x, Number(2)) => E(x) * E(x),
+
+            // generic
+            Binary(Expr a, string op, Expr b) => SMath.Binary(E(a), op, E(b)),
+            Unary(Expr a, string op) => SMath.Unary(E(a), op),
+
+            _ => e
+        };
+
+        return E(expr);
+    }
+}
+

StringMath.Expressions/Expr.cs

@@ -0,0 +1,47 @@
+namespace StringMath.Expressions;
+
+public record Expr
+{
+    public static Mul operator *(Expr left, Expr right) => new(left, right);
+    public static Div operator /(Expr left, Expr right) => new(left, right);
+    public static Sum operator +(Expr left, Expr right) => new(left, right);
+    public static Diff operator -(Expr left, Expr right) => new(left, right);
+    public static Pow operator ^(Expr left, Expr right) => new(left, right);
+    public static Mod operator %(Expr left, Expr right) => new(left, right);
+    public static Neg operator -(Expr operand) => new(operand);
+
+    public static implicit operator Expr(double value) => new Number(value);
+    public static implicit operator Expr(string value) => value.ToExpr();
+}
+
+public record Variable(string Name) : Expr
+{
+    public static implicit operator string(Variable var) => var.Name;
+    public static implicit operator Variable(string name) => new(name);
+}
+
+public record Number(double Value) : Expr
+{
+    public static implicit operator Number(double val) => new(val);
+    public static implicit operator double(Number num) => num.Value;
+}
+public record Binary(Expr Left, string Op, Expr Right) : Expr;
+public record Unary(Expr Value, string Op) : Expr;
+
+public record Neg(Expr Value) : Unary(Value, "-");
+public record Factorial(Expr Value) : Unary(Value, "!");
+public record Sin(Expr Value) : Unary(Value, "sin");
+public record Cos(Expr Value) : Unary(Value, "cos");
+public record Abs(Expr Value) : Unary(Value, "abs");
+public record Sqrt(Expr Value) : Unary(Value, "sqrt");
+public record Tan(Expr Value) : Unary(Value, "tan");
+public record Atan(Expr Value) : Unary(Value, "atan");
+public record Exp(Expr Value) : Unary(Value, "exp");
+
+public record Sum(Expr Left, Expr Right) : Binary(Left, "+", Right);
+public record Diff(Expr Left, Expr Right) : Binary(Left, "-", Right);
+public record Mul(Expr Left, Expr Right) : Binary(Left, "*", Right);
+public record Div(Expr Left, Expr Right) : Binary(Left, "/", Right);
+public record Pow(Expr Left, Expr Right) : Binary(Left, "^", Right);
+public record Mod(Expr Left, Expr Right) : Binary(Left, "%", Right);
+public record Log(Expr Left, Expr Right) : Binary(Left, "log", Right);