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 = [string]

Property

Product: 

Transformer Library

Class: 

Rule

Gets or sets the replacement string of a rule, which defines the output text for a pattern match.

Remarks

🎯 The "To" in "From-To": Defining Replacement Logic

The Replacement property provides runtime access to the "source code" of a rule's replacement string—the part of the rule that defines the output. It allows you to programmatically inspect or even modify what a matched text segment will be transformed into.

This property applies to rules created with both FromTo() and Pattern().

⚙️ Getter and Setter Behavior

This property can be used to both read and write a rule's replacement logic:

  • Getter: myRule.Replacement retrieves the literal string that defines the rule's output.
  • Setter: myRule.Replacement = "new replacement text" modifies the rule at runtime. This change affects all subsequent Transform() operations.

✨ Implicit Behavior: Pattern() vs. FromTo()

Understanding the default replacement behavior is crucial:

  • For rules created with FromTo("pattern", "replacement"), this property returns the exact "replacement" string you provided.
  • For rules created with Pattern("pattern"), which have no explicit replacement, this property returns the special keyword {@Self}. This keyword instructs the transformer to re-insert the matched text without any changes, which is the default behavior for a find-only Pattern rule.

🧩 Components of a Replacement String

A replacement string is more than just literal text. It can contain dynamic components:

  • Literals: Plain text that is inserted as-is.
  • Variable Placeholders: {varName} inserts the text captured by a variable in the pattern.
  • Pattern Methods: Directives like {@Eval} or {@File} can execute logic, perform calculations, or load content during the replacement phase. For more details, see Pattern Methods.

💡 Why uCalc? (Comparative Analysis)

Traditional regex engines typically use a simple, string-based replacement model with numeric or named backreferences.

  • Standard Regex: A replacement might look like Hi, $2 $1 to reorder captured groups. This is functional but limited.
  • uCalc's Replacement: uCalc's model is far more powerful:
    • Readability: Uses descriptive names ({lastName}, {firstName}) instead of cryptic indices.
    • Embedded Logic: Natively supports conditional replacements ({var:text-if-found}) and can execute complex logic directly within the string using {@Eval: {var} * 1.1}, capabilities that would require a separate callback function in most other engines.
    • Runtime Modification: The ability to programmatically change a rule's replacement text at runtime provides a level of dynamism not available in statically compiled regex patterns.

Examples

Replacement()
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "aaa bbb xyz 123";
var aaa = t.FromTo("aaa", "111");
var xyz = t.Pattern("xyz");
t.Filter();
Console.WriteLine(t.Matches.Text);

Console.WriteLine("-----");
Console.WriteLine(aaa.Replacement);
Console.WriteLine(xyz.Replacement);

				
			
111
xyz
-----
111
{@Self}
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("aaa bbb xyz 123");
   auto aaa = t.FromTo("aaa", "111");
   auto xyz = t.Pattern("xyz");
   t.Filter();
   cout << t.Matches().Text() << endl;

   cout << "-----" << endl;
   cout << aaa.Replacement() << endl;
   cout << xyz.Replacement() << endl;

}
				
			
111
xyz
-----
111
{@Self}
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "aaa bbb xyz 123"
      Dim aaa = t.FromTo("aaa", "111")
      Dim xyz = t.Pattern("xyz")
      t.Filter()
      Console.WriteLine(t.Matches.Text)
      
      Console.WriteLine("-----")
      Console.WriteLine(aaa.Replacement)
      Console.WriteLine(xyz.Replacement)
      
   End Sub
End Module
				
			
111
xyz
-----
111
{@Self}
Previous
Next