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.

Release

Method

Product: 

Transformer Library

Class: 

Transformer

Explicitly frees all memory and resources associated with a Transformer instance, including all of its defined rules, tokens, and match results.

Syntax

Release()

Parameters

[None]

Return

void

This method does not return a value.

Remarks

💾 Core Concept: Freeing Engine Resources

The Release() method explicitly destroys a Transformer instance and deallocates all of its associated resources, including rules, tokens, passes, match lists, and the internal text buffer. It is the primary mechanism for manual memory management within the uCalc ecosystem.

🤔 Why is Release() Necessary? (Comparative Analysis)

uCalc's memory model is different from standard garbage-collected or native memory management, making Release() essential.

  • vs. C# Garbage Collection (GC): In C#, when a Transformer object variable goes out of scope, the C# Garbage Collector only reclaims the memory for the handle (the C# wrapper object). The underlying C++ engine instance, which holds the bulk of the data, remains in memory. Release() is the signal to destroy that underlying engine instance. Without it, you will have a memory leak.

  • vs. C++ delete: uCalc uses its own internal memory manager for performance and object recycling. A Transformer handle is not a raw C++ pointer that can be managed with delete. Calling Release() ensures the object is returned to uCalc's internal pool correctly.

⚙️ Manual vs. Automatic Release (Best Practice)

While Release() provides manual control, the recommended approach is to use language-specific scoping mechanisms that call Release() for you automatically:

  • C# / VB.NET: Create the Transformer instance within a using block. The instance will be automatically released when the block is exited.
  • C++: For stack-allocated objects, call Owned() to enable RAII. The Transformer instance is released when its destructor is called at the end of its scope.

Use Release() explicitly only when the lifetime of the Transformer object is not tied to a specific lexical scope.

Release() vs. Active(false) vs. Reset()

It is crucial to choose the correct method for your needs:

MethodPurposeEffect on Object
Release() (This Method)Destroy the objectThe object is destroyed and its memory is freed. The handle becomes invalid.
Rule.Active(false)Temporarily disable a ruleThe rule's definition is preserved in memory but is ignored during matching.
Reset()Clear the object's stateThe Transformer object remains alive but is reset to its initial state (no text, no rules).

Idempotency Note: Release() is idempotent. Calling it multiple times on the same (already released) handle is safe and has no effect.

Examples

Pass()
				
					using uCalcSoftware;

var uc = new uCalc();
var FruitsXML =
"""

<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' />
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <Fruit CommonName='Mango' ScientificName='Mangifera indica' />
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' />
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' />
</Fruits>

""";

var t = uc.NewTransformer();
t.Text = FruitsXML;

var Pass1 = t.Pass();
var Pass2 = t.Pass();

Pass1.Description = "Pass A";
Pass1.FromTo("Fruits", "ListOfFruits");
Pass1.FromTo("<Fruit CommonName={@str:name} ScientificName={@str:sci_name} />", "<Fruit>{name}</Fruit>");

Pass2.Description = "Pass B";
Pass2.FromTo("{Fruit: Apple | Orange | Mango }", "{Fruit} *");
Pass2.FromTo("{Fruit: Banana | Grapes | Watermelon }", "{Fruit} **");

t.Transform();
Console.WriteLine("All passes");
Console.WriteLine("----------");
Console.WriteLine(t.Text);

Console.WriteLine(t.Pass(0).Description);
Console.WriteLine(t.Pass(1).Description);
Console.WriteLine($"Pass count: {t.PassCount()}");
Console.WriteLine("");

t.Str(FruitsXML);
Pass2.Release();
t.Transform();
Console.WriteLine("Pass1 only (Pass2 released)");
Console.WriteLine("---------------------------");
Console.WriteLine(t.Text);

				
			
All passes
----------

<ListOfFruits>
  <Fruit>Apple *</Fruit>
  <Fruit>Banana **</Fruit>
  <Fruit>Orange *</Fruit>
  <Fruit>Grapes **</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango *</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon **</Fruit>
</ListOfFruits>

Pass A
Pass B
Pass count: 2

Pass1 only (Pass2 released)
---------------------------

<ListOfFruits>
  <Fruit>Apple</Fruit>
  <Fruit>Banana</Fruit>
  <Fruit>Orange</Fruit>
  <Fruit>Grapes</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon</Fruit>
</ListOfFruits>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto FruitsXML =
   R"(
<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' />
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <Fruit CommonName='Mango' ScientificName='Mangifera indica' />
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' />
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' />
</Fruits>
)";

   auto t = uc.NewTransformer();
   t.Text(FruitsXML);

   auto Pass1 = t.Pass();
   auto Pass2 = t.Pass();

   Pass1.Description("Pass A");
   Pass1.FromTo("Fruits", "ListOfFruits");
   Pass1.FromTo("<Fruit CommonName={@str:name} ScientificName={@str:sci_name} />", "<Fruit>{name}</Fruit>");

   Pass2.Description("Pass B");
   Pass2.FromTo("{Fruit: Apple | Orange | Mango }", "{Fruit} *");
   Pass2.FromTo("{Fruit: Banana | Grapes | Watermelon }", "{Fruit} **");

   t.Transform();
   cout << "All passes" << endl;
   cout << "----------" << endl;
   cout << t.Text() << endl;

   cout << t.Pass(0).Description() << endl;
   cout << t.Pass(1).Description() << endl;
   cout << "Pass count: " << t.PassCount() << endl;
   cout << "" << endl;

   t.Str(FruitsXML);
   Pass2.Release();
   t.Transform();
   cout << "Pass1 only (Pass2 released)" << endl;
   cout << "---------------------------" << endl;
   cout << t.Text() << endl;

}
				
			
All passes
----------

<ListOfFruits>
  <Fruit>Apple *</Fruit>
  <Fruit>Banana **</Fruit>
  <Fruit>Orange *</Fruit>
  <Fruit>Grapes **</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango *</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon **</Fruit>
</ListOfFruits>

Pass A
Pass B
Pass count: 2

Pass1 only (Pass2 released)
---------------------------

<ListOfFruits>
  <Fruit>Apple</Fruit>
  <Fruit>Banana</Fruit>
  <Fruit>Orange</Fruit>
  <Fruit>Grapes</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon</Fruit>
</ListOfFruits>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim FruitsXML =
      "
<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' />
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <Fruit CommonName='Mango' ScientificName='Mangifera indica' />
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' />
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' />
</Fruits>
"
      
      Dim t = uc.NewTransformer()
      t.Text = FruitsXML
      
      Dim Pass1 = t.Pass()
      Dim Pass2 = t.Pass()
      
      Pass1.Description = "Pass A"
      Pass1.FromTo("Fruits", "ListOfFruits")
      Pass1.FromTo("<Fruit CommonName={@str:name} ScientificName={@str:sci_name} />", "<Fruit>{name}</Fruit>")
      
      Pass2.Description = "Pass B"
      Pass2.FromTo("{Fruit: Apple | Orange | Mango }", "{Fruit} *")
      Pass2.FromTo("{Fruit: Banana | Grapes | Watermelon }", "{Fruit} **")
      
      t.Transform()
      Console.WriteLine("All passes")
      Console.WriteLine("----------")
      Console.WriteLine(t.Text)
      
      Console.WriteLine(t.Pass(0).Description)
      Console.WriteLine(t.Pass(1).Description)
      Console.WriteLine($"Pass count: {t.PassCount()}")
      Console.WriteLine("")
      
      t.Str(FruitsXML)
      Pass2.Release()
      t.Transform()
      Console.WriteLine("Pass1 only (Pass2 released)")
      Console.WriteLine("---------------------------")
      Console.WriteLine(t.Text)
      
   End Sub
End Module
				
			
All passes
----------

<ListOfFruits>
  <Fruit>Apple *</Fruit>
  <Fruit>Banana **</Fruit>
  <Fruit>Orange *</Fruit>
  <Fruit>Grapes **</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango *</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon **</Fruit>
</ListOfFruits>

Pass A
Pass B
Pass count: 2

Pass1 only (Pass2 released)
---------------------------

<ListOfFruits>
  <Fruit>Apple</Fruit>
  <Fruit>Banana</Fruit>
  <Fruit>Orange</Fruit>
  <Fruit>Grapes</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon</Fruit>
</ListOfFruits>
Previous
Next