uCalcSoftware.Cpp 5.7.1-preview.4

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

#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;

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

   uc.DefineVariable("FirstName = 'John'");
   cout << uc.EvalStr("UCase(FirstName) + ' Doe'") << endl; // Output: JOHN Doe

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

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

}

Transformer

#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

}

String Library

#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   // String Library: Using a fluent, chainable operation to modify a subsection of text in-place within a string
   uCalc::String log("INFO: File-handling task. ERROR: File not found.");
   log.After("ERROR: ").Replace("File", "Resource");
   cout << log << endl; // 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

#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc::Transformer t;

   // 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.
   auto formattedJson = R"(
{
  "id": 123,
  "name": "Example, with spaces",
  "tags": [
    "A",
    "B"
  ]
}
)";

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

}

Building an Equation Solver with the Parser and Transformer

#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   // Helper to update the variable in the uCalc engine and evaluate the expression
   auto EvaluateAt = [&](double val) -> double {
      variable.Value(val);
      return expr.Evaluate();
   };

   // 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)) swap(a, b);

   auto midpoint = 0.0;
   auto fMidpoint = 0.0;

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

      if (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 (abs(fMidpoint) > 1e-5) cb.Error().Raise("No solution found in the given range.");
   cb.Return(round(midpoint * 10000000.0) / 10000000.0); // Return the final solved value
}
int main() {
   uCalc uc;
   // 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
   auto 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 ---
   vector<string> eqList = {
      "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'
   };

   for(auto eq : eqList) {
      cout << uc.ExpressionTransformer().Transform(eq) << endl; // Displays transformed expression
      cout << "Result: " << uc.EvalStr(eq) << endl; // 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