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.

Owned

Method

Product: 

Transformer Library

Class: 

Transformer

Marks the Transformer object for automatic memory release when it goes out of scope, enabling RAII-style lifetime management in C++.

Syntax

Owned()

Parameters

[None]

Return

Transformer

Returns the current Transformer instance to allow for method chaining.

Remarks

🛡️ Managing Transformer Lifetime: The Owned Method

The Owned() method is a crucial memory management tool, primarily for C++, that flags a Transformer object for automatic release when its corresponding variable goes out of scope. This aligns with the C++ RAII (Resource Acquisition Is Initialization) paradigm, preventing memory leaks by ensuring resources are cleaned up deterministically.

A Transformer can be a resource-intensive object, holding compiled rules, token sets, and match results. Proper resource management is essential.

C++: Embracing RAII

Owned() is designed specifically for C++ developers to leverage the RAII pattern. When you declare an object as "owned", its destructor will automatically call Release(), ensuring resources are freed when the object goes out of scope.

C# and VB.NET: The using Keyword

In .NET languages, Owned() is not needed. The idiomatic way to ensure automatic resource cleanup is to use the using statement (C#) or Using block (VB.NET). All major uCalc objects, including Transformer, implement IDisposable, which integrates directly with this language feature.

// The 'using' statement ensures myParser.Release() is called automatically.using (var myParser = uc.NewTransformer()){    myParser.FromTo("a", "b");    Console.WriteLine(myParser.Transform("a c a"));} // myParser is released here.

Comparative Analysis

  • vs. Standard Smart Pointers (std::unique_ptr): A C++ developer might ask, "Why not just return a std::unique_ptr<Transformer>?" uCalc uses an internal, cross-platform reference counting and object management system. The Owned() method acts as a bridge, allowing the C++-specific RAII pattern to interface cleanly with uCalc's internal lifetime management without exposing implementation details.

  • vs. Manual Release() Calls: Forgetting to call Release() is a common source of memory leaks. Using Owned() in C++ (or using in C#) makes resource management declarative and less error-prone. The cleanup is guaranteed by the language's scoping rules, leading to safer and more robust code.

Examples

"using" (C#) and Owned (C++) for auto-releasing Transformer object
				
					using uCalcSoftware;

var uc = new uCalc();

// In C# and VB you should use "using".
// In C++ you can flag a uCalc object for
// auto-release with Owned(), or by setting
// the last parameter of the constructor to true.

var t = new uCalc.Transformer(uc);
var MemIndex = t.MemoryIndex;
t.Release(); // MemIndex will be recycled and assigned to the next def

// Use "using" so that the object is auto-released when it it goes out of scope
using (var TempTransform = new uCalc.Transformer(uc)) {
   Console.WriteLine(TempTransform.MemoryIndex == MemIndex); // MemoryIndex() will be the recycled value of the released t object
}
// TempTransform goes out of scope here

var t3 = new uCalc.Transformer(uc);
Console.WriteLine(t3.MemoryIndex == MemIndex); // MemoryIndex() will be the recycled value of the released TempTransform object
t3.Release();

{
   // Use "using" so that the object is auto-released when it it goes out of scope
   var StickyTransformer = new uCalc.Transformer(uc);
   Console.WriteLine(StickyTransformer.MemoryIndex == MemIndex);
} // StickyTransformer remains in memery

var t4 = new uCalc.Transformer(uc);
Console.WriteLine(t4.MemoryIndex == MemIndex); // False since StickyTransformer was not released; MemoryIndex() has a new value
				
			
True
True
True
False
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

int main() {
   uCalc uc;

   // In C# and VB you should use "using".
   // In C++ you can flag a uCalc object for
   // auto-release with Owned(), or by setting
   // the last parameter of the constructor to true.

   uCalc::Transformer t(uc);
   auto MemIndex = t.MemoryIndex();
   t.Release(); // MemIndex will be recycled and assigned to the next def


   {
      uCalc::Transformer TempTransform(uc);
      TempTransform.Owned(); // Causes TempTransform to be released when it goes out of scope // Owned() causes TempTransform to be released when it goes out of scope
      cout << tf(TempTransform.MemoryIndex() == MemIndex) << endl; // MemoryIndex() will be the recycled value of the released t object
   }
   // TempTransform goes out of scope here

   uCalc::Transformer t3(uc);
   cout << tf(t3.MemoryIndex() == MemIndex) << endl; // MemoryIndex() will be the recycled value of the released TempTransform object
   t3.Release();

   {
      uCalc::Transformer StickyTransformer(uc); // StickyTransformer here does NOT get released when it goes out of scope
      cout << tf(StickyTransformer.MemoryIndex() == MemIndex) << endl;
   } // StickyTransformer remains in memery

   uCalc::Transformer t4(uc);
   cout << tf(t4.MemoryIndex() == MemIndex) << endl; // False since StickyTransformer was not released; MemoryIndex() has a new value
}
				
			
True
True
True
False
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      '// In C# and VB you should use "using".
      '// In C++ you can flag a uCalc object for
      '// auto-release with Owned(), or by setting
      '// the last parameter of the constructor to true.
      
      Dim t As New uCalc.Transformer(uc)
      Dim MemIndex = t.MemoryIndex
      t.Release() '// MemIndex will be recycled and assigned to the next def
      
      '// Use "using" so that the object is auto-released when it it goes out of scope
      Using TempTransform As New uCalc.Transformer(uc)
         Console.WriteLine(TempTransform.MemoryIndex = MemIndex) '// MemoryIndex() will be the recycled value of the released t object
      End Using
      '// TempTransform goes out of scope here
      
      Dim t3 As New uCalc.Transformer(uc)
      Console.WriteLine(t3.MemoryIndex = MemIndex) '// MemoryIndex() will be the recycled value of the released TempTransform object
      t3.Release()
      
      If True Then
         '// Use "using" so that the object is auto-released when it it goes out of scope
         Dim StickyTransformer As New uCalc.Transformer(uc)
         Console.WriteLine(StickyTransformer.MemoryIndex = MemIndex)
      End If '// StickyTransformer remains in memery
      
      Dim t4 As New uCalc.Transformer(uc)
      Console.WriteLine(t4.MemoryIndex = MemIndex) '// False since StickyTransformer was not released; MemoryIndex() has a new value
   End Sub
End Module
				
			
True
True
True
False
Previous
Next