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.

uCalc = [uCalc]

Property

Product: 

Fast Math Parser

Class: 

Expression

Returns the parent uCalc instance that owns this expression, providing access to its evaluation context.

Remarks

Every parsed Expression object is intrinsically linked to the uCalc instance that created it. This parent instance holds the complete context—variables, functions, operators, and settings—required to evaluate the expression. The uCalc() method provides a way to retrieve this parent instance, enabling you to inspect or modify the evaluation environment dynamically.

🎯 Core Use Cases

  1. Contextual Modification: You can parse an expression and then, before evaluating it, use its uCalc() method to modify the environment. This is useful for dynamically adding a function or variable that the expression requires.

  2. Multi-Instance Management: In applications that use multiple uCalc instances (e.g., for sandboxing or different configurations), an Expression object might be passed between different parts of your code. This method allows you to reliably determine which engine an expression belongs to, which is crucial for debugging and ensuring correct evaluation.

  3. Introspection: It serves as a key tool for introspection, allowing you to query the state of the engine that will ultimately be used to evaluate the expression.

💡 Comparative Analysis

  • vs. C# LINQ Expressions: A LINQ Expression tree is a pure data structure representing code. It has no inherent evaluation context. You provide the context later when you compile it into a delegate. In contrast, a uCalc Expression is pre-bound to its context. This makes evaluation simpler as the context is implicit, and the uCalc() method makes that context explicitly retrievable.

  • vs. Global Evaluators: Many simple math evaluators operate with a single, global context. uCalc's multi-instance design provides superior encapsulation and safety. The uCalc() method is the bridge that connects a specific expression back to its sandboxed environment, a feature not present in globally-scoped evaluators.

Examples

A succinct example demonstrating that each parsed expression is owned by the uCalc instance that created it.
				
					using uCalcSoftware;

var uc = new uCalc();
// Succinct (Quick Start)
// Create two separate uCalc instances
var uc1 = new uCalc();
var uc2 = new uCalc();

// Parse the same expression string in both instances
var expr1 = uc1.Parse("1 + 1");
var expr2 = uc2.Parse("1 + 1");

// Use the .uCalc() method and MemoryIndex to verify ownership
Console.WriteLine($"expr1 belongs to uc1: {expr1.uCalc.MemoryIndex == uc1.MemoryIndex}");
Console.WriteLine($"expr2 belongs to uc2: {expr2.uCalc.MemoryIndex == uc2.MemoryIndex}");
Console.WriteLine($"expr1 does not belong to uc2: {expr1.uCalc.MemoryIndex != uc2.MemoryIndex}");
				
			
expr1 belongs to uc1: True
expr2 belongs to uc2: True
expr1 does not belong to uc2: True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

int main() {
   uCalc uc;
   // Succinct (Quick Start)
   // Create two separate uCalc instances
   uCalc uc1;
   uCalc uc2;

   // Parse the same expression string in both instances
   auto expr1 = uc1.Parse("1 + 1");
   auto expr2 = uc2.Parse("1 + 1");

   // Use the .uCalc() method and MemoryIndex to verify ownership
   cout << "expr1 belongs to uc1: " << tf(expr1.uCalc().MemoryIndex() == uc1.MemoryIndex()) << endl;
   cout << "expr2 belongs to uc2: " << tf(expr2.uCalc().MemoryIndex() == uc2.MemoryIndex()) << endl;
   cout << "expr1 does not belong to uc2: " << tf(expr1.uCalc().MemoryIndex() != uc2.MemoryIndex()) << endl;
}
				
			
expr1 belongs to uc1: True
expr2 belongs to uc2: True
expr1 does not belong to uc2: True
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Succinct (Quick Start)
      '// Create two separate uCalc instances
      Dim uc1 As New uCalc()
      Dim uc2 As New uCalc()
      
      '// Parse the same expression string in both instances
      Dim expr1 = uc1.Parse("1 + 1")
      Dim expr2 = uc2.Parse("1 + 1")
      
      '// Use the .uCalc() method and MemoryIndex to verify ownership
      Console.WriteLine($"expr1 belongs to uc1: {expr1.uCalc.MemoryIndex = uc1.MemoryIndex}")
      Console.WriteLine($"expr2 belongs to uc2: {expr2.uCalc.MemoryIndex = uc2.MemoryIndex}")
      Console.WriteLine($"expr1 does not belong to uc2: {expr1.uCalc.MemoryIndex <> uc2.MemoryIndex}")
   End Sub
End Module
				
			
expr1 belongs to uc1: True
expr2 belongs to uc2: True
expr1 does not belong to uc2: True
A practical example of retrieving an expression's parent uCalc instance to dynamically add a formatting rule before evaluation.
				
					using uCalcSoftware;

var uc = new uCalc();
// Practical (Real World)
// Parse an expression
var myExpr = uc.Parse("5 + 4");
Console.WriteLine($"Initial evaluation: {myExpr.Evaluate()}");

// Retrieve the parent uCalc instance from the expression object
var parentUc = myExpr.uCalc;

// Use the parent instance to add a new formatting rule
parentUc.Format("Result = 'Answer = ' + Result");

// The new format is now active for this expression's context
Console.WriteLine($"Formatted evaluation: {myExpr.EvaluateStr()}");
				
			
Initial evaluation: 9
Formatted evaluation: Answer = 9
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Practical (Real World)
   // Parse an expression
   auto myExpr = uc.Parse("5 + 4");
   cout << "Initial evaluation: " << myExpr.Evaluate() << endl;

   // Retrieve the parent uCalc instance from the expression object
   auto parentUc = myExpr.uCalc();

   // Use the parent instance to add a new formatting rule
   parentUc.Format("Result = 'Answer = ' + Result");

   // The new format is now active for this expression's context
   cout << "Formatted evaluation: " << myExpr.EvaluateStr() << endl;
}
				
			
Initial evaluation: 9
Formatted evaluation: Answer = 9
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Practical (Real World)
      '// Parse an expression
      Dim myExpr = uc.Parse("5 + 4")
      Console.WriteLine($"Initial evaluation: {myExpr.Evaluate()}")
      
      '// Retrieve the parent uCalc instance from the expression object
      Dim parentUc = myExpr.uCalc
      
      '// Use the parent instance to add a new formatting rule
      parentUc.Format("Result = 'Answer = ' + Result")
      
      '// The new format is now active for this expression's context
      Console.WriteLine($"Formatted evaluation: {myExpr.EvaluateStr()}")
   End Sub
End Module
				
			
Initial evaluation: 9
Formatted evaluation: Answer = 9
An internal test verifying that an expression remains tied to its original context, even after the context has been cloned and modified.
				
					using uCalcSoftware;

var uc = new uCalc();
// Internal Test: Context integrity after cloning
var baseUc = new uCalc();
baseUc.DefineVariable("x = 100");

// Clone the base instance and modify the variable in the clone
var clonedUc = baseUc.Clone();
clonedUc.Eval("x = 200");

// Parse an expression in the original base context
var baseExpr = baseUc.Parse("x");

// 1. Verify the expression evaluates using its original context's value
Console.WriteLine($"Base expression evaluates to: {baseExpr.Evaluate()}");

// 2. Get the parent and verify it is not the cloned instance
Console.WriteLine($"Parent is not the clone: {baseExpr.uCalc.MemoryIndex != clonedUc.MemoryIndex}");
				
			
Base expression evaluates to: 100
Parent is not the clone: True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

int main() {
   uCalc uc;
   // Internal Test: Context integrity after cloning
   uCalc baseUc;
   baseUc.DefineVariable("x = 100");

   // Clone the base instance and modify the variable in the clone
   auto clonedUc = baseUc.Clone();
   clonedUc.Eval("x = 200");

   // Parse an expression in the original base context
   auto baseExpr = baseUc.Parse("x");

   // 1. Verify the expression evaluates using its original context's value
   cout << "Base expression evaluates to: " << baseExpr.Evaluate() << endl;

   // 2. Get the parent and verify it is not the cloned instance
   cout << "Parent is not the clone: " << tf(baseExpr.uCalc().MemoryIndex() != clonedUc.MemoryIndex()) << endl;
}
				
			
Base expression evaluates to: 100
Parent is not the clone: True
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Internal Test: Context integrity after cloning
      Dim baseUc As New uCalc()
      baseUc.DefineVariable("x = 100")
      
      '// Clone the base instance and modify the variable in the clone
      Dim clonedUc = baseUc.Clone()
      clonedUc.Eval("x = 200")
      
      '// Parse an expression in the original base context
      Dim baseExpr = baseUc.Parse("x")
      
      '// 1. Verify the expression evaluates using its original context's value
      Console.WriteLine($"Base expression evaluates to: {baseExpr.Evaluate()}")
      
      '// 2. Get the parent and verify it is not the cloned instance
      Console.WriteLine($"Parent is not the clone: {baseExpr.uCalc.MemoryIndex <> clonedUc.MemoryIndex}")
   End Sub
End Module
				
			
Base expression evaluates to: 100
Parent is not the clone: True
Gets uCalc object associated with an expression
				
					using uCalcSoftware;

var uc = new uCalc();
var MyExpr = uc.Parse("5+4");

Console.WriteLine(MyExpr.Evaluate());

MyExpr.uCalc.Format("Result = 'Answer = ' + Result");

Console.WriteLine(MyExpr.EvaluateStr());
				
			
9
Answer = 9
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto MyExpr = uc.Parse("5+4");

   cout << MyExpr.Evaluate() << endl;

   MyExpr.uCalc().Format("Result = 'Answer = ' + Result");

   cout << MyExpr.EvaluateStr() << endl;
}
				
			
9
Answer = 9
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim MyExpr = uc.Parse("5+4")
      
      Console.WriteLine(MyExpr.Evaluate())
      
      MyExpr.uCalc.Format("Result = 'Answer = ' + Result")
      
      Console.WriteLine(MyExpr.EvaluateStr())
   End Sub
End Module
				
			
9
Answer = 9
Previous
Next