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.

(Constructor)

Constructor

Product: 

Transformer Library

Class: 

Transformer

Creates a new, token-aware text transformation engine for pattern matching and structural replacement.

Remarks

⚙️ The Transformer Engine

The Transformer constructor creates an instance of uCalc's powerful text transformation engine. Unlike standard regular expressions that operate on raw characters, a Transformer operates on tokens—the fundamental building blocks of a language (words, numbers, operators, etc.). This makes it inherently aware of structure, allowing it to safely and reliably parse complex, nested text that would be difficult or impossible to handle with Regex.

A new Transformer instance can be created in several ways, allowing you to control its context and lexical rules.

Constructor Overloads

1. var t = new Transformer();

Creates a new transformer using the default uCalc instance for its context and token set. This is the simplest way to create a transformer for general use.

2. var t = new Transformer(ucalcInstance);

Creates a new transformer within the context of a specific uCalc instance. This is the preferred method when working with multiple, isolated parsing environments.

3. var t = new Transformer(tokensToInherit);

Creates a new transformer that inherits a copy of the lexical rules from an existing Tokens collection. This is ideal for sharing a custom tokenizer configuration across multiple transformers.

💡 Why uCalc? (Transformer vs. Regex)

FeatureStandard RegexuCalc Transformer
AwarenessCharacter-based. Unaware of structure.Token-based. Understands numbers, strings, and operators as units.
Nested BracketsFails on nested structures like func(a, (b+c)).Handles nested brackets (), [], {} automatically by default.
ReadabilityDense, cryptic patterns (e.g., (?<=\s)\d+(?=\s))).Clean, declarative patterns (e.g., {@Number}).
SafetyCan accidentally match inside string literals or comments.Respects string and comment boundaries by default (QuoteSensitive).

🧰 The Transformer-String Equivalence

A Transformer and a uCalc.String are two different interfaces for the same underlying object. You can seamlessly convert between them. This allows you to build a string using the uCalc.String API and then immediately apply transformation rules to it by treating it as a Transformer.

🧠 Memory Management

A Transformer object holds significant resources and must be released when no longer needed to prevent memory leaks.

  • C# / VB.NET: Use the using statement for automatic release.
  • C++: For stack-allocated transformers, call Owned() to enable RAII-style automatic cleanup.

Examples

A simple find-and-replace transformation to replace all occurrences of a word.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Define a simple replacement rule
t.FromTo("Hello", "Greetings");

// Execute the transformation on an input string
t.Text = "Hello World, and Hello again.";
Console.WriteLine(t.Transform());
				
			
Greetings World, and Greetings again.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Define a simple replacement rule
   t.FromTo("Hello", "Greetings");

   // Execute the transformation on an input string
   t.Text("Hello World, and Hello again.");
   cout << t.Transform() << endl;
}
				
			
Greetings World, and Greetings again.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      '// Define a simple replacement rule
      t.FromTo("Hello", "Greetings")
      
      '// Execute the transformation on an input string
      t.Text = "Hello World, and Hello again."
      Console.WriteLine(t.Transform())
   End Sub
End Module
				
			
Greetings World, and Greetings again.
Transformer constructor
				
					using uCalcSoftware;

var uc = new uCalc();
Console.WriteLine("Transformer constructors");
var t1 = new uCalc.Transformer(); // New transformer in default uCalc space
var t2 = new uCalc.Transformer(uc); // New transformer inherits
var t3 = new uCalc.Transformer(t1.Tokens); // Imports tokens from t1
				
			
Transformer constructors
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   cout << "Transformer constructors" << endl;
   uCalc::Transformer t1; // New transformer in default uCalc space
   uCalc::Transformer t2(uc); // New transformer inherits
   uCalc::Transformer t3(t1.Tokens()); // Imports tokens from t1
}
				
			
Transformer constructors
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Console.WriteLine("Transformer constructors")
      Dim t1 As New uCalc.Transformer() '// New transformer in default uCalc space
      Dim t2 As New uCalc.Transformer(uc) '// New transformer inherits
      Dim t3 As New uCalc.Transformer(t1.Tokens) '// Imports tokens from t1
   End Sub
End Module
				
			
Transformer constructors
To_uCalcString
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "if (x > 3) y = x * 2; else if(x == 5) y = x - 1;";
t.FromTo("1", "100");
t.Transform();

var Pattern = "if ({cond})";
Console.WriteLine(new uCalc.String(t).After(Pattern).Text);
Console.WriteLine(new uCalc.String(t).After(Pattern).After(Pattern));

var s = new uCalc.String();
s = "This is a test";
Console.WriteLine(new uCalc.Transformer(s).Text);
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("if (x > 3) y = x * 2; else if(x == 5) y = x - 1;");
   t.FromTo("1", "100");
   t.Transform();

   auto Pattern = "if ({cond})";
   cout <<  uCalc::String(t).After(Pattern).Text() << endl;
   cout <<  uCalc::String(t).After(Pattern).After(Pattern) << endl;

   uCalc::String s;
   s = "This is a test";
   cout <<  uCalc::Transformer(s).Text() << endl;
}
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "if (x > 3) y = x * 2; else if(x == 5) y = x - 1;"
      t.FromTo("1", "100")
      t.Transform()
      
      Dim Pattern = "if ({cond})"
      Console.WriteLine(new uCalc.String(t).After(Pattern).Text)
      Console.WriteLine(new uCalc.String(t).After(Pattern).After(Pattern))
      
      Dim s As New uCalc.String()
      s = "This is a test"
      Console.WriteLine(new uCalc.Transformer(s).Text)
   End Sub
End Module
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
Previous
Next