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(string)

Method

Product: 

Transformer Library

Class: 

Transformer

Sets the source text and runs a find-and-replace operation in a single step, modifying the text according to the transformer's defined rules.

Syntax

Transform(string)

Parameters

inputText
string
The source text string to be transformed.

Return

Transformer

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

Remarks

The Transform(string) method is a convenience overload that combines two operations into one: it first sets the transformer's internal source text to the provided string and then immediately executes the transformation process.

This is functionally equivalent to calling .Text = inputText followed by the parameterless .Transform() method.

⚙️ The Transformation Process

When called, the method executes the full transformation pipeline:

  1. The inputText overwrites any text currently held by the transformer.
  2. The engine scans the text, finding all segments that match the defined rules (FromTo(), Pattern()).
  3. Rule precedence is respected: SkipOver() rules are evaluated first, followed by other rules in LIFO (Last-In, First-Out) order.
  4. Matched segments are replaced according to their replacement strings.
  5. The transformer's internal text is updated with the result, which can then be retrieved using the .Text property.

Transform(string) vs. Transform()

MethodBehaviorUse Case
Transform(string)Sets the text and transforms it.Ideal for stateless, one-off transformations where the Transformer object is primarily a container for rules.
Transform()Transforms the text already present in the object.Useful for multi-stage processing where you perform several distinct operations on the same text buffer.

Transform vs. Find vs. Filter

MethodEffect on TextPrimary Purpose
Transform()Modifies in-place. Replaces matches while preserving all other content.Performing a search-and-replace on a document.
Find()None. The text is not modified.Locating patterns and populating the Matches collection for analysis.
Filter()Extracts. Creates a new string consisting only of the transformed results.Extracting all log errors, URLs, or specific data points into a clean list.

Fluent Interface

This method returns the current Transformer instance, allowing for a fluent, chainable syntax:

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

Examples

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

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

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

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::Transformer t;
      t.Owned(); // Causes t to be released when it goes out of scope
      // Define a simple replacement rule
      t.FromTo("Hello", "Greetings");

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

   string userInput = "  Welcome!  <SCRIPT>alert('bad');</SCRIPT>Please enjoy.  ";

   // Transform the input in one go and print the result
   Console.WriteLine($"Sanitized: '{t.Transform(userInput)}'");
}
				
			
Sanitized: ' Welcome! Please enjoy. '
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::Transformer t;
      t.Owned(); // Causes t to be released when it goes out of scope
      // 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}", " ");

      string userInput = "  Welcome!  <SCRIPT>alert('bad');</SCRIPT>Please enjoy.  ";

      // Transform the input in one go and print the result
      cout << "Sanitized: '" << t.Transform(userInput) << "'" << endl;
   }
}
				
			
Sanitized: ' Welcome! Please enjoy. '
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using 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}", " ")
         
         Dim userInput As String = "  Welcome!  <SCRIPT>alert('bad');</SCRIPT>Please enjoy.  "
         
         '// Transform the input in one go and print the result
         Console.WriteLine($"Sanitized: '{t.Transform(userInput)}'")
      End Using
   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
RewindOnChange
				
					using uCalcSoftware;

var uc = new uCalc();
var ExprT = uc.ExpressionTransformer;  // Transformer used for Eval() and Evaluate()

ExprT.DefaultRuleSet.RewindOnChange = true;

ExprT.FromTo("AddUp({x})", "{x}");
ExprT.FromTo("AddUp({x}, {y})", "({x} + AddUp({y}))");

ExprT.FromTo("ArgCount({x})", "1");
ExprT.FromTo("ArgCount({x}, {y})", "(1 + ArgCount({y}))");

ExprT.FromTo("Average({x}, {y})", "AddUp({x}, {y}) / ArgCount({x}, {y})");

var Expression = "Average(1, 2, 3, 4)";
Console.WriteLine($"Input: {Expression}");
Console.WriteLine($"Transform: {ExprT.Transform(Expression)}");
Console.WriteLine($"Eval: {uc.Eval(Expression)}");
				
			
Input: Average(1, 2, 3, 4)
Transform: (1 + (2 + (3 + 4))) / (1 + (1 + (1 + 1)))
Eval: 2.5
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto ExprT = uc.ExpressionTransformer();  // Transformer used for Eval() and Evaluate()

   ExprT.DefaultRuleSet().RewindOnChange(true);

   ExprT.FromTo("AddUp({x})", "{x}");
   ExprT.FromTo("AddUp({x}, {y})", "({x} + AddUp({y}))");

   ExprT.FromTo("ArgCount({x})", "1");
   ExprT.FromTo("ArgCount({x}, {y})", "(1 + ArgCount({y}))");

   ExprT.FromTo("Average({x}, {y})", "AddUp({x}, {y}) / ArgCount({x}, {y})");

   auto Expression = "Average(1, 2, 3, 4)";
   cout << "Input: " << Expression << endl;
   cout << "Transform: " << ExprT.Transform(Expression) << endl;
   cout << "Eval: " << uc.Eval(Expression) << endl;
}
				
			
Input: Average(1, 2, 3, 4)
Transform: (1 + (2 + (3 + 4))) / (1 + (1 + (1 + 1)))
Eval: 2.5
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim ExprT = uc.ExpressionTransformer  '// Transformer used for Eval() and Evaluate()
      
      ExprT.DefaultRuleSet.RewindOnChange = true
      
      ExprT.FromTo("AddUp({x})", "{x}")
      ExprT.FromTo("AddUp({x}, {y})", "({x} + AddUp({y}))")
      
      ExprT.FromTo("ArgCount({x})", "1")
      ExprT.FromTo("ArgCount({x}, {y})", "(1 + ArgCount({y}))")
      
      ExprT.FromTo("Average({x}, {y})", "AddUp({x}, {y}) / ArgCount({x}, {y})")
      
      Dim Expression = "Average(1, 2, 3, 4)"
      Console.WriteLine($"Input: {Expression}")
      Console.WriteLine($"Transform: {ExprT.Transform(Expression)}")
      Console.WriteLine($"Eval: {uc.Eval(Expression)}")
   End Sub
End Module
				
			
Input: Average(1, 2, 3, 4)
Transform: (1 + (2 + (3 + 4))) / (1 + (1 + (1 + 1)))
Eval: 2.5
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
Transformer.uCalc
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.uCalc.DefineVariable("xyz = 123");

t.FromTo("xyz", "{@Eval: xyz * 10}");
Console.WriteLine(t.Transform("The answer is: xyz"));
				
			
The answer is: 1230
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.uCalc().DefineVariable("xyz = 123");

   t.FromTo("xyz", "{@Eval: xyz * 10}");
   cout << t.Transform("The answer is: xyz") << endl;
}
				
			
The answer is: 1230
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.uCalc.DefineVariable("xyz = 123")
      
      t.FromTo("xyz", "{@Eval: xyz * 10}")
      Console.WriteLine(t.Transform("The answer is: xyz"))
   End Sub
End Module
				
			
The answer is: 1230
Previous
Next