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.

Replacement

Product: 

Class: 

Remarks

In a FromTo(pattern, replacement) rule, the Replacement string defines how the matched text should be reconstructed.

Key Components:

  • Literals: Text that is inserted exactly as written.
  • Variables: {name} acts as a placeholder if and only if {name} was defined as a capturing variable in the Pattern.
  • Evaluations: {@Eval: expression} executes logic during replacement (e.g., {@Eval: 2 + 2} inserts 4).

Conditional Replacements (Optional Blocks):When a variable corresponds to an optional part of the pattern (e.g., Start [{opt}] End), you can control the output based on whether a match occurred.

  • Standard {opt}: Inserts the captured text if found, or an empty string if not found.
  • Conditional {opt: ...}: Inserts the entire block of text following the colon only if the variable captured content.
    • Syntax: {varName: text to display}
    • Behavior: If varName captured text, the block is displayed (and can include the variable itself). If varName is empty/missing, the entire block is suppressed.

Implicit Behavior:

  • Verbatim Braces: You do not need to escape curly braces in the replacement string. If {Hello} appears in the replacement but {Hello} was not defined as a variable in the pattern, it is treated as literal text.

Comparative Analysis: Why uCalc?

  • vs. Regex:
    • Conditionals: Standard Regex replacements cannot easily say "Insert 'Label: ' only if Group 1 matched." You typically need complex code callbacks. uCalc handles this natively with {var: Label: {var}}.
    • Readability: uCalc uses named variables ({name}) instead of numeric backreferences ($1), making complex rearrangements intuitive.
    • Logic: {@Eval} allows mathematical transformation directly in the replacement string.

Examples

Searching for two different words in parallel.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

// Define concurrent patterns
t.FromTo("Mango", "[Fruit]");
t.FromTo("Car", "[Vehicle]");

Console.WriteLine(t.Transform("I have a Mango and a Car."));

				
			
I have a [Fruit] and a [Vehicle].
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   // Define concurrent patterns
   t.FromTo("Mango", "[Fruit]");
   t.FromTo("Car", "[Vehicle]");

   cout << t.Transform("I have a Mango and a Car.") << endl;

}
				
			
I have a [Fruit] and a [Vehicle].
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// Define concurrent patterns
      t.FromTo("Mango", "[Fruit]")
      t.FromTo("Car", "[Vehicle]")
      
      Console.WriteLine(t.Transform("I have a Mango and a Car."))
      
   End Sub
End Module
				
			
I have a [Fruit] and a [Vehicle].
More on variables and anchors
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

// Variables are {etc} and {ch}
// Anchors are "This", either "a small" or "an easy", and "Test"

t.FromTo("This {etc} {ch: a small | an easy } Test", "<{etc}> ({ch}) experiment");
Console.WriteLine(t.Transform("This is such an easy test."));
				
			
<is such> (an easy) experiment.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   // Variables are {etc} and {ch}
   // Anchors are "This", either "a small" or "an easy", and "Test"

   t.FromTo("This {etc} {ch: a small | an easy } Test", "<{etc}> ({ch}) experiment");
   cout << t.Transform("This is such an easy test.") << endl;
}
				
			
<is such> (an easy) experiment.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// Variables are {etc} and {ch}
      '// Anchors are "This", either "a small" or "an easy", and "Test"
      
      t.FromTo("This {etc} {ch: a small | an easy } Test", "<{etc}> ({ch}) experiment")
      Console.WriteLine(t.Transform("This is such an easy test."))
   End Sub
End Module
				
			
<is such> (an easy) experiment.
Named optional part
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

t.FromTo("a [{option: small | big }] test",
"a sample test{option: categorized as '{option}'}");

Console.WriteLine(t.Transform("This is a test."));
Console.WriteLine(t.Transform("This is a big test."));
Console.WriteLine(t.Transform("This is a small test."));
Console.WriteLine(t.Transform("This is a random test."));
				
			
This is a sample test.
This is a sample test categorized as 'big'.
This is a sample test categorized as 'small'.
This is a random test.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   t.FromTo("a [{option: small | big }] test",
   "a sample test{option: categorized as '{option}'}");

   cout << t.Transform("This is a test.") << endl;
   cout << t.Transform("This is a big test.") << endl;
   cout << t.Transform("This is a small test.") << endl;
   cout << t.Transform("This is a random test.") << endl;
}
				
			
This is a sample test.
This is a sample test categorized as 'big'.
This is a sample test categorized as 'small'.
This is a random test.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("a [{option: small | big }] test",
      "a sample test{option: categorized as '{option}'}")
      
      Console.WriteLine(t.Transform("This is a test."))
      Console.WriteLine(t.Transform("This is a big test."))
      Console.WriteLine(t.Transform("This is a small test."))
      Console.WriteLine(t.Transform("This is a random test."))
   End Sub
End Module
				
			
This is a sample test.
This is a sample test categorized as 'big'.
This is a sample test categorized as 'small'.
This is a random test.
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
Using the same pattern variable multiple times in a pattern
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

// When a variable is used multiple times in a pattern,
// such as {tag} in this case, the matching text must be the same

t.FromTo("<{tag}> {words:2} {more} </{tag}>",
"tag={tag}, 2 words={words}, text={more}");

Console.WriteLine(t.Transform("<div>abc xyz more words<b>bold</b></div>").Text);
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   // When a variable is used multiple times in a pattern,
   // such as {tag} in this case, the matching text must be the same

   t.FromTo("<{tag}> {words:2} {more} </{tag}>",
   "tag={tag}, 2 words={words}, text={more}");

   cout << t.Transform("<div>abc xyz more words<b>bold</b></div>").Text() << endl;
}
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// When a variable is used multiple times in a pattern,
      '// such as {tag} in this case, the matching text must be the same
      
      t.FromTo("<{tag}> {words:2} {more} </{tag}>",
      "tag={tag}, 2 words={words}, text={more}")
      
      Console.WriteLine(t.Transform("<div>abc xyz more words<b>bold</b></div>").Text)
   End Sub
End Module
				
			
tag=div, 2 words=abc xyz, text=more words<b>bold</b>
Using **Conditional Blocks** to format an optional title.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
// Pattern: Name followed optionally by a Title in parens.
t.FromTo("Name: {n} [({title})]",
"User: {n} {title:[Title: {title}]}");

// Case 1: Title exists
Console.WriteLine(t.Transform("Name: Alice (Manager)"));

// Case 2: Title missing
Console.WriteLine(t.Transform("Name: Bob"));
// (The entire "[Title: ...]" block is omitted)
				
			
User: Alice [Title: Manager]
User: Bob
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   // Pattern: Name followed optionally by a Title in parens.
   t.FromTo("Name: {n} [({title})]",
   "User: {n} {title:[Title: {title}]}");

   // Case 1: Title exists
   cout << t.Transform("Name: Alice (Manager)") << endl;

   // Case 2: Title missing
   cout << t.Transform("Name: Bob") << endl;
   // (The entire "[Title: ...]" block is omitted)
}
				
			
User: Alice [Title: Manager]
User: Bob
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      '// Pattern: Name followed optionally by a Title in parens.
      t.FromTo("Name: {n} [({title})]",
      "User: {n} {title:[Title: {title}]}")
      
      '// Case 1: Title exists
      Console.WriteLine(t.Transform("Name: Alice (Manager)"))
      
      '// Case 2: Title missing
      Console.WriteLine(t.Transform("Name: Bob"))
      '// (The entire "[Title: ...]" block is omitted)
   End Sub
End Module
				
			
User: Alice [Title: Manager]
User: Bob
Previous
Next