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: 

Rule

Permanently removes a defined Transformer rule, freeing its resources and making it unavailable for future operations.

Syntax

Release()

Parameters

[None]

Return

void

This method does not return a value.

Remarks

The Release method is the primary mechanism for manual memory management of uCalc symbols. When an item such as a function, variable, or transformer rule is no longer needed, calling Release() removes it from the uCalc instance, frees its associated resources, and makes its name available for reuse.

💡 Key Use Cases

While its main purpose is resource management, Release() enables several powerful patterns:

  • Standard Cleanup: The most common use is to free memory by removing temporary variables, expressions, or rules at the end of a process. This prevents memory leaks in long-running applications.

  • Un-shadowing Definitions: uCalc allows multiple definitions for the same name, creating a stack where the newest definition shadows older ones. Releasing the newest Item pops it from the stack, automatically restoring the previous definition. This is a powerful feature for managing layered configurations or temporary overrides.

  • Deactivating Rules and Aliases: Releasing an Item that represents a Transformer rule, a Format rule, or an Alias effectively deactivates that specific behavior without affecting other definitions.

🗑️ Manual vs. Automatic Release

There are two primary ways an Item's resources are reclaimed:

  1. Manual Release (Explicit)Calling myItem.Release() directly gives you precise control over the lifetime of an object.

  2. Automatic Release (Implicit)

    • Parent Release: Releasing a parent container object automatically releases all of its children. For example, calling Release() on a uCalc instance will release every function, variable, and expression defined within it.
    • Scoped Release: uCalc objects can be configured for automatic release when they go out of scope, using language-specific constructs like using in C# or using Owned in C++. For more details, see the uCalc.Constructor topic.

🆚 Release() vs. Active(false)

It is crucial to understand the difference between permanently removing a rule and temporarily deactivating it.

ActionmyRule.Release()myRule.Active(false)
EffectPermanent Deletion. The rule's definition is removed from memory.Temporary Deactivation. The rule's definition is preserved.
ReversibilityIrreversible. The rule must be redefined.Reversible by calling myRule.Active(true).
Use CaseCleaning up resources for a rule that is no longer needed.Temporarily disabling a rule for a specific operation.

⚖️ Comparative Analysis

uCalc's memory model is distinct from both standard garbage collection (GC) and native C++ RAII.

  • vs. Garbage Collection (C#): The C# Item object is a lightweight handle to a more substantial object inside the core uCalc engine. Even if the C# handle is garbage collected, the underlying engine object will not be released. You must call Release() or use using to free the engine's resources. Failure to do so can lead to memory leaks within the uCalc instance, even in a managed environment.

  • vs. C++ Destructors: Similarly, a C++ Item object going out of scope does not automatically release the underlying engine resource unless it is explicitly configured as Owned. Release() provides deterministic cleanup.

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

Examples

Internal Test: Verifies that releasing a rule correctly 'un-shadows' a previously defined rule with the same pattern.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.Text = "The quick brown fox.";

// 1. Define the original rule
var ruleV1 = t.FromTo("brown", "BROWN_V1");
Console.WriteLine($"Initial transform: {t.Transform()}");

// 2. Define a new rule with the same pattern, shadowing the original
t.Text = "The quick brown fox.";
var ruleV2 = t.FromTo("brown", "BROWN_V2");
Console.WriteLine($"After shadowing: {t.Transform()}");

// 3. Release the new rule. The original rule should become active again.
t.Text = "The quick brown fox.";
ruleV2.Release();
Console.WriteLine($"After release (reverted): {t.Transform()}");
				
			
Initial transform: The quick BROWN_V1 fox.
After shadowing: The quick BROWN_V2 fox.
After release (reverted): The quick BROWN_V1 fox.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.Text("The quick brown fox.");

   // 1. Define the original rule
   auto ruleV1 = t.FromTo("brown", "BROWN_V1");
   cout << "Initial transform: " << t.Transform() << endl;

   // 2. Define a new rule with the same pattern, shadowing the original
   t.Text("The quick brown fox.");
   auto ruleV2 = t.FromTo("brown", "BROWN_V2");
   cout << "After shadowing: " << t.Transform() << endl;

   // 3. Release the new rule. The original rule should become active again.
   t.Text("The quick brown fox.");
   ruleV2.Release();
   cout << "After release (reverted): " << t.Transform() << endl;
}
				
			
Initial transform: The quick BROWN_V1 fox.
After shadowing: The quick BROWN_V2 fox.
After release (reverted): The quick BROWN_V1 fox.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.Text = "The quick brown fox."
      
      '// 1. Define the original rule
      Dim ruleV1 = t.FromTo("brown", "BROWN_V1")
      Console.WriteLine($"Initial transform: {t.Transform()}")
      
      '// 2. Define a new rule with the same pattern, shadowing the original
      t.Text = "The quick brown fox."
      Dim ruleV2 = t.FromTo("brown", "BROWN_V2")
      Console.WriteLine($"After shadowing: {t.Transform()}")
      
      '// 3. Release the new rule. The original rule should become active again.
      t.Text = "The quick brown fox."
      ruleV2.Release()
      Console.WriteLine($"After release (reverted): {t.Transform()}")
   End Sub
End Module
				
			
Initial transform: The quick BROWN_V1 fox.
After shadowing: The quick BROWN_V2 fox.
After release (reverted): The quick BROWN_V1 fox.
A succinct example demonstrating how to define and then permanently remove a rule.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
string text = "(this and that) <this or that>";
t.Text = text;

// Define two rules
var rule1 = t.FromTo("({txt})", "#{txt}#");
var rule2 = t.FromTo("<{txt}>", "${txt}$");

// Transform with both rules active
Console.WriteLine(t.Transform());

// Release the first rule
rule1.Release();

// Re-run the transformation; only the second rule applies
t.Text = text;
Console.WriteLine(t.Transform());
				
			
#this and that# $this or that$
(this and that) $this or that$
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   string text = "(this and that) <this or that>";
   t.Text(text);

   // Define two rules
   auto rule1 = t.FromTo("({txt})", "#{txt}#");
   auto rule2 = t.FromTo("<{txt}>", "${txt}$");

   // Transform with both rules active
   cout << t.Transform() << endl;

   // Release the first rule
   rule1.Release();

   // Re-run the transformation; only the second rule applies
   t.Text(text);
   cout << t.Transform() << endl;
}
				
			
#this and that# $this or that$
(this and that) $this or that$
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      Dim text As String = "(this and that) <this or that>"
      t.Text = text
      
      '// Define two rules
      Dim rule1 = t.FromTo("({txt})", "#{txt}#")
      Dim rule2 = t.FromTo("<{txt}>", "${txt}$")
      
      '// Transform with both rules active
      Console.WriteLine(t.Transform())
      
      '// Release the first rule
      rule1.Release()
      
      '// Re-run the transformation; only the second rule applies
      t.Text = text
      Console.WriteLine(t.Transform())
   End Sub
End Module
				
			
#this and that# $this or that$
(this and that) $this or that$
Previous
Next