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.

Clone

Method

Product: 

Transformer Library

Class: 

Transformer

Creates an identical, yet completely independent, copy of the Transformer object, including all its rules and settings.

Syntax

Clone()

Parameters

[None]

Return

Transformer

A new, independent Transformer instance that is a complete replica of the original.

Remarks

The Clone method creates a deep, independent copy of a Transformer object. This is a highly efficient operation, as it duplicates the transformer's internal state directly in memory, which is significantly faster than creating a new transformer and redefining all its rules and tokens from scratch.

What is Cloned?

A clone is a complete replica of the original Transformer's state at the moment of cloning, including:

  • All Rules: Every FromTo and Pattern rule is copied.
  • Tokens: The entire collection of token definitions is duplicated.
  • Text: The current source string held by the transformer is copied.
  • Settings: All default rule settings (CaseSensitive, WhitespaceSensitive, etc.) are preserved.

Once created, the clone is completely independent; modifying the clone will not affect the original, and vice-versa.

🎯 Primary Use Cases

  1. Performance Optimization: Parsing a complex set of rules and token definitions can be computationally expensive. If you need to use the same configuration repeatedly, you should configure it once, and then Clone the Transformer object as needed. This avoids the high cost of repeated setup.

  2. Templating: Clone is perfect for creating a "template" pattern. You can create a base Transformer with a standard set of rules (e.g., for parsing a specific language or format). Then, for different tasks, you can Clone this base and add a few specialized rules to the clone, promoting modularity and reuse.

  3. Isolation & Sandboxing: Create a clone to experiment with temporary rules or transformations without altering the state of the original, master Transformer.

Transformer.Clone() vs. uCalc.Clone()

It is crucial to understand the difference between cloning a Transformer and cloning the entire uCalc engine:

MethodWhat It CopiesParent uCalc Instance
Transformer.Clone() (This Method)A single Transformer object.The clone belongs to the same parent uCalc instance as the original.
uCalc.Clone()The entire uCalc engine, including all variables, functions, and every Transformer within it.The clone creates a new, isolated parent uCalc instance.

Memory Management

A cloned Transformer object holds resources and must be released when no longer needed to prevent memory leaks. This can be done explicitly with Release() or automatically using language-specific scoping constructs like using in C# or Owned() in C++.

Examples

A succinct example demonstrating that a clone is independent and that modifying it does not affect the original.
				
					using uCalcSoftware;

var uc = new uCalc();
// 1. Create and configure the original transformer
var t1 = new uCalc.Transformer();
t1.FromTo("A", "B");
Console.WriteLine($"Original Transform: {t1.Transform("A C A")}");

// 2. Clone it
var t2 = t1.Clone();

// 3. Modify the clone. This does not affect the original.
t2.FromTo("C", "D");
Console.WriteLine($"Cloned Transform:   {t2.Transform("A C A")}");

// 4. Verify original is unchanged by re-running its transform
Console.WriteLine($"Original is Unchanged: {t1.Transform("A C A")}");
t2.Release();
t1.Release();
				
			
Original Transform: B C B
Cloned Transform:   B D B
Original is Unchanged: B C B
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // 1. Create and configure the original transformer
   uCalc::Transformer t1;
   t1.FromTo("A", "B");
   cout << "Original Transform: " << t1.Transform("A C A") << endl;

   // 2. Clone it
   auto t2 = t1.Clone();

   // 3. Modify the clone. This does not affect the original.
   t2.FromTo("C", "D");
   cout << "Cloned Transform:   " << t2.Transform("A C A") << endl;

   // 4. Verify original is unchanged by re-running its transform
   cout << "Original is Unchanged: " << t1.Transform("A C A") << endl;
   t2.Release();
   t1.Release();
}
				
			
Original Transform: B C B
Cloned Transform:   B D B
Original is Unchanged: B C B
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// 1. Create and configure the original transformer
      Dim t1 As New uCalc.Transformer()
      t1.FromTo("A", "B")
      Console.WriteLine($"Original Transform: {t1.Transform("A C A")}")
      
      '// 2. Clone it
      Dim t2 = t1.Clone()
      
      '// 3. Modify the clone. This does not affect the original.
      t2.FromTo("C", "D")
      Console.WriteLine($"Cloned Transform:   {t2.Transform("A C A")}")
      
      '// 4. Verify original is unchanged by re-running its transform
      Console.WriteLine($"Original is Unchanged: {t1.Transform("A C A")}")
      t2.Release()
      t1.Release()
   End Sub
End Module
				
			
Original Transform: B C B
Cloned Transform:   B D B
Original is Unchanged: B C B
A practical example using Clone() to create a specialized parser from a base template, demonstrating rule inheritance.
				
					using uCalcSoftware;

var uc = new uCalc();
// 1. Create a "base" HTML transformer template
var baseHtmlParser = new uCalc.Transformer();
baseHtmlParser.Description = "Base HTML Parser";
// Rule to skip over comments
baseHtmlParser.SkipOver("<!--{body}->");
// Rule to find any tag
baseHtmlParser.Pattern("<{tag}>");
baseHtmlParser.DefaultRuleSet.SetStatementSensitive(false);

// 2. Create a specialized clone to find only image tags
var imageParser = baseHtmlParser.Clone();
imageParser.Description = "Image Tag Finder";
imageParser.FromTo("<img {attribs} />", "FOUND_IMG_TAG");

string html = " <body> <img src='a.jpg' /> <!-- <img src='b.jpg' /> --> </body> ";

// The clone inherits the SkipOver rule from the base, so the commented img tag is ignored.
Console.WriteLine(imageParser.Transform(html));

imageParser.Release();
baseHtmlParser.Release();
				
			
 <body> FOUND_IMG_TAG <!-- <img src='b.jpg' /> --> </body> 
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // 1. Create a "base" HTML transformer template
   uCalc::Transformer baseHtmlParser;
   baseHtmlParser.Description("Base HTML Parser");
   // Rule to skip over comments
   baseHtmlParser.SkipOver("<!--{body}->");
   // Rule to find any tag
   baseHtmlParser.Pattern("<{tag}>");
   baseHtmlParser.DefaultRuleSet().SetStatementSensitive(false);

   // 2. Create a specialized clone to find only image tags
   auto imageParser = baseHtmlParser.Clone();
   imageParser.Description("Image Tag Finder");
   imageParser.FromTo("<img {attribs} />", "FOUND_IMG_TAG");

   string html = " <body> <img src='a.jpg' /> <!-- <img src='b.jpg' /> --> </body> ";

   // The clone inherits the SkipOver rule from the base, so the commented img tag is ignored.
   cout << imageParser.Transform(html) << endl;

   imageParser.Release();
   baseHtmlParser.Release();
}
				
			
 <body> FOUND_IMG_TAG <!-- <img src='b.jpg' /> --> </body> 
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// 1. Create a "base" HTML transformer template
      Dim baseHtmlParser As New uCalc.Transformer()
      baseHtmlParser.Description = "Base HTML Parser"
      '// Rule to skip over comments
      baseHtmlParser.SkipOver("<!--{body}->")
      '// Rule to find any tag
      baseHtmlParser.Pattern("<{tag}>")
      baseHtmlParser.DefaultRuleSet.SetStatementSensitive(false)
      
      '// 2. Create a specialized clone to find only image tags
      Dim imageParser = baseHtmlParser.Clone()
      imageParser.Description = "Image Tag Finder"
      imageParser.FromTo("<img {attribs} />", "FOUND_IMG_TAG")
      
      Dim html As String = " <body> <img src='a.jpg' /> <!-- <img src='b.jpg' /> --> </body> "
      
      '// The clone inherits the SkipOver rule from the base, so the commented img tag is ignored.
      Console.WriteLine(imageParser.Transform(html))
      
      imageParser.Release()
      baseHtmlParser.Release()
   End Sub
End Module
				
			
 <body> FOUND_IMG_TAG <!-- <img src='b.jpg' /> --> </body>
Previous
Next