Your First Transformation

Learn to perform your first token-aware find-and-replace operation using the uCalc Transformer.

Product: 

Class: 

Warning

uCalc API Preview Release Notice:The uCalc engine has successfully transitioned to modern cross-platform environments.The next phase envolves some structural changes, performance optimizations, and API refinements.The API is subject to breaking changes prior to the stable release. Please evaluate the preview version thoroughly before production use.

Remarks

🚀 Your First Transformation

Welcome to the uCalc Transformer! This is the engine's tool for structural, token-aware find-and-replace operations. It's more powerful and safer than a standard string Replace() function because it understands the structure of your text, distinguishing between code, numbers, and string literals.

This guide will walk you through the essential steps to perform your first transformation.

The 4-Step Process

Every transformation follows the same basic workflow:

  1. Create a Transformer: Get an instance of the transformer engine.
  2. Define Rules: Tell the transformer what to find and what to replace it with.
  3. Set the Text: Provide the source string to be transformed.
  4. Run the Transform: Execute the operation and get the result.

Let's break down each step.

Step 1: Create a Transformer

First, you need an instance of the Transformer. You can create one from your uCalc object.

using uCalcSoftware;

var uc = new uCalc();

using (var t = new uCalc.Transformer()) {;

Note: The using block ensures the transformer's resources are automatically released when it goes out of scope.

Step 2: Define a Rule with FromTo()

Next, you define the transformation logic using the FromTo() method. It takes two arguments: the pattern to find and the text to replace it with.

Our pattern will look for the word "Hello" followed by a variable named name.

using uCalcSoftware;

var uc = new uCalc();

// A rule to find "Hello {name}" and replace it with "Greetings, {name}!"
t.FromTo("Hello {name}", "Greetings, {name}!");

Here, {name} is a variable that captures the word immediately following "Hello". This captured value can be used in the replacement string.

Step 3: Set the Text

Now, provide the source string you want to modify. You can do this by assigning a string directly to the transformer object, which is a shortcut for setting its Text property.

using uCalcSoftware;

var uc = new uCalc();

t = "Hello World";

Step 4: Run the Transform and Get the Result

Finally, call the Transform() method to execute the rules. The result can be retrieved by using the transformer object where a string is expected.

using uCalcSoftware;

var uc = new uCalc();

Console.WriteLine(t.Transform());

Putting It All Together

Here is the complete code from all four steps:

using uCalcSoftware;

var uc = new uCalc();

using (var t = new uCalc.Transformer()) {
   t.FromTo("Hello {name}", "Greetings, {name}!");
   t = "Hello World";
   Console.WriteLine(t.Transform()); // Output: Greetings, World!
};

💡 Why uCalc? (Comparative Analysis)

You might ask, "Why not just use a standard string Replace() function?" The power of the Transformer lies in its token awareness. A standard replace is character-based and "blind" to structure. The Transformer breaks text into meaningful units (tokens) first, so it knows the difference between the number 10 and the string "10".

This prevents common bugs, like accidentally changing text inside a string literal when refactoring code. The next tutorial, [Capturing Text with Variables](TODO: Broken Link), will explore this concept in more detail.

Examples

A basic find-and-replace operation to change one word to another using a fluent, chainable syntax.

ID: 1195

See: Your First Transformation 
				
					using uCalcSoftware;

var uc = new uCalc();
using (var t = new uCalc.Transformer()) {
   
   // Define the rule and execute the transform in a single, chained statement.
   t.FromTo("Hello", "Greetings");
   Console.WriteLine(t.Transform("Hello World!"));

}
				
			
Greetings World!
Explore 600+ other examples
				
					#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 the rule and execute the transform in a single, chained statement.
      t.FromTo("Hello", "Greetings");
      cout << t.Transform("Hello World!") << endl;

   }
}
				
			
Greetings World!
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using t As New uCalc.Transformer()
         
         '// Define the rule and execute the transform in a single, chained statement.
         t.FromTo("Hello", "Greetings")
         Console.WriteLine(t.Transform("Hello World!"))
         
      End Using
   End Sub
End Module
				
			
Greetings World!
Explore 600+ other examples
Safely renames a variable without corrupting a string literal, demonstrating the Transformer's token-awareness.

ID: 1196

See: Your First Transformation 
				
					using uCalcSoftware;

var uc = new uCalc();
using (var t = new uCalc.Transformer()) {
   
   // This rule replaces the ALPHANUMERIC token 'x', not just the character 'x'.
   t.FromTo("x", "value");

   var code = """
if (x > 10) print("Max value is x");
""";

   // The 'x' inside the string is ignored because QuoteSensitive is true by default.
   Console.WriteLine(t.Transform(code));

}
				
			
if (value > 10) print("Max value is x");
Explore 600+ other examples
				
					#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

      // This rule replaces the ALPHANUMERIC token 'x', not just the character 'x'.
      t.FromTo("x", "value");

      auto code = R"(if (x > 10) print("Max value is x");)";

      // The 'x' inside the string is ignored because QuoteSensitive is true by default.
      cout << t.Transform(code) << endl;

   }
}
				
			
if (value > 10) print("Max value is x");
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using t As New uCalc.Transformer()
         
         '// This rule replaces the ALPHANUMERIC token 'x', not just the character 'x'.
         t.FromTo("x", "value")
         
         Dim code = "if (x > 10) print(""Max value is x"");"
         
         '// The 'x' inside the string is ignored because QuoteSensitive is true by default.
         Console.WriteLine(t.Transform(code))
         
      End Using
   End Sub
End Module
				
			
if (value > 10) print("Max value is x");
Explore 600+ other examples

This page last modified on: 

8/21/2026