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.

Introduction

Product:

Fast Math Parser

Class:

uCalcBase

An overview of the main uCalc engine 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.

Member	Description
`Eval`	Parses and evaluates a string expression in a single step, returning a numeric result.
`EvalStr`	Parses and evaluates an expression in a single step, returning the result of any data type as a string.
`Parse`	Compiles 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.

Member	Description
`Define`	Creates functions, operators, variables, and other symbols using a single, versatile definition string.
`DefineFunction`	Registers 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.
`DefineOperator`	Defines a custom operator to extend or modify the expression syntax at runtime.
`DefineVariable`	Defines a new variable or array within the uCalc engine, with an optional initial value and data type.
`DefineConstant`	Defines a named, read-only constant for use in expressions.
`CreateAlias`	Creates 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.

Member	Description
`Constructor`	Creates a new uCalc instance, optionally cloning an existing one, or creating an empty placeholder.
`Clone`	Creates an identical, but independent, copy of the current uCalc instance, including all its defined variables, functions, and settings.
`Release`	Explicitly releases a uCalc instance and frees all of its associated memory and resources.
`Owned`	Manages automatic resource release for an object, enabling RAII-style lifetime management primarily for C++.
`DefaultInstance`	Gets/sets the globally accessible default uCalc instance.
`IsDefault`	Gets or sets whether the current uCalc instance is the active default for the current thread.
`DefaultClear`	Resets the default instance stack, restoring the original default instance to its initial state.
`DefaultCount`	Gets the number of uCalc instances currently on the default instance stack.
`ResetAll`	Resets 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.

Member	Description
`ItemOf`	Retrieves the uCalc.Item object for a symbol by its name, optionally filtered by properties to disambiguate overloads.
`Items`	Retrieves a collection of all defined symbols (functions, variables, operators, etc.).
`DataTypeOf`	Retrieves the DataType object associated with a specific item name, type name, or expression.
`DataTypes`	Retrieves a collection of all data types registered within the current uCalc instance.
`Properties`	Creates a bitmask for querying items by their properties, such as function, operator, or variable.
`Description`	Retrieves or assigns a user-defined text description to a uCalc object, useful for attaching metadata and for debugging.
`Error`	Provides 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.

Member	Description
`ExpressionTransformer`	Returns the singleton transformer instance used to pre-process expressions before they are parsed.
`TokenTransformer`	Retrieves the dedicated transformer for defining token-level transformations, enabling custom syntax like string interpolation or hex literals.
`ExpressionTokens`	Retrieves the token definition collection used by the expression parser, allowing for inspection and customization.
`TransformerForRulePatterns`	Retrieves a singleton transformer that pre-processes pattern definition strings before they are compiled into rules.
`TransformerForRuleReplacements`	Retrieves a meta-transformer that pre-processes the replacement strings of other transformer rules before they are defined.
`Format`	Defines a declarative rule for transforming the string output of evaluation functions.
`FormatRemove`	Removes one or all custom output formatting rules previously defined with the Format method.
`DefaultDataType`	Gets 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.

Member	Description
`NewString`	Creates a new uCalc.String object.
`NewTransformer`	Creates a new Transformer object.

🔍 Low-Level & Diagnostics

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

Member	Description
`Handle`	Returns the internal handle of the uCalc instance, a unique identifier used by the library for low-level operations.
`MemoryIndex`	Returns a stable, session-unique integer that identifies a uCalc object, primarily for diagnostics and tracking object lifetimes.
`DiagMem`	Provides a programmatic way to query uCalc's internal memory usage.
`ValueAt`	Dereferences a pointer and returns a string representation of the value, allowing for on-the-fly type casting.

Examples

A quick start example showing defining symbols and evaluating an expression.

				
					using uCalcSoftware;

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

Console.WriteLine(uc.Eval("DoubleThis(x) + 5"));

using uCalcSoftware;&#13;&#13;var uc = new uCalc();&#13;uc.DefineVariable("x = 10");&#13;uc.DefineFunction("DoubleThis(n) = n * 2");&#13;&#13;Console.WriteLine(uc.Eval("DoubleThis(x) + 5"));

				
					#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;
}

#include <iostream>&#13;#include "uCalc.h"&#13;&#13;using namespace std;&#13;using namespace uCalcSoftware;&#13;&#13;int main() {&#13;   uCalc uc;&#13;   uc.DefineVariable("x = 10");&#13;   uc.DefineFunction("DoubleThis(n) = n * 2");&#13;&#13;   cout << uc.Eval("DoubleThis(x) + 5") << endl;&#13;}

				
					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

Imports System&#13;Imports uCalcSoftware&#13;Public Module Program&#13;   Public Sub Main()&#13;      Dim uc As New uCalc()&#13;      uc.DefineVariable("x = 10")&#13;      uc.DefineFunction("DoubleThis(n) = n * 2")&#13;      &#13;      Console.WriteLine(uc.Eval("DoubleThis(x) + 5"))&#13;   End Sub&#13;End Module