uCalc API Version: 5.7.0-preview.1 Released: 7/30/2026

Warning

uCalc API Preview Release Notice:This preview documentation describes the intended behavior of the API. It is not fully accurate or complete.The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.Use of the preview version in your production code is not recommended.

Transform()

Method

Product: 

Transformer Library

Class: 

Transformer

Applies all defined find-and-replace rules to the source text, modifying the transformer's internal text buffer.

Syntax

Transform()

Parameters

[None]

Return

Transformer

Returns the current Transformer object, allowing for a fluent, chainable interface.

Remarks

⚙️ Executing a Transformation

The Transform() method is the primary function for executing find-and-replace operations. It processes the text currently held by the Transformer against all active rules, updating the internal text buffer with the result.

Transformation Workflow

A typical operation follows these steps:

  1. Set Source Text: Load the input string into the transformer, usually via the Text property (e.g., t.Text("input string");).
  2. Define Rules: Add one or more rules using methods like FromTo(), Pattern(), and SkipOver().
  3. Execute Transform: Call Transform(). The engine scans the text, applies the rules, and modifies its internal buffer.
  4. Retrieve Result: Get the modified string, typically by reading the Text property (e.g., var result = t.Text();).

In-Place Modification & Fluent Interface

Transform() modifies the transformer's internal state. The method also returns the Transformer object itself, allowing for a fluent, chainable syntax:

Console.WriteLine(t.Transform().Text());

🆚 Comparative Analysis: Transform() vs. Find() vs. Filter()

It is crucial to choose the correct method for your task, as each serves a different purpose:

MethodPurposeResultUse Case
Find()LocatePopulates the Matches collection. Does not modify text.When you only need to know if and where patterns exist.
Filter()Extract & TransformCreates a new string consisting only of the transformed results of each match, separated by newlines.Extracting all log errors, URLs, or specific data points from a document into a clean list.
Transform() (This Method)Modify In-PlaceModifies the original text, replacing matches according to rules but preserving all other content.Performing a search-and-replace operation on a document.

💡 Why uCalc? Transform() vs. Regex

In many languages, Regex.Replace is the standard tool for find-and-replace. uCalc's Transform() offers significant advantages for structured text:

  • Token-Awareness: Regex is character-based and can easily fail on nested structures like func(a, (b+c)) or make incorrect replacements inside string literals. Transform() operates on tokens, so it inherently understands and respects these boundaries by default.
  • Stateful Engine: A Transformer is a stateful object. It maintains a set of rules with a clear precedence order (last-in, first-out) and configurable properties (e.g., CaseSensitive). A regex is typically a stateless pattern.
  • Embedded Logic: Transform() leverages rules that can contain embedded logic like {@Eval} or conditionals, capabilities that would require complex callback functions with standard regex.

Examples

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

ID: 1141

See: Introduction, Transform(), (Constructor) 
				
					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.
Explore 600+ other examples
				
					#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.
Explore 600+ other examples
				
					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.
Explore 600+ other examples
A practical example sanitizing user input by removing script tags and normalizing excess whitespace in a single pass.

ID: 1142

See: Transform() 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Rule 1: Remove script tags and their content (case-insensitive, multi-line)
t.FromTo("<script>{content}</script>", "");
t.DefaultRuleSet.SetCaseSensitive(false).SetStatementSensitive(false);

// Rule 2: Normalize one or more whitespace characters to a single space
t.FromTo("{@Whitespace:ws}", " ");

// Transform the input in one go and print the result
t.Text = "  Welcome!  <SCRIPT>alert('bad');</SCRIPT>Please enjoy.  ";
Console.WriteLine($"Sanitized: '{t.Transform()}'");
				
			
Sanitized: ' Welcome! Please enjoy. '
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Rule 1: Remove script tags and their content (case-insensitive, multi-line)
   t.FromTo("<script>{content}</script>", "");
   t.DefaultRuleSet().SetCaseSensitive(false).SetStatementSensitive(false);

   // Rule 2: Normalize one or more whitespace characters to a single space
   t.FromTo("{@Whitespace:ws}", " ");

   // Transform the input in one go and print the result
   t.Text("  Welcome!  <SCRIPT>alert('bad');</SCRIPT>Please enjoy.  ");
   cout << "Sanitized: '" << t.Transform() << "'" << endl;
}
				
			
Sanitized: ' Welcome! Please enjoy. '
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      '// Rule 1: Remove script tags and their content (case-insensitive, multi-line)
      t.FromTo("<script>{content}</script>", "")
      t.DefaultRuleSet.SetCaseSensitive(false).SetStatementSensitive(false)
      
      '// Rule 2: Normalize one or more whitespace characters to a single space
      t.FromTo("{@Whitespace:ws}", " ")
      
      '// Transform the input in one go and print the result
      t.Text = "  Welcome!  <SCRIPT>alert('bad');</SCRIPT>Please enjoy.  "
      Console.WriteLine($"Sanitized: '{t.Transform()}'")
   End Sub
End Module
				
			
Sanitized: ' Welcome! Please enjoy. '
Explore 600+ other examples
Implicit Str(), Transform()

ID: 156

See: Str(), Str(string), Text = [string], Transform(), Transform(string) 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.FromTo("a", "XY");

t.Text = "a b c a b c";
Console.WriteLine(t.Transform().Text); // Text that was set before trasnform
Console.WriteLine(t.Transform("c b a c b a").Text); // text passed to Transform()
Console.WriteLine(t.Transform("a, b, a, b")); // Implicit; Text property can be omitted
				
			
XY b c XY b c
c b XY c b XY
XY, b, XY, b
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.FromTo("a", "XY");

   t.Text("a b c a b c");
   cout << t.Transform().Text() << endl; // Text that was set before trasnform
   cout << t.Transform("c b a c b a").Text() << endl; // text passed to Transform()
   cout << t.Transform("a, b, a, b") << endl; // Implicit; Text property can be omitted
}
				
			
XY b c XY b c
c b XY c b XY
XY, b, XY, b
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.FromTo("a", "XY")
      
      t.Text = "a b c a b c"
      Console.WriteLine(t.Transform().Text) '// Text that was set before trasnform
      Console.WriteLine(t.Transform("c b a c b a").Text) '// text passed to Transform()
      Console.WriteLine(t.Transform("a, b, a, b")) '// Implicit; Text property can be omitted
   End Sub
End Module
				
			
XY b c XY b c
c b XY c b XY
XY, b, XY, b
Explore 600+ other examples
ParentTransformer

ID: 132

See: Description = [string], Description(string), ParentTransformer = [Transformer], Str(), Str(string), Transform(), Transform(string) 
				
					using uCalcSoftware;

var uc = new uCalc();
var Txt = "Test a b c. x y z";

var FirstTransform = uc.NewTransformer().SetText(Txt).SetDescription("First Transformer");
var aaa = FirstTransform.FromTo("Test {etc}.", "[{etc}]");

var SecondTransform = uc.NewTransformer().SetDescription("Second Transformer");
var bbb = SecondTransform.FromTo("Test {etc}.", "({etc})");

Console.WriteLine(aaa.ParentTransformer.Description);
Console.WriteLine(FirstTransform.Transform().Text);
Console.WriteLine("");

Console.WriteLine(SecondTransform.Description);
Console.WriteLine(bbb.ParentTransformer.Transform(Txt).Text);
				
			
First Transformer
[a b c] x y z

Second Transformer
(a b c) x y z
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto Txt = "Test a b c. x y z";

   auto FirstTransform = uc.NewTransformer().SetText(Txt).SetDescription("First Transformer");
   auto aaa = FirstTransform.FromTo("Test {etc}.", "[{etc}]");

   auto SecondTransform = uc.NewTransformer().SetDescription("Second Transformer");
   auto bbb = SecondTransform.FromTo("Test {etc}.", "({etc})");

   cout << aaa.ParentTransformer().Description() << endl;
   cout << FirstTransform.Transform().Text() << endl;
   cout << "" << endl;

   cout << SecondTransform.Description() << endl;
   cout << bbb.ParentTransformer().Transform(Txt).Text() << endl;
}
				
			
First Transformer
[a b c] x y z

Second Transformer
(a b c) x y z
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim Txt = "Test a b c. x y z"
      
      Dim FirstTransform = uc.NewTransformer().SetText(Txt).SetDescription("First Transformer")
      Dim aaa = FirstTransform.FromTo("Test {etc}.", "[{etc}]")
      
      Dim SecondTransform = uc.NewTransformer().SetDescription("Second Transformer")
      Dim bbb = SecondTransform.FromTo("Test {etc}.", "({etc})")
      
      Console.WriteLine(aaa.ParentTransformer.Description)
      Console.WriteLine(FirstTransform.Transform().Text)
      Console.WriteLine("")
      
      Console.WriteLine(SecondTransform.Description)
      Console.WriteLine(bbb.ParentTransformer.Transform(Txt).Text)
   End Sub
End Module
				
			
First Transformer
[a b c] x y z

Second Transformer
(a b c) x y z
Explore 600+ other examples
SkipOver(), Str(), Implicit Str()

ID: 137

See: SkipOver, Transform(), Transform(string) 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var txt = "a b c (a b c a b c) a b c";
t.FromTo("a", "AA");

// You can either set the string before or pass it to Transform()
t.Str(txt);
Console.WriteLine(t.Transform().Text);

t.SkipOver("({text})");
Console.WriteLine(t.Transform(txt)); // Implicit Text property
				
			
AA b c (AA b c AA b c) AA b c
AA b c (a b c a b c) AA b c
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto txt = "a b c (a b c a b c) a b c";
   t.FromTo("a", "AA");

   // You can either set the string before or pass it to Transform()
   t.Str(txt);
   cout << t.Transform().Text() << endl;

   t.SkipOver("({text})");
   cout << t.Transform(txt) << endl; // Implicit Text property
}
				
			
AA b c (AA b c AA b c) AA b c
AA b c (a b c a b c) AA b c
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim txt = "a b c (a b c a b c) a b c"
      t.FromTo("a", "AA")
      
      '// You can either set the string before or pass it to Transform()
      t.Str(txt)
      Console.WriteLine(t.Transform().Text)
      
      t.SkipOver("({text})")
      Console.WriteLine(t.Transform(txt)) '// Implicit Text property
   End Sub
End Module
				
			
AA b c (AA b c AA b c) AA b c
AA b c (a b c a b c) AA b c
Explore 600+ other examples