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: 

Matches

An overview of the Matches collection, which holds the results of a Transformer pattern-matching operation.

Remarks

🎯 The Matches Collection: Your Search Results

The uCalc.Matches object is a collection that holds the results of a pattern-matching operation performed by a uCalc.Transformer. It is not created directly; instead, it is returned by the Matches property of a Transformer after calling Find(), Filter(), or Transform().

⚙️ Core Concepts

  • Read-Only Snapshot: A Matches object is a snapshot of the results at a moment in time. The collection itself doesn't change if you re-run a transform, but you can get a new Matches object with updated results.
  • Collection-like Behavior: It acts like a list or array. You can get its Count(), iterate through it, and access individual Match objects by index.
  • Rich Metadata: Each element in the collection is not just a string, but a rich Match object containing details like the captured text, its start and end positions, its length, and—crucially—a reference to the Rule that generated the match.

How to Use It

The typical workflow is simple:

  1. Configure a Transformer with rules.
  2. Run an operation like Find().
  3. Get the results via the Matches property.
  4. Loop through the collection to analyze each Match.
using (var t = new uCalc.Transformer()) {t.Pattern("{@Alphanumeric}");t.Text("One two three");t.Find();var m = t.Matches();Console.WriteLine($"Found {m.Count()} matches.");for (var i = 0; i <= m.Count() - 1; i++) {    Console.WriteLine($" - Match {i}: '{m[i].Text()}' at position {m[i].StartPosition()}");}}

📜 Members of the Matches Collection

This section provides a high-level overview. For details on the individual Match object, see the Match class documentation.

MemberDescription
Indexer []Accesses an individual Match object in the collection by its zero-based index.
Count()Gets the total number of matches in the collection.
TextReturns a single string of all match texts concatenated by newlines.
ApplyOffset()Adjusts the start/end positions of all matches by a given offset.
IndexOf()Finds the index of a match given its starting character position.
Reset()Clears or re-filters the match list without re-running the search.
uCalc()Retrieves the parent uCalc instance providing the execution context.
Release()Releases the Matches object and its resources.
Match classRepresents a single match, with properties like Text, StartPosition, EndPosition, Length, and Rule().

⚖️ Comparative Analysis: uCalc.Matches vs. Regex MatchCollection

  • Token Awareness: Regex matches are character-based. A uCalc.Matches collection contains results from a token-aware engine, so the matches are structurally sound and respect boundaries like quotes and brackets by default.
  • Introspection: A standard regex Match provides the captured string and its position. A uCalc Match provides much richer context. The ability to retrieve the specific Rule that generated the match via match.Rule() is invaluable for debugging and for building applications with complex, layered logic where you need to know why something was matched.
  • Filtering: uCalc provides built-in, engine-side filtering via MatchesOption flags (e.g., RootLevelOnly, InnermostOnly) which is more efficient than filtering a full result set in application code.

Examples

A succinct example demonstrating how to count all alphanumeric words in a sentence.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "There are five words here.";

// Define a pattern to find any alphanumeric word
t.Pattern("{@Alpha}");
t.Find();

Console.WriteLine($"Total words found: {t.Matches.Count()}");
				
			
Total words found: 5
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("There are five words here.");

   // Define a pattern to find any alphanumeric word
   t.Pattern("{@Alpha}");
   t.Find();

   cout << "Total words found: " << t.Matches().Count() << endl;
}
				
			
Total words found: 5
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "There are five words here."
      
      '// Define a pattern to find any alphanumeric word
      t.Pattern("{@Alpha}")
      t.Find()
      
      Console.WriteLine($"Total words found: {t.Matches.Count()}")
   End Sub
End Module
				
			
Total words found: 5
A succinct example that finds all occurrences of a word, gets the total count, and displays the text of the first match.
				
					using uCalcSoftware;

var uc = new uCalc();
using (var t = new uCalc.Transformer()) {
   t.Text = "apple banana apple cherry";
   t.Pattern("apple");
   t.Find();

   var m = t.Matches;
   Console.WriteLine($"Matches found: {m.Count()}");
   if (m.Count() > 0) {
      Console.WriteLine($"First match: {m[0].Text}");
   }
};
				
			
Matches found: 2
First match: apple
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::Transformer t;
      t.Owned(); // Causes t to be released when it goes out of scope
      t.Text("apple banana apple cherry");
      t.Pattern("apple");
      t.Find();

      auto m = t.Matches();
      cout << "Matches found: " << m.Count() << endl;
      if (m.Count() > 0) {
         cout << "First match: " << m[0].Text() << endl;
      }
   };
}
				
			
Matches found: 2
First match: apple
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using t As New uCalc.Transformer()
         t.Text = "apple banana apple cherry"
         t.Pattern("apple")
         t.Find()
         
         Dim m = t.Matches
         Console.WriteLine($"Matches found: {m.Count()}")
         If m.Count() > 0 Then
            Console.WriteLine($"First match: {m(0).Text}")
         End If
      End Using
   End Sub
End Module
				
			
Matches found: 2
First match: apple
Filters matches by rule; FilterByRule, Matches.Str, Matches.Count
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Str("<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}>");
var BoldTag = t.Pattern("<b>{text}</b>");
var H3Tag = t.Pattern("<h3>{text}</h3>");
t.Find();

Console.WriteLine($"All matches -- count = {t.Matches.Count()}");
Console.WriteLine("----------------------");
Console.WriteLine(t.Matches.Text);
Console.WriteLine("");

Console.WriteLine($"Only BoldTag matches -- count = {BoldTag.Matches.Count()}");
Console.WriteLine("-------------------------------");
Console.WriteLine(BoldTag.Matches.Text);
Console.WriteLine("");

Console.WriteLine($"Only H3Tag matches -- count = {H3Tag.Matches.Count()}");
Console.WriteLine("-----------------------------");
Console.WriteLine(H3Tag.Matches.Text);
				
			
All matches -- count = 5
----------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
<p>My paragraph</p>

Only BoldTag matches -- count = 2
-------------------------------
<b>Bold statement</b>
<b>Other text</b>

Only H3Tag matches -- count = 2
-----------------------------
<h3>Title</h3>
<h3>Title B</h3>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Str("<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}>");
   auto BoldTag = t.Pattern("<b>{text}</b>");
   auto H3Tag = t.Pattern("<h3>{text}</h3>");
   t.Find();

   cout << "All matches -- count = " << t.Matches().Count() << endl;
   cout << "----------------------" << endl;
   cout << t.Matches().Text() << endl;
   cout << "" << endl;

   cout << "Only BoldTag matches -- count = " << BoldTag.Matches().Count() << endl;
   cout << "-------------------------------" << endl;
   cout << BoldTag.Matches().Text() << endl;
   cout << "" << endl;

   cout << "Only H3Tag matches -- count = " << H3Tag.Matches().Count() << endl;
   cout << "-----------------------------" << endl;
   cout << H3Tag.Matches().Text() << endl;
}
				
			
All matches -- count = 5
----------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
<p>My paragraph</p>

Only BoldTag matches -- count = 2
-------------------------------
<b>Bold statement</b>
<b>Other text</b>

Only H3Tag matches -- count = 2
-----------------------------
<h3>Title</h3>
<h3>Title B</h3>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Str("<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}>")
      Dim BoldTag = t.Pattern("<b>{text}</b>")
      Dim H3Tag = t.Pattern("<h3>{text}</h3>")
      t.Find()
      
      Console.WriteLine($"All matches -- count = {t.Matches.Count()}")
      Console.WriteLine("----------------------")
      Console.WriteLine(t.Matches.Text)
      Console.WriteLine("")
      
      Console.WriteLine($"Only BoldTag matches -- count = {BoldTag.Matches.Count()}")
      Console.WriteLine("-------------------------------")
      Console.WriteLine(BoldTag.Matches.Text)
      Console.WriteLine("")
      
      Console.WriteLine($"Only H3Tag matches -- count = {H3Tag.Matches.Count()}")
      Console.WriteLine("-----------------------------")
      Console.WriteLine(H3Tag.Matches.Text)
   End Sub
End Module
				
			
All matches -- count = 5
----------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
<p>My paragraph</p>

Only BoldTag matches -- count = 2
-------------------------------
<b>Bold statement</b>
<b>Other text</b>

Only H3Tag matches -- count = 2
-----------------------------
<h3>Title</h3>
<h3>Title B</h3>
Previous
Next