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.

Your First Transformation

Product: 

Class: 

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

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 (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.

// 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.

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.

Console.WriteLine(t.Transform());

Putting It All Together

Here is the complete code from all four steps:

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.
				
					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!
				
					#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!
				
					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!
Safely renames a variable without corrupting a string literal, demonstrating the Transformer's token-awareness.
				
					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");
				
					#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");
				
					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");
Previous
Next