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: 

Transformer Library

Class: 

Matches

Retrieves the parent uCalc instance that owns the transformer and its matches, providing access to the full evaluation context.

Remarks

🎯 Retrieving the Execution Context

Every Matches object is intrinsically linked to the uCalc instance that created its parent Transformer. This parent instance holds the complete context—variables, functions, operators, and settings—required for any subsequent evaluations. The uCalc() property provides a way to retrieve this parent instance, enabling you to inspect or modify the evaluation environment dynamically.

This is a read-only property.

💡 Core Use Cases

  1. Contextual Operations: The most common use is to perform another operation within the same context as the matches. If you have a Matches object but not a direct reference to its parent uCalc instance, you can use this property to retrieve it and call methods like Eval() or DefineVariable().

  2. Instance Introspection: It allows you to determine if two different Matches collections belong to the same execution context, which is invaluable for debugging applications that manage multiple, isolated uCalc instances.

  3. Accessing Sibling Items: Once you retrieve the parent instance, you can use it to find other items within the same sandbox, for example: myMatches.uCalc.ItemOf("SomeOtherVar").

⚖️ Comparative Analysis

  • vs. Native Objects (C#/C++): In standard object-oriented programming, an object typically does not maintain a public reference to the factory or container that created it. You would have to design this relationship manually. uCalc makes this parent-child link a first-class, built-in feature, simplifying the management of multiple, concurrent parsing environments.

  • vs. Document Object Model (DOM): The relationship is analogous to the DOM in web development. Just as an HTML element has an ownerDocument property that points back to the document it belongs to, a uCalc Matches object has its uCalc() property to get back to its owner instance. This provides a consistent and predictable way to navigate the object hierarchy.

Examples

A succinct example showing how to retrieve the parent uCalc instance from a Matches object and verify its identity.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "some text";
t.Pattern("some");
t.Find();
var m = t.Matches;

// Get the parent uCalc instance from the Matches collection
var parent_uc = m.uCalc;

// Verify they are the same instance using their MemoryIndex
Console.WriteLine(parent_uc.MemoryIndex == uc.MemoryIndex);
				
			
True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("some text");
   t.Pattern("some");
   t.Find();
   auto m = t.Matches();

   // Get the parent uCalc instance from the Matches collection
   auto parent_uc = m.uCalc();

   // Verify they are the same instance using their MemoryIndex
   cout << tf(parent_uc.MemoryIndex() == uc.MemoryIndex()) << endl;
}
				
			
True
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "some text"
      t.Pattern("some")
      t.Find()
      Dim m = t.Matches
      
      '// Get the parent uCalc instance from the Matches collection
      Dim parent_uc = m.uCalc
      
      '// Verify they are the same instance using their MemoryIndex
      Console.WriteLine(parent_uc.MemoryIndex = uc.MemoryIndex)
   End Sub
End Module
				
			
True
Demonstrates context isolation by retrieving the parent uCalc instance from a Matches object and evaluating an expression that only exists in that parent's context.
				
					using uCalcSoftware;

var uc = new uCalc();
var uc1 = new uCalc();
uc1.DefineVariable("val = 100");

var uc2 = new uCalc();
uc2.DefineVariable("val = 200");

// Create the transformer in uc1's context
var t = uc1.NewTransformer();
t.Text = "data";
t.Pattern("data");
t.Find();

var m = t.Matches;
var parent_uc = m.uCalc;

Console.WriteLine($"Parent has value: {parent_uc.Eval("val")}");
Console.WriteLine($"Is parent uc1? {parent_uc.MemoryIndex == uc1.MemoryIndex}");
Console.WriteLine($"Is parent uc2? {parent_uc.MemoryIndex == uc2.MemoryIndex}");
				
			
Parent has value: 100
Is parent uc1? True
Is parent uc2? False
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

int main() {
   uCalc uc;
   uCalc uc1;
   uc1.DefineVariable("val = 100");

   uCalc uc2;
   uc2.DefineVariable("val = 200");

   // Create the transformer in uc1's context
   auto t = uc1.NewTransformer();
   t.Text("data");
   t.Pattern("data");
   t.Find();

   auto m = t.Matches();
   auto parent_uc = m.uCalc();

   cout << "Parent has value: " << parent_uc.Eval("val") << endl;
   cout << "Is parent uc1? " << tf(parent_uc.MemoryIndex() == uc1.MemoryIndex()) << endl;
   cout << "Is parent uc2? " << tf(parent_uc.MemoryIndex() == uc2.MemoryIndex()) << endl;
}
				
			
Parent has value: 100
Is parent uc1? True
Is parent uc2? False
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim uc1 As New uCalc()
      uc1.DefineVariable("val = 100")
      
      Dim uc2 As New uCalc()
      uc2.DefineVariable("val = 200")
      
      '// Create the transformer in uc1's context
      Dim t = uc1.NewTransformer()
      t.Text = "data"
      t.Pattern("data")
      t.Find()
      
      Dim m = t.Matches
      Dim parent_uc = m.uCalc
      
      Console.WriteLine($"Parent has value: {parent_uc.Eval("val")}")
      Console.WriteLine($"Is parent uc1? {parent_uc.MemoryIndex = uc1.MemoryIndex}")
      Console.WriteLine($"Is parent uc2? {parent_uc.MemoryIndex = uc2.MemoryIndex}")
   End Sub
End Module
				
			
Parent has value: 100
Is parent uc1? True
Is parent uc2? False
Internal Test: Verifies that the parent uCalc instance can be retrieved even from an empty Matches collection.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
// NOTE: We do NOT call t.Find(), so the matches collection is empty.

var m = t.Matches;

Console.WriteLine($"Match count: {m.Count()}");

// Even with no matches, the parent context should be accessible
var parent_uc = m.uCalc;

Console.WriteLine($"Parent uCalc is valid: {parent_uc.MemoryIndex == uc.MemoryIndex}");
				
			
Match count: 0
Parent uCalc is valid: True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   // NOTE: We do NOT call t.Find(), so the matches collection is empty.

   auto m = t.Matches();

   cout << "Match count: " << m.Count() << endl;

   // Even with no matches, the parent context should be accessible
   auto parent_uc = m.uCalc();

   cout << "Parent uCalc is valid: " << tf(parent_uc.MemoryIndex() == uc.MemoryIndex()) << endl;
}
				
			
Match count: 0
Parent uCalc is valid: True
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      '// NOTE: We do NOT call t.Find(), so the matches collection is empty.
      
      Dim m = t.Matches
      
      Console.WriteLine($"Match count: {m.Count()}")
      
      '// Even with no matches, the parent context should be accessible
      Dim parent_uc = m.uCalc
      
      Console.WriteLine($"Parent uCalc is valid: {parent_uc.MemoryIndex = uc.MemoryIndex}")
   End Sub
End Module
				
			
Match count: 0
Parent uCalc is valid: True
Previous
Next