uCalcSoftware 5.7.1-preview.1

uCalc: The High-Performance Math Expression Evaluator and Token-Aware Text Transformation Engine

Homepage | Documentation | Online interactive examples | What's New | Release Notes | License

uCalc is a suite of three components: a Fast Math Parser, a token-aware text Transformer, and a String library. They are powered by the same underlying advanced parser engine and designed to seamlessly integrate for sophisticated operations. The uCalc SDK is backed by extensive online documentation with numerous interactive examples.

Use uCalc to build spreadsheet calculation engines, dynamic report generators, static analysis/code refactoring tools, linters, game scripting environments, custom domain-specific languages (DSLs), and to perform data extraction, complex string building, markup language conversion, and more.

• uCalc Fast Math Parser lets you evaluate math expressions defined at runtime. It comes with many functions and operators, and lets you define your own as well, either at runtime, or by attaching them to functions in your source code. You can call the simple Eval() to evaluate an expression right away, or parse the expression once and evaluate it many times in a loop at optimal speeds. uCalc is easy to use, yet very powerful.
• uCalc Transformer is a smart, token-aware engine for searching, replacing, and restructuring text. Use it to parse structured or unstructured text alike. Not limited to character units, it understands units of text like quoted strings, whitespace, nested brackets, user-defined comment structures, etc., and shines where regex falls short. It supports advanced rewrite rules, while also being designed for human readability to make it simple to use.
• uCalc String Library is a smart, mutable string manipulation library that offers you live views into strings for surgical in-place editing of different parts of the string, respecting structural boundaries (for instance it can distinguish between alphanumeric symbols, quoted text, etc., or user defined units of text), using the same underlying token-aware parser as the transformer. Methods can be chained together fluently for easy deployment.

Runtimes for Windows (x86, x64, and ARM64), Linux (x64 and ARM64), macOS (Intel osx-64 and osx-ARM64 Apple Silicon), are carefully packaged into the same NuGet library. This allows for immediate plug-and-play integration without the hassle of setting up platform-specific plumbing.

Quick Start

Fast Math Parser

using uCalcSoftware;

var uc = new uCalc();

// 1. Expression Parser: Evaluating a simple math or string expression
uc.DefineVariable("n = 10");
uc.DefineFunction("Area(length, width) = length * width");
Console.WriteLine(uc.Eval("5 * Area(n, 6) / 2")); // Output: 150

uc.DefineVariable("FirstName = 'John'");
Console.WriteLine(uc.EvalStr("UCase(FirstName) + ' Doe'")); // Output: JOHN Doe

// 2. Evaluate an expression faster in a loop
var myVar = uc.DefineVariable("x");
var expr = uc.Parse("x * 2");

for (double i = 1; i <= 5; i++) {
   myVar.Value(i);
   Console.WriteLine($"When x is {i} result is: {expr.Evaluate()}");
}
// Output:
// When x is 1, result is: 2
// ...
// When x is 5, result is: 10

Transformer

using uCalcSoftware;

// Transformer: Performing a basic find-and-replace to reformat a person's name
var t = new uCalc.Transformer();
t.FromTo("First Name: {first} [Middle Name: {middle}] Last Name: {last}", "Name: {last}, {first} {middle}");
Console.WriteLine(t.Transform("First Name: John-Paul    Last Name: Doe")); // Output: Doe, John-Paul
Console.WriteLine(t.Transform("First Name: John  Middle Name: Peter  Last Name: Doe")); // Output: Doe, John Peter

String Library

using uCalcSoftware;

// String Library: Using a fluent, chainable operation to modify a subsection of text in-place within a string
var log = new uCalc.String("INFO: File-handling task. ERROR: File not found.");
log.After("ERROR: ").Replace("File", "Resource");
Console.WriteLine(log); // Output: INFO: File-handling task. ERROR: Resource not found.

Practical example: Creating a JSON minifier that takes a formatted string and removes all non-essential whitespace

using uCalcSoftware;

var t = new uCalc.Transformer();

// 1. Define rules to remove whitespace and newlines.
// The engine's default QuoteSensitive=true ensures whitespace inside strings is protected.
t.FromTo("{@Whitespace}", "");
t.FromTo("{@Newline}", "");

// 2. Define the formatted input string.
var formattedJson = """

{
  "id": 123,
  "name": "Example, with spaces",
  "tags": [
    "A",
    "B"
  ]
}

""";

// 3. Run the transformation and print the result.
Console.WriteLine(t.Transform(formattedJson));
// Output: {"id":123,"name":"Example, with spaces","tags":["A","B"]}

Building an Equation Solver with the Parser and Transformer

using uCalcSoftware;

var uc = new uCalc();


static void EqSolveCb(uCalc.Callback cb) { // Callback based on the Bisection Method
   var expr = cb.ArgExpr(1);     // ByExpr: Unevaluated Expression object (lazy evaluation)
   var a = cb.Arg(2);            // Argument 2: Range Minimum
   var b = cb.Arg(3);            // Argument 3: Range Maximum
   var variable = cb.ArgItem(4); // ByHandle: The variable Item object

   // Helper to update the variable in the uCalc engine and evaluate the expression
   double EvaluateAt(double val) {
      variable.Value(val);   // Push the new test value to the variable
      return expr.Evaluate(); // Evaluate the pre-parsed expression
   }

   // Ensure f(a) < f(b) so we always know which direction to slide the bounds; swap a & b if necessary
   if (EvaluateAt(b) < EvaluateAt(a)) (a, b) = (b, a);

   var midpoint = 0.0;
   var fMidpoint = 0.0;

   // Bisection loop
   for (int i = 0; i <= 100; i++) {
      midpoint = (a + b) / 2;
      fMidpoint = EvaluateAt(midpoint);

      if (Math.Abs(fMidpoint) < 1e-7) break; // Stop if close enough to 0

      // Narrow the bounds (compact logic!)
      if (fMidpoint < 0) a = midpoint; else b = midpoint;
   }

   if (Math.Abs(fMidpoint) > 1e-5) cb.Error.Raise("No solution found in the given range.");
   cb.Return(Math.Round(midpoint, 7)); // Return the final solved value
}

// 1. Define variables that might be used by the end-user
uc.DefineVariable("x");
uc.DefineVariable("MyVar");

// 2. Transformer converts `EqSolve(L = R)` into `EqSolve(L - (R))` & sets defaults before it hits the parser
var t = uc.ExpressionTransformer;
t.FromTo("EqSolve({L} = {R} [[,]for {var}][, {min}, {max}])",
"EqSolve({L} - ({R}), {min}{!min:-10000}, {max}{!max: 10000}, {var}{!var: x})");

// 3. Define the custom function signature
uc.DefineFunction("EqSolve(ByExpr eq, min, max, ByHandle variable)", EqSolveCb);

// --- Demo Executions ---
System.Collections.Generic.List<string> eqList = new() {
   "EqSolve(x + 5 = 125)", // Using default range [-10000,10000]
   "EqSolve(x^2 + 5 = 105)", // Picks one result from the default range
   "EqSolve(x^2 + 5 = 105, 0, 100)", // Restricts to positive root
   "EqSolve(x^2 + 5 = 105, -100, 0)", // Restricts to negative root
   "EqSolve(x^2 + 1000 = 5)", // No existing solution
   "EqSolve(40 + MyVar * 6 = 88, for MyVar)" // Uses custom variable 'MyVar' instead of 'x'
};

foreach(var eq in eqList) {
   Console.WriteLine(uc.ExpressionTransformer.Transform(eq)); // Displays transformed expression
   Console.WriteLine($"Result: {uc.EvalStr(eq)}"); // Returns result
}

Current Status & Roadmap

The uCalc SDK has been successfully packaged for modern cross-platform environments. This Developer Preview allows you to evaluate the engine's token-aware architecture, explore the interactive documentation, and integrate early before General Availability (GA).

While the core logic relies on decades of mature development, this preview is a transitional build. To set proper expectations for production use, please note the current development roadmap:

• Performance Optimization: The Math Parser successfully targets modern compilers, but needs to undergo heavy re-optimization to match or exceed the extreme execution speeds of its legacy predecessors.

• Structural Refinement & API Stability: The Text Transformer is slated for a clean structural rewrite under the hood to bypass current limitations and natively support advanced Language Building capabilities. Additionally, the uCalc String Library is currently still in its active design phase. Expect notable breaking API changes, especially in the String Library, as final architectures are locked in.

Links

• Homepage
• Documentation
• What's New
• Release Notes
• Online interactive examples
• License