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.

Text = [string]

Property

Product: 

Transformer Library

Class: 

Transformer

Gets or sets the primary source text string that the transformer will search or modify.

Remarks

📝 The Core Text Property

The Text property is the primary interface for managing the source string that a Transformer operates on. It functions as both a getter to retrieve the current (potentially transformed) text and a setter to assign a new source string.

This property is a fundamental part of the transformation workflow:

  1. Set: You assign the initial input string to the Text property.
  2. Process: You call methods like Find() or Transform() to process the text.
  3. Get: You retrieve the final, modified string from the Text property.

⚙️ Getter and Setter Behavior

  • Getter: Retrieves the current string content of the transformer.var currentText = myTransformer.Text;

  • Setter: Assigns a new source string, overwriting any previous content.myTransformer.Text = "new source text";

✨ Shortcut Notations (Implicit Conversions)

To enhance developer experience and reduce boilerplate, the Transformer object (along with uCalc.String) supports implicit conversions to and from the native string type. This makes the Text property feel like the default property of the object.

  • Implicit Setter: Assigning a string literal directly to a transformer variable is a shortcut for setting its Text property.

    • Verbose: t.Text = "Hello World";
    • Shortcut: t = "Hello World";

  • Implicit Getter: Using a transformer object in a context that expects a string (like assigning it to a string variable or passing it to wl()) is a shortcut for getting its Text property.

    • Verbose: var result = t.Text;
    • Shortcut: var result = t;

For a detailed explanation of this feature, see the Shortcut notations topic.

💡 Why uCalc? (Comparative Analysis)

In standard libraries, interacting with string-like objects often requires explicit method calls.

  • C# StringBuilder: You must call .ToString() to get the final string.
  • C++ std::stringstream: You must call .str() to retrieve the content.

While these are perfectly functional, uCalc's design choice to implement implicit conversions provides a more intuitive and seamless experience. The Transformer object can be treated almost like a native string, making the code more readable and less cluttered with ceremonial method calls. This focus on an ergonomic API design is a key differentiator, allowing developers to write more expressive code.

Examples

A basic example of setting the text, transforming it, and retrieving the result.
				
					using uCalcSoftware;

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

// 1. Set the initial text
t.Text = "The quick brown fox.";

// 2. Define a rule and transform
t.FromTo("brown", "red");
t.Transform();

// 3. Get the final text
Console.WriteLine(t.Text);
				
			
The quick red fox.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;

   // 1. Set the initial text
   t.Text("The quick brown fox.");

   // 2. Define a rule and transform
   t.FromTo("brown", "red");
   t.Transform();

   // 3. Get the final text
   cout << t.Text() << endl;
}
				
			
The quick red fox.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      
      '// 1. Set the initial text
      t.Text = "The quick brown fox."
      
      '// 2. Define a rule and transform
      t.FromTo("brown", "red")
      t.Transform()
      
      '// 3. Get the final text
      Console.WriteLine(t.Text)
   End Sub
End Module
				
			
The quick red fox.
Demonstrates using the Text property with implicit conversions (shortcuts) to parse a simple config string.
				
					using uCalcSoftware;

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

// Implicitly set the Text property by assigning a string to the object
t = "user=admin; level=9; theme=dark;";

// Define a rule to extract the user value
t.FromTo("user={name};", "Username: {name}");
t.Transform();

// Implicitly get the Text property by using the object in a string context
string result = t;
Console.WriteLine(result);
				
			
Username: admin level=9; theme=dark;
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;

   // Implicitly set the Text property by assigning a string to the object
   t = "user=admin; level=9; theme=dark;";

   // Define a rule to extract the user value
   t.FromTo("user={name};", "Username: {name}");
   t.Transform();

   // Implicitly get the Text property by using the object in a string context
   string result = t;
   cout << result << endl;
}
				
			
Username: admin level=9; theme=dark;
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      
      '// Implicitly set the Text property by assigning a string to the object
      t = "user=admin; level=9; theme=dark;"
      
      '// Define a rule to extract the user value
      t.FromTo("user={name};", "Username: {name}")
      t.Transform()
      
      '// Implicitly get the Text property by using the object in a string context
      Dim result As String = t
      Console.WriteLine(result)
   End Sub
End Module
				
			
Username: admin level=9; theme=dark;
Implicit Str(), Transform()
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.FromTo("a", "XY");

t.Text = "a b c a b c";
Console.WriteLine(t.Transform().Text); // Text that was set before trasnform
Console.WriteLine(t.Transform("c b a c b a").Text); // text passed to Transform()
Console.WriteLine(t.Transform("a, b, a, b")); // Implicit; Text property can be omitted
				
			
XY b c XY b c
c b XY c b XY
XY, b, XY, b
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.FromTo("a", "XY");

   t.Text("a b c a b c");
   cout << t.Transform().Text() << endl; // Text that was set before trasnform
   cout << t.Transform("c b a c b a").Text() << endl; // text passed to Transform()
   cout << t.Transform("a, b, a, b") << endl; // Implicit; Text property can be omitted
}
				
			
XY b c XY b c
c b XY c b XY
XY, b, XY, b
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.FromTo("a", "XY")
      
      t.Text = "a b c a b c"
      Console.WriteLine(t.Transform().Text) '// Text that was set before trasnform
      Console.WriteLine(t.Transform("c b a c b a").Text) '// text passed to Transform()
      Console.WriteLine(t.Transform("a, b, a, b")) '// Implicit; Text property can be omitted
   End Sub
End Module
				
			
XY b c XY b c
c b XY c b XY
XY, b, XY, b
Rule Name
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "<b>(5+4)</b> this and that etc";
var a = t.Pattern("<{tg}>");
var b = t.Pattern("This {body} That");
var c = t.Pattern("etc");
var d = t.Pattern("({expr})");

t.Filter();
Console.WriteLine("--- Matches ---");
Console.WriteLine(t.Matches.Text);
Console.WriteLine("--- Pattern names ---");
Console.WriteLine(a.Name);
Console.WriteLine(b.Name);
Console.WriteLine(c.Name);
Console.WriteLine(d.Name);
Console.WriteLine("--- Pattern defs ---");
Console.WriteLine(a.Pattern);
Console.WriteLine(b.Pattern);
Console.WriteLine(c.Pattern);
Console.WriteLine(d.Pattern);
				
			
--- Matches ---
<b>
(5+4)
</b>
this and that
etc
--- Pattern names ---
<
this
etc
(
--- Pattern defs ---
<{tg}>
This {body} That
etc
({expr})
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("<b>(5+4)</b> this and that etc");
   auto a = t.Pattern("<{tg}>");
   auto b = t.Pattern("This {body} That");
   auto c = t.Pattern("etc");
   auto d = t.Pattern("({expr})");

   t.Filter();
   cout << "--- Matches ---" << endl;
   cout << t.Matches().Text() << endl;
   cout << "--- Pattern names ---" << endl;
   cout << a.Name() << endl;
   cout << b.Name() << endl;
   cout << c.Name() << endl;
   cout << d.Name() << endl;
   cout << "--- Pattern defs ---" << endl;
   cout << a.Pattern() << endl;
   cout << b.Pattern() << endl;
   cout << c.Pattern() << endl;
   cout << d.Pattern() << endl;
}
				
			
--- Matches ---
<b>
(5+4)
</b>
this and that
etc
--- Pattern names ---
<
this
etc
(
--- Pattern defs ---
<{tg}>
This {body} That
etc
({expr})
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "<b>(5+4)</b> this and that etc"
      Dim a = t.Pattern("<{tg}>")
      Dim b = t.Pattern("This {body} That")
      Dim c = t.Pattern("etc")
      Dim d = t.Pattern("({expr})")
      
      t.Filter()
      Console.WriteLine("--- Matches ---")
      Console.WriteLine(t.Matches.Text)
      Console.WriteLine("--- Pattern names ---")
      Console.WriteLine(a.Name)
      Console.WriteLine(b.Name)
      Console.WriteLine(c.Name)
      Console.WriteLine(d.Name)
      Console.WriteLine("--- Pattern defs ---")
      Console.WriteLine(a.Pattern)
      Console.WriteLine(b.Pattern)
      Console.WriteLine(c.Pattern)
      Console.WriteLine(d.Pattern)
   End Sub
End Module
				
			
--- Matches ---
<b>
(5+4)
</b>
this and that
etc
--- Pattern names ---
<
this
etc
(
--- Pattern defs ---
<{tg}>
This {body} That
etc
({expr})
Previous
Next