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: 

Match

Retrieves the read-only string of characters captured by an individual match result.

Remarks

The Text property returns the exact string of text that was captured by the pattern rule that generated this specific match.

🎯 Primary Use Case

This property is the main way to access the content of an individual result from a Matches collection. It is a read-only property; a match's text is a snapshot of the source string from a find operation and cannot be modified directly.

⚡️ Match.Text vs. Matches.Text

It is crucial to distinguish between the property on a single Match object and the property on the parent Matches collection:

  • Match.Text (This Property): Returns the text for one specific match. This is what you get when you index into a Matches collection (e.g., myMatches[0].Text).
  • Matches.Text: Returns a single string containing all matches concatenated together, typically separated by newlines.

⚙️ Behavior After a Transform() Operation

A Match object is a read-only snapshot of the original source string. Therefore, Text will always contain the text segment that was found before any replacement occurred. To see the new, modified string, you must inspect the Transformer's final output (e.g., myTransformer.Text()). The internal test example demonstrates this behavior clearly.

📝 Design Note & Future Direction

Based on user feedback, a new property such as NewText or ReplacementText is under consideration. This would return the text that replaced the original Match.Text after a Transform() operation. Logically, this would also require corresponding NewStartPosition, NewEndPosition, and NewLength properties to describe the replacement's location and size within the newly transformed string. This is a complex feature involving coordinate mapping and is not yet implemented.

⚖️ Comparative Analysis

This property is analogous to Match.Value in .NET's System.Text.RegularExpressions or the result of a captured group in other regex engines.

However, a uCalc Match object provides richer context than a standard regex match. While Text gives you the captured string, the Match object itself also gives you access to:

  • The specific Rule that generated the match.
  • The match's StartPosition and Length.
  • Nested or child matches if they exist.

This makes Match.Text a component of a much more powerful and introspective result set than what is typically available from character-based regex libraries.

Examples

Retrieving the text of the first match found in a simple search.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "The price is $19.99 today.";
t.Pattern("{@Number}"); // Find the first number
t.Find();

// Get the collection of matches
var matches = t.Matches;

// Check if any match was found and get its text
if (matches.Count() > 0) {
   Console.WriteLine(matches[0].Text);
}
				
			
19.99
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("The price is $19.99 today.");
   t.Pattern("{@Number}"); // Find the first number
   t.Find();

   // Get the collection of matches
   auto matches = t.Matches();

   // Check if any match was found and get its text
   if (matches.Count() > 0) {
      cout << matches[0].Text() << endl;
   }
}
				
			
19.99
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "The price is $19.99 today."
      t.Pattern("{@Number}") '// Find the first number
      t.Find()
      
      '// Get the collection of matches
      Dim matches = t.Matches
      
      '// Check if any match was found and get its text
      If matches.Count() > 0 Then
         Console.WriteLine(matches(0).Text)
      End If
   End Sub
End Module
				
			
19.99
Iterating through multiple HTML tag matches and printing the text of each one.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "<p>First paragraph.</p> <div>Content</div>";

// Pattern to find any simple HTML-like tag
t.Pattern("<{tag}>{content}</{tag}>");
t.Find();

var matches = t.Matches;
Console.WriteLine($"Found {matches.Count()} tags:");
foreach(var match in t.Matches) {
   Console.WriteLine($"- {match.Text}");
}
				
			
Found 2 tags:
- <p>First paragraph.</p>
- <div>Content</div>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("<p>First paragraph.</p> <div>Content</div>");

   // Pattern to find any simple HTML-like tag
   t.Pattern("<{tag}>{content}</{tag}>");
   t.Find();

   auto matches = t.Matches();
   cout << "Found " << matches.Count() << " tags:" << endl;
   for(auto match : t.Matches()) {
      cout << "- " << match.Text() << endl;
   }
}
				
			
Found 2 tags:
- <p>First paragraph.</p>
- <div>Content</div>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "<p>First paragraph.</p> <div>Content</div>"
      
      '// Pattern to find any simple HTML-like tag
      t.Pattern("<{tag}>{content}</{tag}>")
      t.Find()
      
      Dim matches = t.Matches
      Console.WriteLine($"Found {matches.Count()} tags:")
      For Each match In t.Matches
         Console.WriteLine($"- {match.Text}")
      Next
   End Sub
End Module
				
			
Found 2 tags:
- <p>First paragraph.</p>
- <div>Content</div>
A succinct example demonstrating how to get the text of the first match found.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "The quick brown fox";
t.Pattern("brown");
t.Find();

// Get the collection of matches
var matches = t.Matches;

// Check if any matches were found
// Get the first match object and retrieve its text
var firstMatch = matches[0];
Console.WriteLine($"Found match: '{firstMatch.Text}'");

				
			
Found match: 'brown'
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("The quick brown fox");
   t.Pattern("brown");
   t.Find();

   // Get the collection of matches
   auto matches = t.Matches();

   // Check if any matches were found
   // Get the first match object and retrieve its text
   auto firstMatch = matches[0];
   cout << "Found match: '" << firstMatch.Text() << "'" << endl;

}
				
			
Found match: 'brown'
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "The quick brown fox"
      t.Pattern("brown")
      t.Find()
      
      '// Get the collection of matches
      Dim matches = t.Matches
      
      '// Check if any matches were found
      '// Get the first match object and retrieve its text
      Dim firstMatch = matches(0)
      Console.WriteLine($"Found match: '{firstMatch.Text}'")
      
   End Sub
End Module
				
			
Found match: 'brown'
A practical example that finds all HTML-style tags and prints the text of each one.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "<h1>Title</h1><p>Text</p>";

// Pattern to find any tag and its content
t.Pattern("<{tag}>{content}</{tag}>");
t.Find();

var allMatches = t.Matches;
Console.WriteLine($"Found {allMatches.Count()} matches:");

// Loop through each Match object and print its Text
foreach(var match in allMatches) {
   Console.WriteLine($" - {match.Text}");
}
				
			
Found 2 matches:
 - <h1>Title</h1>
 - <p>Text</p>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("<h1>Title</h1><p>Text</p>");

   // Pattern to find any tag and its content
   t.Pattern("<{tag}>{content}</{tag}>");
   t.Find();

   auto allMatches = t.Matches();
   cout << "Found " << allMatches.Count() << " matches:" << endl;

   // Loop through each Match object and print its Text
   for(auto match : allMatches) {
      cout << " - " << match.Text() << endl;
   }
}
				
			
Found 2 matches:
 - <h1>Title</h1>
 - <p>Text</p>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "<h1>Title</h1><p>Text</p>"
      
      '// Pattern to find any tag and its content
      t.Pattern("<{tag}>{content}</{tag}>")
      t.Find()
      
      Dim allMatches = t.Matches
      Console.WriteLine($"Found {allMatches.Count()} matches:")
      
      '// Loop through each Match object and print its Text
      For Each match In allMatches
         Console.WriteLine($" - {match.Text}")
      Next
   End Sub
End Module
				
			
Found 2 matches:
 - <h1>Title</h1>
 - <p>Text</p>
Returns Start and End positions of Transformer matches
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "<br><h1>First</h1>Blah Blah<br>Testing<br><h2>Second</h2>";
//         ^             ^                       ^              ^
//     012345678901234567890123456789012345678901234567890123456789
//     0         10        20        30        40        50
// Carrets (^) point to Start and End locations of the matches

Console.WriteLine(t.Text);
Console.WriteLine("");

t.Pattern("<{tag}>{etc}</{tag}>");
t.Find();
var Matches = t.Matches;

Console.WriteLine(Matches[0].Text);
Console.WriteLine($"Start pos: {Matches[0].StartPosition}");
Console.WriteLine($"End pos: {Matches[0].EndPosition}");
Console.WriteLine($"Length: {Matches[0].Length}");
Console.WriteLine("");

Console.WriteLine(Matches[1].Text);
Console.WriteLine($"Start pos: {Matches[1].StartPosition}");
Console.WriteLine($"End pos: {Matches[1].EndPosition}");
Console.WriteLine($"Length: {Matches[1].Length}");
				
			
<br><h1>First</h1>Blah Blah<br>Testing<br><h2>Second</h2>

<h1>First</h1>
Start pos: 4
End pos: 18
Length: 14

<h2>Second</h2>
Start pos: 42
End pos: 57
Length: 15
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("<br><h1>First</h1>Blah Blah<br>Testing<br><h2>Second</h2>");
   //         ^             ^                       ^              ^
   //     012345678901234567890123456789012345678901234567890123456789
   //     0         10        20        30        40        50
   // Carrets (^) point to Start and End locations of the matches

   cout << t.Text() << endl;
   cout << "" << endl;

   t.Pattern("<{tag}>{etc}</{tag}>");
   t.Find();
   auto Matches = t.Matches();

   cout << Matches[0].Text() << endl;
   cout << "Start pos: " << Matches[0].StartPosition() << endl;
   cout << "End pos: " << Matches[0].EndPosition() << endl;
   cout << "Length: " << Matches[0].Length() << endl;
   cout << "" << endl;

   cout << Matches[1].Text() << endl;
   cout << "Start pos: " << Matches[1].StartPosition() << endl;
   cout << "End pos: " << Matches[1].EndPosition() << endl;
   cout << "Length: " << Matches[1].Length() << endl;
}
				
			
<br><h1>First</h1>Blah Blah<br>Testing<br><h2>Second</h2>

<h1>First</h1>
Start pos: 4
End pos: 18
Length: 14

<h2>Second</h2>
Start pos: 42
End pos: 57
Length: 15
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "<br><h1>First</h1>Blah Blah<br>Testing<br><h2>Second</h2>"
      '//         ^             ^                       ^              ^
      '//     012345678901234567890123456789012345678901234567890123456789
      '//     0         10        20        30        40        50
      '// Carrets (^) point to Start and End locations of the matches
      
      Console.WriteLine(t.Text)
      Console.WriteLine("")
      
      t.Pattern("<{tag}>{etc}</{tag}>")
      t.Find()
      Dim Matches = t.Matches
      
      Console.WriteLine(Matches(0).Text)
      Console.WriteLine($"Start pos: {Matches(0).StartPosition}")
      Console.WriteLine($"End pos: {Matches(0).EndPosition}")
      Console.WriteLine($"Length: {Matches(0).Length}")
      Console.WriteLine("")
      
      Console.WriteLine(Matches(1).Text)
      Console.WriteLine($"Start pos: {Matches(1).StartPosition}")
      Console.WriteLine($"End pos: {Matches(1).EndPosition}")
      Console.WriteLine($"Length: {Matches(1).Length}")
   End Sub
End Module
				
			
<br><h1>First</h1>Blah Blah<br>Testing<br><h2>Second</h2>

<h1>First</h1>
Start pos: 4
End pos: 18
Length: 14

<h2>Second</h2>
Start pos: 42
End pos: 57
Length: 15
Matches
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "<h3>Title</h3><b>Bold statement</b><!--<h3>Title B</h3>--><b>Other text</b><p>My paragraph</p>";
//     0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456
//     0         10        20        30        40        50        60        70        80        90
//     ^             ^                                           ^                ^                  ^
// Carrets (^) represent starting and ending point of the matches

t.Pattern("<{tag}>{text}</{tag}>");
t.Pattern("<b>{text}</b>");
t.Pattern("<h3>{text}</h3>");
t.SkipOver("<!--{text}-->");
t.Find();

foreach(var match in t.Matches) {
   Console.WriteLine(match.Text);
   Console.WriteLine($"Start pos: {match.StartPosition}");
   Console.WriteLine($"End pos: {match.EndPosition}");
   Console.WriteLine($"Length: {match.Length}");
   Console.WriteLine("");
}
				
			
<h3>Title</h3>
Start pos: 0
End pos: 14
Length: 14

<b>Bold statement</b>
Start pos: 14
End pos: 35
Length: 21

<b>Other text</b>
Start pos: 58
End pos: 75
Length: 17

<p>My paragraph</p>
Start pos: 75
End pos: 94
Length: 19
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("<h3>Title</h3><b>Bold statement</b><!--<h3>Title B</h3>--><b>Other text</b><p>My paragraph</p>");
   //     0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456
   //     0         10        20        30        40        50        60        70        80        90
   //     ^             ^                                           ^                ^                  ^
   // Carrets (^) represent starting and ending point of the matches

   t.Pattern("<{tag}>{text}</{tag}>");
   t.Pattern("<b>{text}</b>");
   t.Pattern("<h3>{text}</h3>");
   t.SkipOver("<!--{text}-->");
   t.Find();

   for(auto match : t.Matches()) {
      cout << match.Text() << endl;
      cout << "Start pos: " << match.StartPosition() << endl;
      cout << "End pos: " << match.EndPosition() << endl;
      cout << "Length: " << match.Length() << endl;
      cout << "" << endl;
   }
}
				
			
<h3>Title</h3>
Start pos: 0
End pos: 14
Length: 14

<b>Bold statement</b>
Start pos: 14
End pos: 35
Length: 21

<b>Other text</b>
Start pos: 58
End pos: 75
Length: 17

<p>My paragraph</p>
Start pos: 75
End pos: 94
Length: 19
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "<h3>Title</h3><b>Bold statement</b><!--<h3>Title B</h3>--><b>Other text</b><p>My paragraph</p>"
      '//     0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456
      '//     0         10        20        30        40        50        60        70        80        90
      '//     ^             ^                                           ^                ^                  ^
      '// Carrets (^) represent starting and ending point of the matches
      
      t.Pattern("<{tag}>{text}</{tag}>")
      t.Pattern("<b>{text}</b>")
      t.Pattern("<h3>{text}</h3>")
      t.SkipOver("<!--{text}-->")
      t.Find()
      
      For Each match In t.Matches
         Console.WriteLine(match.Text)
         Console.WriteLine($"Start pos: {match.StartPosition}")
         Console.WriteLine($"End pos: {match.EndPosition}")
         Console.WriteLine($"Length: {match.Length}")
         Console.WriteLine("")
      Next
   End Sub
End Module
				
			
<h3>Title</h3>
Start pos: 0
End pos: 14
Length: 14

<b>Bold statement</b>
Start pos: 14
End pos: 35
Length: 21

<b>Other text</b>
Start pos: 58
End pos: 75
Length: 17

<p>My paragraph</p>
Start pos: 75
End pos: 94
Length: 19
Previous
Next