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.

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 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"));
				
			
25
				
					#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
				
					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
Previous
Next