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.

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.
---## 📜 Members of the Matches CollectionThis section provides a high-level overview. For details on the individual `Match` object, see the [Match](/Reference/uCalcBase/Matches/Match) class documentation.| Member                                                        | Description                                                                                                      || :------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------- || **Indexer `[]`**                                              | Accesses an individual `Match` object in the collection by its zero-based index.                                   || [`Count()`](/Reference/uCalcBase/Matches/Count)               | Gets the total number of matches in the collection.                                                              || [`Text`](/Reference/uCalcBase/Matches/Text)                   | Returns a single string of all match texts concatenated by newlines.                                             || [`ApplyOffset()`](/Reference/uCalcBase/Matches/ApplyOffset)       | Adjusts the start/end positions of all matches by a given offset.                                                || [`IndexOf()`](/Reference/uCalcBase/Matches/IndexOf)           | Finds the index of a match given its starting character position.                                                || [`Reset()`](/Reference/uCalcBase/Matches/Reset)                 | Clears or re-filters the match list without re-running the search.                                               || [`uCalc()`](/Reference/uCalcBase/Matches/uCalc)                 | Retrieves the parent `uCalc` instance providing the execution context.                                           || [`Release()`](/Reference/uCalcBase/Matches/Release)               | Releases the `Matches` object and its resources.                                                                 || [`Match`](/Reference/uCalcBase/Matches/Match) class             | Represents a single match, with properties like [Text](/Reference/uCalcBase/Matches/Match/Text), [StartPosition](/Reference/uCalcBase/Matches/Match/StartPosition), [EndPosition](/Reference/uCalcBase/Matches/Match/EndPosition), [Length](/Reference/uCalcBase/Matches/Match/Length), and [Rule()](/Reference/uCalcBase/Matches/Match/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](/Reference/uCalcBase/Matches/Match) provides much richer context. The ability to retrieve the specific [Rule](/Reference/uCalcBase/Rule/Constructor) that generated the match via [match.Rule()](/Reference/uCalcBase/Matches/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](/Reference/Enums/MatchesOption) flags (e.g., [RootLevelOnly](/Reference/Enums/MatchesOption), [InnermostOnly](/Reference/Enums/MatchesOption)) which is more efficient than filtering a full result set in application code.

Examples

How to count all alphanumeric words in a sentence.

ID: 785

See: Count, Introduction 
				
					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
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("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
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 = "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
Explore 600+ other examples
Finding all occurrences of a word, getting the total count, and displaying the text of the first match.

ID: 1312

See: Introduction 
				
					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
Explore 600+ other examples
				
					#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
Explore 600+ other examples
				
					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
Explore 600+ other examples
Filters matches by rule; FilterByRule, Matches.Str, Matches.Count

ID: 855

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