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.

The uCalc Object Model - A High-Level Overview

Product: 

Class: 

A high-level guide to the key classes in the uCalc library and how they interact to provide parsing, evaluation, and transformation capabilities.

Remarks

🏛️ The uCalc Object Model: A High-Level Overview

The uCalc library is more than just a collection of functions; it's a structured ecosystem of interconnected objects. Understanding this object model is key to leveraging the full power of the library, from high-performance expression evaluation to complex text transformation. This guide provides a high-level map of the core classes and their relationships.

1. 👑 The Core Engine: uCalc and Item

At the center of everything are two fundamental concepts:

  • uCalc: This is the main engine instance. Think of it as a self-contained, sandboxed environment. It acts as the primary factory for creating other objects and holds the complete context for all operations, including all defined symbols.
  • Item: This is the universal, polymorphic handle for any symbol defined within a uCalc instance. Whether it's a variable, a function, an operator, a data type, or even a transformer rule, it is represented internally as an Item. This unified model simplifies introspection and management.

2. 🚀 The Expression Parser System

This subsystem is responsible for evaluating mathematical and logical expressions.

  • uCalc: The starting point. You use its methods like Parse, Eval, and EvalStr to process expression strings. It's also where you define symbols with DefineFunction, DefineVariable, etc.
  • Expression: The result of a Parse operation. It represents a pre-compiled, reusable execution plan, which is the key to the "Parse-Once, Evaluate-Many" performance pattern.
  • Callback: The bridge object. When you bind a custom function to your native code, your function receives a Callback object, which it uses to get arguments and return a value to the engine.

3. 🧠 The Text Transformation System

This subsystem provides powerful, token-aware find-and-replace capabilities.

  • Transformer: The rule-based engine for transforming text. It is more powerful and safer than regular expressions for structured data.
  • Tokens: A collection of lexical rules (regular expressions) that defines how the Transformer breaks raw text into meaningful tokens (words, numbers, symbols).
  • Rule: A single, compiled pattern-to-action definition within a Transformer. You create rules with methods like FromTo and Pattern.
  • Matches: The collection of results from a Find or Transform operation. Each individual Match object contains the text, position, and the Rule that generated it.

4. 🧵 The Fluent String Library

  • uCalc.String: A mutable, high-performance string class with a fluent, chainable API. It's designed for "one-liner" transformations and acts as a StringBuilder, lightweight Transformer, and list processor all in one. It operates using a "live view" model, where modifications to a substring directly affect the parent.

🗺️ Relationship Diagram

The following diagram illustrates the primary relationships and ownership within the object model:

                   ┌─────────────────┐                   │      uCalc      │ (The Engine/Context)                   └─────────────────┘                           │         ┌─────────────────┴─────────────────┐         │ (Owns/Manages)                    │  ┌──────▼──────┐   ┌────────────┐   ┌──────▼─────┐  │    Items    │   │ DataTypes  │   │   Tokens   │ (Symbol Tables)  └─────────────┘   └────────────┘   └────────────┘         │┌────────┴─────────┐│ (Creates)        │▼                  ▼                  ▼┌────────────┐   ┌─────────────┐   ┌────────────┐│ Expression │   │ Transformer │   │ uCalc.String │└────────────┘   └─────────────┘   └────────────┘      │                 │      │ (Evaluates)     │ (Owns)      │                 │      ▼                 ▼┌──────────┐      ┌─────────┐│ Callback │      │  Rules  │└──────────┘      └─────────┘                        │                        │ (Produces)                        │                        ▼                    ┌─────────┐                    │ Matches │                    └─────────┘

Examples

Illustrates the core relationship between the uCalc engine, an Item (variable), and a compiled Expression.

ID: 31

See: Evaluate, Introduction, Memory Management, Parse, Release, Release, The uCalc Object Model - A High-Level Overview, uCalc Fast Math Parser, Value(double) 
				
					using uCalcSoftware;

var uc = new uCalc();
var VariableX = uc.DefineVariable("x");
var Expression = "x^2 * 10"; // Replace this with your expression

Console.WriteLine("--- Efficient: Parse() once, then Evaluate() in a loop ---");
var ParsedExpr = uc.Parse(Expression);
for (double x = 1; x <= 10; x++) {
   VariableX.Value(x);
   Console.WriteLine(ParsedExpr.Evaluate());
}

ParsedExpr.Release();
VariableX.Release();
				
			
--- Efficient: Parse() once, then Evaluate() in a loop ---
10
40
90
160
250
360
490
640
810
1000
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto VariableX = uc.DefineVariable("x");
   auto Expression = "x^2 * 10"; // Replace this with your expression

   cout << "--- Efficient: Parse() once, then Evaluate() in a loop ---" << endl;
   auto ParsedExpr = uc.Parse(Expression);
   for (double x = 1; x <= 10; x++) {
      VariableX.Value(x);
      cout << ParsedExpr.Evaluate() << endl;
   }

   ParsedExpr.Release();
   VariableX.Release();
}
				
			
--- Efficient: Parse() once, then Evaluate() in a loop ---
10
40
90
160
250
360
490
640
810
1000
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim VariableX = uc.DefineVariable("x")
      Dim Expression = "x^2 * 10" '// Replace this with your expression
      
      Console.WriteLine("--- Efficient: Parse() once, then Evaluate() in a loop ---")
      Dim ParsedExpr = uc.Parse(Expression)
      For x  As Double = 1 To 10
         VariableX.Value(x)
         Console.WriteLine(ParsedExpr.Evaluate())
      Next
      
      ParsedExpr.Release()
      VariableX.Release()
   End Sub
End Module
				
			
--- Efficient: Parse() once, then Evaluate() in a loop ---
10
40
90
160
250
360
490
640
810
1000
Explore 600+ other examples
Demonstrates how a Transformer is created from a uCalc instance and used to apply Rules to text.

ID: 1335

See: The uCalc Object Model - A High-Level Overview 
				
					using uCalcSoftware;

var uc = new uCalc();

// 1. The uCalc instance (uc) is the factory

// 2. Create a Transformer from the instance
using (var t = new uCalc.Transformer(uc)) {
   // 3. Define a Rule on the transformer
   t.FromTo("apple", "FRUIT");

   // 4. Process text and get the result
   Console.WriteLine(t.Transform("An apple a day."));
};
				
			
An FRUIT a day.
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;

   // 1. The uCalc instance (uc) is the factory

   // 2. Create a Transformer from the instance
   {
      uCalc::Transformer t(uc);
      t.Owned(); // Causes t to be released when it goes out of scope
      // 3. Define a Rule on the transformer
      t.FromTo("apple", "FRUIT");

      // 4. Process text and get the result
      cout << t.Transform("An apple a day.") << endl;
   };
}
				
			
An FRUIT a day.
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      '// 1. The uCalc instance (uc) is the factory
      
      '// 2. Create a Transformer from the instance
      Using t As New uCalc.Transformer(uc)
         '// 3. Define a Rule on the transformer
         t.FromTo("apple", "FRUIT")
         
         '// 4. Process text and get the result
         Console.WriteLine(t.Transform("An apple a day."))
      End Using
   End Sub
End Module
				
			
An FRUIT a day.
Explore 600+ other examples
Shows the creation of a uCalc.String and its use of a fluent, token-aware API to modify text in-place.

ID: 1336

See: The uCalc Object Model - A High-Level Overview 
				
					using uCalcSoftware;

var uc = new uCalc();
// 1. Create a uCalc.String with a parent uCalc instance
using (var s = new uCalc.String(uc, "The user is <admin>.")) {
   // 2. Use the fluent, token-aware API
   s.After("is").Between("<", ">").ToUpper();

   // 3. The original string is modified in-place
   Console.WriteLine(s);
};
				
			
The user is <ADMIN>.
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // 1. Create a uCalc.String with a parent uCalc instance
   {
      uCalc::String s(uc, "The user is <admin>.");
      s.Owned(); // Causes s to be released when it goes out of scope
      // 2. Use the fluent, token-aware API
      s.After("is").Between("<", ">").ToUpper();

      // 3. The original string is modified in-place
      cout << s << endl;
   };
}
				
			
The user is <ADMIN>.
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// 1. Create a uCalc.String with a parent uCalc instance
      Using s As New uCalc.String(uc, "The user is <admin>.")
         '// 2. Use the fluent, token-aware API
         s.After("is").Between("<", ">").ToUpper()
         
         '// 3. The original string is modified in-place
         Console.WriteLine(s)
      End Using
   End Sub
End Module
				
			
The user is <ADMIN>.
Explore 600+ other examples