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.

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.
				
					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
				
					#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
				
					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
Demonstrates how a Transformer is created from a uCalc instance and used to apply Rules to text.
				
					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.
				
					#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.
				
					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.
Shows the creation of a uCalc.String and its use of a fluent, token-aware API to modify text in-place.
				
					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>.
				
					#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>.
				
					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>.
Previous
Next