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.

Introduction

Product: 

Transformer Library

Class: 

Match

Represents a single successful match from a Transformer operation, providing access to its text, position, and originating rule.

Remarks

🎯 The Match Object: A Snapshot of a Find

A Match object represents a single successful pattern match from a Transformer operation. It is a read-only snapshot that contains detailed information about a specific substring that was found, including its content, its location within the source text, and the rule that generated it.

You do not create Match objects directly. Instead, you access them by iterating through a Matches collection, which is returned by methods like Transformer.Matches after a Find() or Transform() operation.

⚙️ Core Properties

PropertyDescription
TextRetrieves the read-only string of characters captured by the match.
StartPositionGets the zero-based starting character position of the match within the source text.
EndPositionGets the zero-based index of the character position immediately following the match's last character.
LengthGets the length, in characters, of the substring captured by the match.
RuleRetrieves the Rule object that generated this specific match, enabling runtime introspection.

Examples

Assigns descriptive text to multiple rules and uses the `Rule` property to identify which rule generated each match.
				
					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>";

var AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag");
var BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag");
var H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag");
t.Find();

foreach(var match in t.Matches) {
   Console.WriteLine(match.Text + "   Description: " + match.Rule.Description);
}
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
				
					#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>");

   auto AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag");
   auto BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag");
   auto H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag");
   t.Find();

   for(auto match : t.Matches()) {
      cout << match.Text() + "   Description: " + match.Rule().Description() << endl;
   }
}
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
				
					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>"
      
      Dim AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag")
      Dim BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag")
      Dim H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag")
      t.Find()
      
      For Each match In t.Matches
         Console.WriteLine(match.Text + "   Description: " + match.Rule.Description)
      Next
   End Sub
End Module
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
A practical example that iterates through all words in a sentence to find the one with the greatest length.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "Find the longest word in this sentence.";
t.Pattern("{@Alpha}"); // Match all words
t.Find();

int maxLength = 0;
string longestWord = "";
foreach(var match in t.Matches) {
   if (match.Length > maxLength) {
      maxLength = match.Length;
      longestWord = match.Text;
   }
}

Console.WriteLine($"Longest word is '{longestWord}' with length: {maxLength}");
				
			
Longest word is 'sentence' with length: 8
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("Find the longest word in this sentence.");
   t.Pattern("{@Alpha}"); // Match all words
   t.Find();

   int maxLength = 0;
   string longestWord = "";
   for(auto match : t.Matches()) {
      if (match.Length() > maxLength) {
         maxLength = match.Length();
         longestWord = match.Text();
      }
   }

   cout << "Longest word is '" << longestWord << "' with length: " << maxLength << endl;
}
				
			
Longest word is 'sentence' with length: 8
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "Find the longest word in this sentence."
      t.Pattern("{@Alpha}") '// Match all words
      t.Find()
      
      Dim maxLength As Integer = 0
      Dim longestWord As String = ""
      For Each match In t.Matches
         If match.Length > maxLength Then
            maxLength = match.Length
            longestWord = match.Text
         End If
      Next
      
      Console.WriteLine($"Longest word is '{longestWord}' with length: {maxLength}")
   End Sub
End Module
				
			
Longest word is 'sentence' with length: 8
Finds a single match and retrieves the name of the rule that generated it.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var ruleA = t.FromTo("apple", "fruit");
t.Text = "an apple a day";
t.Find();

var firstMatch = t.Matches[0];
var generatingRule = firstMatch.Rule;

Console.Write("Match text: '"); Console.Write(firstMatch.Text); Console.Write("' was found by rule: '"); Console.Write(generatingRule.Name); Console.Write("'");
				
			
Match text: 'apple' was found by rule: 'apple'
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto ruleA = t.FromTo("apple", "fruit");
   t.Text("an apple a day");
   t.Find();

   auto firstMatch = t.Matches()[0];
   auto generatingRule = firstMatch.Rule();

   cout << "Match text: '" << firstMatch.Text() << "' was found by rule: '" << generatingRule.Name() << "'";
}
				
			
Match text: 'apple' was found by rule: 'apple'
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim ruleA = t.FromTo("apple", "fruit")
      t.Text = "an apple a day"
      t.Find()
      
      Dim firstMatch = t.Matches(0)
      Dim generatingRule = firstMatch.Rule
      
      Console.Write("Match text: '")
      Console.Write(firstMatch.Text)
      Console.Write("' was found by rule: '")
      Console.Write(generatingRule.Name)
      Console.Write("'")
   End Sub
End Module
				
			
Match text: 'apple' was found by rule: 'apple'
Previous
Next