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.

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.

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

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 TextNow, 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](/Reference/uCalcBase/Transformer/Text) property.```csharp
t = "Hello World";
```### Step 4: Run the Transform and Get the ResultFinally, call the [Transform()](/Reference/uCalcBase/Transformer/Transform) method to execute the rules. The result can be retrieved by using the transformer object where a string is expected.```csharp
Console.WriteLine(t.Transform());
```### Putting It All TogetherHere is the complete code from all four steps:```csharp
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](/Reference/uCalcBase/Transformer/Constructor) lies in its **token awareness**. A standard replace is character-based and "blind" to structure. The [Transformer](/Reference/uCalcBase/Transformer/Constructor) 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