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: 

Fast Math Parser

Class: 

Item

Removes a defined symbol (like a function, variable, or rule) from the uCalc instance, freeing its resources and making it unavailable for future use.

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.

🆚 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

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
Previous
Next