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.

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.
				
					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.
A practical example sanitizing user input by removing script tags and normalizing excess whitespace in a single pass.
				
					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. '
				
					#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. '
				
					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. '
Implicit Str(), Transform()
				
					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
				
					#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
				
					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
ParentTransformer
				
					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
				
					#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
				
					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
SkipOver(), Str(), Implicit Str()
				
					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
				
					#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
				
					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
Previous
Next