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.

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

ID: 134

See: Replacement = [string] 
				
					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}
Explore 600+ other examples
				
					#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}
Explore 600+ other examples
				
					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}
Explore 600+ other examples