uCalc API Version: 5.7.0-preview.1 Released: 7/30/2026

Warning

uCalc API Preview Release Notice:This preview documentation describes the intended behavior of the API. It is not fully accurate or complete.The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.Use of the preview version in your production code is not recommended.

Introduction

Product: 

Fast Math Parser

Class: 

uCalc

An overview of the main uCalc class, the central component for parsing, evaluation, and customization.

Remarks

🚀 The uCalc Class: Your Parsing Engine

The uCalc class is the heart of the library. An instance of this class represents a complete, sandboxed evaluation engine with its own isolated set of variables, functions, operators, and settings. It serves as the primary factory and context for all parsing and transformation operations.

Think of a uCalc object as a self-contained language environment. You can create multiple instances, each with a different configuration, allowing you to run different parsers side-by-side without interference. This is the starting point for nearly everything you will do with the library.

⚡ Core Evaluation Methods

These methods are the workhorses for processing expression strings.

MemberDescription
EvalParses and evaluates a string expression in a single step, returning a numeric result.
EvalStrParses and evaluates an expression in a single step, returning the result of any data type as a string.
ParseCompiles a string expression into an intermediate, reusable object for high-performance evaluation.

🛠️ Symbol Definition Methods

These methods allow you to extend the engine's syntax and define data at runtime.

MemberDescription
DefineCreates functions, operators, variables, and other symbols using a single, versatile definition string.
DefineFunctionRegisters a user-defined function for use in expressions, supporting inline definitions, external callbacks, and advanced features like overloading, recursion, bootstrapping, variadic args, lazy argument evaluation, and more.
DefineOperatorDefines a custom operator to extend or modify the expression syntax at runtime.
DefineVariableDefines a new variable or array within the uCalc engine, with an optional initial value and data type.
DefineConstantDefines a named, read-only constant for use in expressions.
CreateAliasCreates a new symbol that behaves exactly like an existing symbol.

⚙️ Instance & Lifetime Management

These members control the creation, cloning, and destruction of uCalc engine instances.

MemberDescription
ConstructorCreates a new uCalc instance, optionally cloning an existing one, or creating an empty placeholder.
CloneCreates an identical, but independent, copy of the current uCalc instance, including all its defined variables, functions, and settings.
ReleaseExplicitly releases a uCalc instance and frees all of its associated memory and resources.
OwnedManages automatic resource release for an object, enabling RAII-style lifetime management primarily for C++.
DefaultInstanceGets/sets the globally accessible default uCalc instance.
IsDefaultGets or sets whether the current uCalc instance is the active default for the current thread.
DefaultClearResets the default instance stack, restoring the original default instance to its initial state.
DefaultCountGets the number of uCalc instances currently on the default instance stack.
ResetAllResets the entire uCalc library to its initial startup state, releasing all instances and clearing all definitions.

🧐 Introspection & Metadata

These members allow you to query the state and symbols within a uCalc instance.

MemberDescription
ItemOfRetrieves the uCalc.Item object for a symbol by its name, optionally filtered by properties to disambiguate overloads.
ItemsRetrieves a collection of all defined symbols (functions, variables, operators, etc.).
DataTypeOfRetrieves the DataType object associated with a specific item name, type name, or expression.
DataTypesRetrieves a collection of all data types registered within the current uCalc instance.
PropertiesCreates a bitmask for querying items by their properties, such as function, operator, or variable.
DescriptionRetrieves or assigns a user-defined text description to a uCalc object, useful for attaching metadata and for debugging.
ErrorProvides access to the ErrorInfo object with details about the last error.

🎨 Customization & Extensibility

These members provide access to the engines that control syntax and output formatting.

MemberDescription
ExpressionTransformerReturns the singleton transformer instance used to pre-process expressions before they are parsed.
TokenTransformerRetrieves the dedicated transformer for defining token-level transformations, enabling custom syntax like string interpolation or hex literals.
ExpressionTokensRetrieves the token definition collection used by the expression parser, allowing for inspection and customization.
TransformerForRulePatternsRetrieves a singleton transformer that pre-processes pattern definition strings before they are compiled into rules.
TransformerForRuleReplacementsRetrieves a meta-transformer that pre-processes the replacement strings of other transformer rules before they are defined.
FormatDefines a declarative rule for transforming the string output of evaluation functions.
FormatRemoveRemoves one or all custom output formatting rules previously defined with the Format method.
DefaultDataTypeGets or sets the default data type used for implicit typing during definitions and evaluation.

🏭 Component Factories

These methods create instances of other major uCalc components.

MemberDescription
NewStringCreates a new uCalc.String object.
NewTransformerCreates a new Transformer object.

🔍 Low-Level & Diagnostics

These members are for advanced use cases, performance tuning, and debugging.

MemberDescription
HandleReturns the internal handle of the uCalc instance, a unique identifier used by the library for low-level operations.
MemoryIndexReturns a stable, session-unique integer that identifies a uCalc object, primarily for diagnostics and tracking object lifetimes.
DiagMemProvides a programmatic way to query uCalc's internal memory usage.
ValueAtDereferences a pointer and returns a string representation of the value, allowing for on-the-fly type casting.

Examples

A quick start example showing defining a variable, a function, and evaluating an expression.

ID: 1296

See: DefineFunction, DefineVariable, Eval, Introduction 
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineVariable("x = 10");
uc.DefineFunction("DoubleThis(n) = n * 2");

Console.WriteLine(uc.Eval("DoubleThis(x) + 5"));
				
			
25
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineVariable("x = 10");
   uc.DefineFunction("DoubleThis(n) = n * 2");

   cout << uc.Eval("DoubleThis(x) + 5") << endl;
}
				
			
25
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("x = 10")
      uc.DefineFunction("DoubleThis(n) = n * 2")
      
      Console.WriteLine(uc.Eval("DoubleThis(x) + 5"))
   End Sub
End Module
				
			
25
Explore 600+ other examples
Manage separate parser contexts for different application modules.

ID: 271

See: DefaultCount = [int], DefaultInstance = [uCalc], Introduction, IsDefault = [bool] 
				
					using uCalcSoftware;

var uc = new uCalc();
// --- Main Application Context ---
// Starting with the 'uc' object as the initial default.
uCalc.DefaultInstance.DefineConstant("PI = 3.14159");
Console.WriteLine($"Initial Count: {uCalc.DefaultCount}");

// --- A Plugin needs a temporary, isolated context ---
using (var moduleCalc = new uCalc()) {
   moduleCalc.IsDefault = true; // Push the new instance onto the stack.
   Console.WriteLine($"Count after module pushes new default: {uCalc.DefaultCount}");

   // The module's context is now active.
   // uCalc::DefaultInstance() would now return 'moduleCalc'.
}

// When 'moduleCalc' goes out of scope, it's destroyed and automatically
// removed from the stack, restoring the previous default.

Console.WriteLine($"Count after module instance is disposed: {uCalc.DefaultCount}");

// Verify the original default instance is active again.
var result = uCalc.DefaultInstance.EvalStr("PI");
Console.WriteLine($"Original context restored. PI = {result}");
				
			
Initial Count: 1
Count after module pushes new default: 2
Count after module instance is disposed: 1
Original context restored. PI = 3.14159
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // --- Main Application Context ---
   // Starting with the 'uc' object as the initial default.
   uCalc::DefaultInstance().DefineConstant("PI = 3.14159");
   cout << "Initial Count: " << uCalc::DefaultCount() << endl;

   // --- A Plugin needs a temporary, isolated context ---
   {
      uCalc moduleCalc;
      moduleCalc.Owned(); // Causes moduleCalc to be released when it goes out of scope
      moduleCalc.IsDefault(true); // Push the new instance onto the stack.
      cout << "Count after module pushes new default: " << uCalc::DefaultCount() << endl;

      // The module's context is now active.
      // uCalc::DefaultInstance() would now return 'moduleCalc'.
   }

   // When 'moduleCalc' goes out of scope, it's destroyed and automatically
   // removed from the stack, restoring the previous default.

   cout << "Count after module instance is disposed: " << uCalc::DefaultCount() << endl;

   // Verify the original default instance is active again.
   auto result = uCalc::DefaultInstance().EvalStr("PI");
   cout << "Original context restored. PI = " << result << endl;
}
				
			
Initial Count: 1
Count after module pushes new default: 2
Count after module instance is disposed: 1
Original context restored. PI = 3.14159
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// --- Main Application Context ---
      '// Starting with the 'uc' object as the initial default.
      uCalc.DefaultInstance.DefineConstant("PI = 3.14159")
      Console.WriteLine($"Initial Count: {uCalc.DefaultCount}")
      
      '// --- A Plugin needs a temporary, isolated context ---
      Using moduleCalc As New uCalc()
         moduleCalc.IsDefault = true '// Push the new instance onto the stack.
         Console.WriteLine($"Count after module pushes new default: {uCalc.DefaultCount}")
         
         '// The module's context is now active.
         '// uCalc::DefaultInstance() would now return 'moduleCalc'.
      End Using
      
      '// When 'moduleCalc' goes out of scope, it's destroyed and automatically
      '// removed from the stack, restoring the previous default.
      
      Console.WriteLine($"Count after module instance is disposed: {uCalc.DefaultCount}")
      
      '// Verify the original default instance is active again.
      Dim result = uCalc.DefaultInstance.EvalStr("PI")
      Console.WriteLine($"Original context restored. PI = {result}")
   End Sub
End Module
				
			
Initial Count: 1
Count after module pushes new default: 2
Count after module instance is disposed: 1
Original context restored. PI = 3.14159
Explore 600+ other examples
"using" (C#) and Owned (C++) for auto-releasing uCalc object

ID: 161

See: (Constructor), DefaultInstance = [uCalc], Introduction, IsDefault = [bool], Owned 
				
					using uCalcSoftware;

var uc = new uCalc();

// In C# and VB you should use "using".
// In C++ you can flag a uCalc object for
// auto-release with Owned(), or by setting
// the last parameter of the constructor to true.

uc.IsDefault = true; // Set uc as the default uCalc object
uCalc.DefaultInstance.DefineVariable("Value = 'Original uc object'");
Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")); // Outputs: Original uc object

// Use "using" so that the object is auto-released when it it goes out of scope
using (var uCalcTemp = new uCalc()) {
   uCalcTemp.IsDefault = true; // Set uCalcTemp as the default uCalc object
   uCalc.DefaultInstance.DefineVariable("Value = 'uCalcTemp object'");
   Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")); // uCalcTemp object
}
// uCalcTemp goes out of scope here, and the default uCalc object reverts back to uc

Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")); // Original uc object

{
   /*using*/ var uCalcSticky = new uCalc(); // remains the default even after going out of scope
   uCalcSticky.IsDefault = true; // Set uCalcSticky as the default uCalc object
   uCalc.DefaultInstance.DefineVariable("Value = 'uCalcSticky object'");
   Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")); // Outputs: uCalcSticky object
}    // The uCalcSticky object itself goes out of scope here, but internally it remains the default uCalc object

Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value"));
				
			
Original uc object
uCalcTemp object
Original uc object
uCalcSticky object
uCalcSticky object
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;

   // In C# and VB you should use "using".
   // In C++ you can flag a uCalc object for
   // auto-release with Owned(), or by setting
   // the last parameter of the constructor to true.

   uc.IsDefault(true); // Set uc as the default uCalc object
   uCalc::DefaultInstance().DefineVariable("Value = 'Original uc object'");
   cout << uCalc::DefaultInstance().EvalStr("Value") << endl; // Outputs: Original uc object


   {
      uCalc uCalcTemp;
      uCalcTemp.Owned(); // Causes uCalcTemp to be released when it goes out of scope // Make uCalcTemp owned so it reverts back to uc when uCalcTemp goes out of scope
      uCalcTemp.IsDefault(true); // Set uCalcTemp as the default uCalc object
      uCalc::DefaultInstance().DefineVariable("Value = 'uCalcTemp object'");
      cout << uCalc::DefaultInstance().EvalStr("Value") << endl; // uCalcTemp object
   }
   // uCalcTemp goes out of scope here, and the default uCalc object reverts back to uc

   cout << uCalc::DefaultInstance().EvalStr("Value") << endl; // Original uc object

   {
      uCalc uCalcSticky; // remains the default even after going out of scope
      uCalcSticky.IsDefault(true); // Set uCalcSticky as the default uCalc object
      uCalc::DefaultInstance().DefineVariable("Value = 'uCalcSticky object'");
      cout << uCalc::DefaultInstance().EvalStr("Value") << endl; // Outputs: uCalcSticky object
   }    // The uCalcSticky object itself goes out of scope here, but internally it remains the default uCalc object

   cout << uCalc::DefaultInstance().EvalStr("Value") << endl;
}
				
			
Original uc object
uCalcTemp object
Original uc object
uCalcSticky object
uCalcSticky object
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      '// In C# and VB you should use "using".
      '// In C++ you can flag a uCalc object for
      '// auto-release with Owned(), or by setting
      '// the last parameter of the constructor to true.
      
      uc.IsDefault = true '// Set uc as the default uCalc object
      uCalc.DefaultInstance.DefineVariable("Value = 'Original uc object'")
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")) '// Outputs: Original uc object
      
      '// Use "using" so that the object is auto-released when it it goes out of scope
      Using uCalcTemp As New uCalc()
         uCalcTemp.IsDefault = true '// Set uCalcTemp as the default uCalc object
         uCalc.DefaultInstance.DefineVariable("Value = 'uCalcTemp object'")
         Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")) '// uCalcTemp object
      End Using
      '// uCalcTemp goes out of scope here, and the default uCalc object reverts back to uc
      
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")) '// Original uc object
      
      If True Then
         Dim uCalcSticky As New uCalc() '// remains the default even after going out of scope
         uCalcSticky.IsDefault = true '// Set uCalcSticky as the default uCalc object
         uCalc.DefaultInstance.DefineVariable("Value = 'uCalcSticky object'")
         Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")) '// Outputs: uCalcSticky object
      End If    '// The uCalcSticky object itself goes out of scope here, but internally it remains the default uCalc object
      
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value"))
   End Sub
End Module
				
			
Original uc object
uCalcTemp object
Original uc object
uCalcSticky object
uCalcSticky object
Explore 600+ other examples
Passing arg ByExpr (delayed lazy eval) and ByHandle

ID: 14

See: (Constructor), Arg, ArgExpr, ArgItem, DefineFunction, Evaluate, Introduction, Value(double) 
				
					using uCalcSoftware;

var uc = new uCalc();

static void MySum(uCalc.Callback cb) {
   var Total = 0.0;
   var Expr = cb.ArgExpr(1);
   var Start = cb.Arg(2);
   var Finish = cb.Arg(3);
   var Variable = cb.ArgItem(4);

   for (double x = Start; x <= Finish; x++) {
      Variable.Value(x);
      Total += Expr.Evaluate();
   }
   cb.Return(Total);
}

uc.DefineVariable("x");
uc.DefineFunction("Sum(ByExpr Expr, Start, Finish, ByHandle Var)", MySum);
Console.WriteLine(uc.Eval("Sum(x ^ 2, 1, 10, x)"));

				
			
385
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MySum(uCalcBase::Callback cb) {
   auto Total = 0.0;
   auto Expr = cb.ArgExpr(1);
   auto Start = cb.Arg(2);
   auto Finish = cb.Arg(3);
   auto Variable = cb.ArgItem(4);

   for (double x = Start; x <= Finish; x++) {
      Variable.Value(x);
      Total += Expr.Evaluate();
   }
   cb.Return(Total);
}
int main() {
   uCalc uc;
   uc.DefineVariable("x");
   uc.DefineFunction("Sum(ByExpr Expr, Start, Finish, ByHandle Var)", MySum);
   cout << uc.Eval("Sum(x ^ 2, 1, 10, x)") << endl;

}
				
			
385
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MySum(ByVal cb As uCalc.Callback)
      Dim Total = 0.0
      Dim Expr = cb.ArgExpr(1)
      Dim Start = cb.Arg(2)
      Dim Finish = cb.Arg(3)
      Dim Variable = cb.ArgItem(4)
      
      For x  As Double = Start To Finish
         Variable.Value(x)
         Total += Expr.Evaluate()
      Next
      cb.Return(Total)
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("x")
      uc.DefineFunction("Sum(ByExpr Expr, Start, Finish, ByHandle Var)", AddressOf MySum)
      Console.WriteLine(uc.Eval("Sum(x ^ 2, 1, 10, x)"))
      
   End Sub
End Module
				
			
385
Explore 600+ other examples