uCalc API Version: 2.1.3-preview.2 Released: 6/16/2026

Warning

uCalc API Preview Release Notice:The documentation describes the intended behavior of the API. The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.

uCalc SDK

Product: 

Class: 

An overview of the uCalc SDK, a powerful toolkit for expression evaluation, text transformation, and high-performance string manipulation.

Remarks

🚀 The uCalc SDK: A Unified Toolkit for Parsing and Transformation

The uCalc SDK is a suite of three powerful, integrated components designed for everything from evaluating simple math expressions to performing complex, rule-based text transformations. It provides ready-to-use tools for common tasks while offering the extensibility to build sophisticated parsers, custom Domain-Specific Languages (DSLs), and dynamic evaluation engines when you need more power.

This overview introduces the three pillars of the uCalc SDK and explains how their integration provides capabilities far beyond what each component can do alone.

1. ⚡ The Expression Parser

At its core is the uCalc Fast Math Parser, a high-performance engine for evaluating mathematical, logical, and string-based expressions. It's more than a simple calculator; it's a dynamic language environment that you can extend at runtime by defining new functions and operators. Its "Parse-Once, Evaluate-Many" architecture ensures near-native performance in loops.

  • Use Case: Financial modeling, scientific computing, game scripting, report generation.

2. 🧠 The Transformer

The uCalc Transformer is an intelligent, token-aware engine for find-and-replace operations. Unlike character-based Regular Expressions, the Transformer understands the structure of your text, making it a safer and more powerful tool for tasks like code refactoring, static analysis, or transpiling one language to another. It uses a declarative, readable pattern syntax to define its rules.

  • Use Case: Code refactoring, building linters, data extraction, markup language conversion.

3. ✨ The String Library

The uCalc.String class is a mutable, high-performance string object designed for fluent, chainable text manipulation. It operates on a "live view" model, where operations on substrings directly modify the parent string in-place. It combines the efficiency of a StringBuilder with a lightweight, token-aware search and replace API, making it ideal for concise "one-liner" transformations.

  • Use Case: Quick data extraction, in-place text modification, building complex strings in a loop.

🧩 The Power of Integration

The true power of the uCalc SDK comes from the seamless integration of these components. The most significant example is the ability to embed the full power of the Expression Parser directly inside a Transformer rule using the {@Eval} pattern method.

This allows you to perform calculations, call functions, and use conditional logic during a find-and-replace operation. A rule can capture text, convert it to a number, perform a calculation with it, and insert the formatted result back into the string—all in a single, declarative step. The practical and internal test examples below showcase this powerful synergy.

Likewise the expression parser syntax can be expanded using uCalc.ExpressionTransformer.

Examples

A succinct demonstration of the three core SDK components performing their primary functions independently.
				
					using uCalcSoftware;

var uc = new uCalc();
// 1. Expression Parser: Evaluate a simple math or string expression
Console.WriteLine($"Parser Result: {uc.Eval("(100 - 50) / 2")}");
Console.WriteLine($"Parser Result (string): {uc.EvalStr("'Hello ' + 'World'")}");

// 2. Transformer: Perform a basic find-and-replace
var t = new uCalc.Transformer();
t.FromTo("Hello", "Hi");
t.FromTo("World", "Planet");
t.SkipOver("/* {comment} */");
Console.WriteLine($"Transformer Result: {t.Transform("Hello World /* Was Hello World */")}");

// 3. String Library: Use a fluent, chainable operation
uCalc.String s = "The value is: important";
s.After(":").ToUpper();
Console.WriteLine($"String Library Result: {s}");


				
			
Parser Result: 25
Parser Result (string): Hello World
Transformer Result: Hi Planet /* Was Hello World */
String Library Result: The value is: IMPORTANT
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // 1. Expression Parser: Evaluate a simple math or string expression
   cout << "Parser Result: " << uc.Eval("(100 - 50) / 2") << endl;
   cout << "Parser Result (string): " << uc.EvalStr("'Hello ' + 'World'") << endl;

   // 2. Transformer: Perform a basic find-and-replace
   uCalc::Transformer t;
   t.FromTo("Hello", "Hi");
   t.FromTo("World", "Planet");
   t.SkipOver("/* {comment} */");
   cout << "Transformer Result: " << t.Transform("Hello World /* Was Hello World */") << endl;

   // 3. String Library: Use a fluent, chainable operation
   uCalc::String s = "The value is: important";
   s.After(":").ToUpper();
   cout << "String Library Result: " << s << endl;


}
				
			
Parser Result: 25
Parser Result (string): Hello World
Transformer Result: Hi Planet /* Was Hello World */
String Library Result: The value is: IMPORTANT
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// 1. Expression Parser: Evaluate a simple math or string expression
      Console.WriteLine($"Parser Result: {uc.Eval("(100 - 50) / 2")}")
      Console.WriteLine($"Parser Result (string): {uc.EvalStr("'Hello ' + 'World'")}")
      
      '// 2. Transformer: Perform a basic find-and-replace
      Dim t As New uCalc.Transformer()
      t.FromTo("Hello", "Hi")
      t.FromTo("World", "Planet")
      t.SkipOver("/* {comment} */")
      Console.WriteLine($"Transformer Result: {t.Transform("Hello World /* Was Hello World */")}")
      
      '// 3. String Library: Use a fluent, chainable operation
      Dim s As uCalc.String = "The value is: important"
      s.After(":").ToUpper()
      Console.WriteLine($"String Library Result: {s}")
      
      
   End Sub
End Module
				
			
Parser Result: 25
Parser Result (string): Hello World
Transformer Result: Hi Planet /* Was Hello World */
String Library Result: The value is: IMPORTANT
A practical, real-world example of integration: using the Transformer and Expression Parser together to create a simple template engine that replaces placeholders with evaluated data.
				
					using uCalcSoftware;

var uc = new uCalc();
// Define the data context for our template
uc.DefineVariable("user = 'Alice'");
uc.DefineVariable("score = 95");

// Define the template with placeholders
var myTemplate = "User: {user}, Score: {score * 10}, Status: {IIf(score > 90, 'Excellent', 'Good')}";

var t = uc.NewTransformer();
// This single rule finds placeholders like {...}
// and uses the Expression Parser ({@@Eval}) to evaluate the content inside.
t.FromTo("'{' {expr} '}'", "{@@Eval: expr}");

Console.WriteLine(t.Transform(myTemplate));

				
			
User: Alice, Score: 950, Status: Excellent
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Define the data context for our template
   uc.DefineVariable("user = 'Alice'");
   uc.DefineVariable("score = 95");

   // Define the template with placeholders
   auto myTemplate = "User: {user}, Score: {score * 10}, Status: {IIf(score > 90, 'Excellent', 'Good')}";

   auto t = uc.NewTransformer();
   // This single rule finds placeholders like {...}
   // and uses the Expression Parser ({@@Eval}) to evaluate the content inside.
   t.FromTo("'{' {expr} '}'", "{@@Eval: expr}");

   cout << t.Transform(myTemplate) << endl;

}
				
			
User: Alice, Score: 950, Status: Excellent
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Define the data context for our template
      uc.DefineVariable("user = 'Alice'")
      uc.DefineVariable("score = 95")
      
      '// Define the template with placeholders
      Dim myTemplate = "User: {user}, Score: {score * 10}, Status: {IIf(score > 90, 'Excellent', 'Good')}"
      
      Dim t = uc.NewTransformer()
      '// This single rule finds placeholders like {...}
      '// and uses the Expression Parser ({@@Eval}) to evaluate the content inside.
      t.FromTo("'{' {expr} '}'", "{@@Eval: expr}")
      
      Console.WriteLine(t.Transform(myTemplate))
      
   End Sub
End Module
				
			
User: Alice, Score: 950, Status: Excellent
Using the parse-evaluate pattern for high-performance calculations in a loop with a changing variable.
				
					using uCalcSoftware;

var uc = new uCalc();
// Define a variable 'x' that will be updated in the loop.
var variableX = uc.DefineVariable("x");

// Parse the expression just once before the loop begins.
var parsedExpr = uc.Parse("x^2 * 10");

Console.WriteLine("Evaluating 'x^2 * 10' for x = 1 to 5:");
for (double x = 1; x <= 5; x++) {
   variableX.Value(x);
   // Evaluate is very fast as the parsing work is already done.
   Console.WriteLine($"x = {x}, Result = {parsedExpr.Evaluate()}");
}
				
			
Evaluating 'x^2 * 10' for x = 1 to 5:
x = 1, Result = 10
x = 2, Result = 40
x = 3, Result = 90
x = 4, Result = 160
x = 5, Result = 250
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Define a variable 'x' that will be updated in the loop.
   auto variableX = uc.DefineVariable("x");

   // Parse the expression just once before the loop begins.
   auto parsedExpr = uc.Parse("x^2 * 10");

   cout << "Evaluating 'x^2 * 10' for x = 1 to 5:" << endl;
   for (double x = 1; x <= 5; x++) {
      variableX.Value(x);
      // Evaluate is very fast as the parsing work is already done.
      cout << "x = " << x << ", Result = " << parsedExpr.Evaluate() << endl;
   }
}
				
			
Evaluating 'x^2 * 10' for x = 1 to 5:
x = 1, Result = 10
x = 2, Result = 40
x = 3, Result = 90
x = 4, Result = 160
x = 5, Result = 250
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Define a variable 'x' that will be updated in the loop.
      Dim variableX = uc.DefineVariable("x")
      
      '// Parse the expression just once before the loop begins.
      Dim parsedExpr = uc.Parse("x^2 * 10")
      
      Console.WriteLine("Evaluating 'x^2 * 10' for x = 1 to 5:")
      For x  As Double = 1 To 5
         variableX.Value(x)
         '// Evaluate is very fast as the parsing work is already done.
         Console.WriteLine($"x = {x}, Result = {parsedExpr.Evaluate()}")
      Next
   End Sub
End Module
				
			
Evaluating 'x^2 * 10' for x = 1 to 5:
x = 1, Result = 10
x = 2, Result = 40
x = 3, Result = 90
x = 4, Result = 160
x = 5, Result = 250
Previous
Next