uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

Why uCalc? A Quick Tour

Product: 

Class: 

A showcase of compelling examples demonstrating uCalc's unique advantages over conventional tools like Regex and simple expression evaluators.

Remarks

✨ Why uCalc? A Quick Tour

Before diving into the details, let's take a quick tour of what makes uCalc special. Most developers are familiar with tools like Regular Expressions (Regex) for text processing and simple eval() functions for math. uCalc goes far beyond these, offering a more powerful, safer, and more flexible approach to parsing and transformation.

This page highlights three core advantages you won't find in most conventional tools.

1. Safety Through Token-Awareness

The Problem with Regex: Regular expressions are powerful but 'blind'. They see a stream of characters, not a structured language. This makes them dangerous for code transformation. A simple search-and-replace can easily corrupt code by changing text inside a string literal or comment.

The uCalc Solution: uCalc first breaks text into meaningful tokens (words, numbers, strings, etc.). Its Transformer operates on these tokens, giving it structural awareness. By default, it knows not to look inside a string, making refactoring safe and predictable.

Example: Safely Renaming a Variable

Imagine you want to rename the variable x to value. A simple regex would incorrectly change the x inside the string literal.

  • Input: if (x > 10) print("Max value is x");
  • Regex Replace: if (value > 10) print("Max value is value"); 🔴 (Incorrect!)
  • uCalc Transform: if (value > 10) print("Max value is x"); 🟢 (Correct!)

This safety is a core architectural advantage, especially for building static analysis tools, linters, or code transpilers.

2. Dynamic Syntax at Runtime

The Problem with Compiled Languages: The syntax of languages like C# and C++ is fixed at compile time. You can't invent a new operator or keyword without modifying the compiler itself. Parser generators like ANTLR are also static; changes require regenerating code and recompiling.

The uCalc Solution: uCalc's grammar is fully dynamic. You can define new operators, functions, and even literal formats at runtime. This allows you to create your own expressive, domain-specific languages (DSLs) tailored to your application's needs.

Example: Creating a Custom to Operator

Let's create a custom to operator to generate a sequence of numbers, a feature common in languages like Swift or Kotlin.

// Define a new operator at runtimeuc.DefineOperator("{start} to {end} = ForLoop(i, start, end, 1, print(i))", 50);// Now you can use it directly in an expressionuc.Eval("1 to 5");

This runtime extensibility is impossible with static parsers and allows you to build highly adaptable and user-configurable systems.

3. Lazy Evaluation and Metaprogramming

The Problem with Simple Evaluators: Standard eval() functions and simple expression parsers typically evaluate all arguments immediately. This prevents you from creating custom control structures (like loops or conditional statements) where an argument should only be executed if a certain condition is met.

The uCalc Solution: uCalc supports lazy evaluation through the ByExpr parameter modifier. When used, an argument is passed not as a value, but as an unevaluated Expression object. The function can then decide when, or even if, to execute it.

Example: Creating a Custom Repeat Function

Let's build a function that repeats an action N times. The action is passed as an expression that the function will evaluate in a loop.

static void MyRepeat(uCalc.Callback cb) {  int count = cb.ArgInt32(1);  Expression action = cb.ArgExpr(2);  for (int i = 1; i <= count; i++) {    action.Execute();  }}// Define a variable to be modifieduc.DefineVariable("counter = 0");// The 'action' (counter++) is passed unevaluateduc.DefineFunction("Repeat(count, ByExpr action)", MyRepeat);// Run the custom loopuc.Eval("Repeat(5, counter++)");Console.WriteLine(uc.Eval("counter")); // Output: 5

This capability elevates uCalc from a simple calculator to a lightweight scripting engine, allowing you to implement custom control flow and other advanced logic.

Examples

Demonstrates how uCalc's token-aware Transformer safely renames a variable without corrupting a string literal, a common failure point for Regex.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();

// A rule to replace the alphanumeric token 'x' with 'value'
t.FromTo("x", "value");

// The input string where 'x' appears both as a variable and inside a string
var code = """
if (x > 10) print("Max value is x");
""";

// The transformation correctly ignores the 'x' inside the quoted string
Console.WriteLine(t.Transform(code));
				
			
if (value > 10) print("Max value is x");
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;

   // A rule to replace the alphanumeric token 'x' with 'value'
   t.FromTo("x", "value");

   // The input string where 'x' appears both as a variable and inside a string
   auto code = R"(if (x > 10) print("Max value is x");)";

   // The transformation correctly ignores the 'x' inside the quoted string
   cout << t.Transform(code) << endl;
}
				
			
if (value > 10) print("Max value is x");
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      
      '// A rule to replace the alphanumeric token 'x' with 'value'
      t.FromTo("x", "value")
      
      '// The input string where 'x' appears both as a variable and inside a string
      Dim code = "if (x > 10) print(""Max value is x"");"
      
      '// The transformation correctly ignores the 'x' inside the quoted string
      Console.WriteLine(t.Transform(code))
   End Sub
End Module
				
			
if (value > 10) print("Max value is x");
Illustrates lazy evaluation by creating a custom 'Repeat' function that executes a code block (passed with `ByExpr`) a specified number of times.
				
					using uCalcSoftware;

var uc = new uCalc();

static void MyRepeat(uCalc.Callback cb) {
   var count = cb.ArgInt32(1);
   var action = cb.ArgExpr(2);

   for (int i = 1; i <= count; i++) {
      action.Execute(); // Evaluate the passed-in expression
   }
}


// Define a variable that our action will modify
uc.DefineVariable("counter = 0");

// Define the function. The 'action' parameter is marked with ByExpr
// to ensure it's passed as an unevaluated expression object.
uc.DefineFunction("Repeat(count As Int, ByExpr action)", MyRepeat);

// Call the custom Repeat function. The expression 'counter++' is not
// evaluated here; it's passed to the callback to be executed in a loop.
uc.Eval("Repeat(5, counter++)");

// Verify the side effect
Console.WriteLine($"Final counter value: {uc.Eval("counter")}");
				
			
Final counter value: 5
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MyRepeat(uCalcBase::Callback cb) {
   auto count = cb.ArgInt32(1);
   auto action = cb.ArgExpr(2);

   for (int i = 1; i <= count; i++) {
      action.Execute(); // Evaluate the passed-in expression
   }
}

int main() {
   uCalc uc;
   // Define a variable that our action will modify
   uc.DefineVariable("counter = 0");

   // Define the function. The 'action' parameter is marked with ByExpr
   // to ensure it's passed as an unevaluated expression object.
   uc.DefineFunction("Repeat(count As Int, ByExpr action)", MyRepeat);

   // Call the custom Repeat function. The expression 'counter++' is not
   // evaluated here; it's passed to the callback to be executed in a loop.
   uc.Eval("Repeat(5, counter++)");

   // Verify the side effect
   cout << "Final counter value: " << uc.Eval("counter") << endl;
}
				
			
Final counter value: 5
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MyRepeat(ByVal cb As uCalc.Callback)
      Dim count = cb.ArgInt32(1)
      Dim action = cb.ArgExpr(2)
      
      For i  As Integer = 1 To count
         action.Execute() '// Evaluate the passed-in expression
      Next
   End Sub
   
   Public Sub Main()
      Dim uc As New uCalc()
      '// Define a variable that our action will modify
      uc.DefineVariable("counter = 0")
      
      '// Define the function. The 'action' parameter is marked with ByExpr
      '// to ensure it's passed as an unevaluated expression object.
      uc.DefineFunction("Repeat(count As Int, ByExpr action)", AddressOf MyRepeat)
      
      '// Call the custom Repeat function. The expression 'counter++' is not
      '// evaluated here; it's passed to the callback to be executed in a loop.
      uc.Eval("Repeat(5, counter++)")
      
      '// Verify the side effect
      Console.WriteLine($"Final counter value: {uc.Eval("counter")}")
   End Sub
End Module
				
			
Final counter value: 5
Previous
Next