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.

GetMatches

Method

Product: 

Transformer Library

Class: 

Rule

Retrieves the collection of matches found specifically by this rule, with options to filter the results.

Syntax

GetMatches(MatchesOption, bool)

Parameters

options
MatchesOption
(Default = MatchesOption::SameAsBefore)
Specifies the subset of matches to return, such as all, focusable only, or only the root/innermost level.
Map_UTF16
bool
(Default = false)
Internal use only. Controls UTF-16 character mapping for .NET environments.

Return

Matches

A Matches object containing the collection of matches found by this rule, filtered according to the provided options.

Remarks

🎯 Rule.GetMatches Property

Retrieves the collection of matches generated exclusively by this specific Rule, providing a more granular view than the global Transformer.Matches property.

This property is your primary tool for inspecting the results of a single pattern. While myTransformer.Matches returns a collection of all matches found by all active rules, myRule.Matches returns only the subset of those matches that were found by myRule.

⚙️ Filtering with MatchesOption

The optional options parameter allows you to refine the returned list based on the structure and properties of the matches, using members of the MatchesOption enum:

  • MatchesOption::All (Default): Returns all matches found by this rule.
  • MatchesOption::FocusableOnly: Returns only those matches if this rule was marked as focusable (e.g., with myRule.Focusable = true).
  • MatchesOption::RootLevelOnly: In a set of nested matches (created by a LocalTransformer), this returns only the top-level (parent) matches from this rule.
  • MatchesOption::InnermostOnly: The opposite of RootLevelOnly; returns only the most deeply nested (child) matches from this rule.

This filtering is a performance optimization, as it allows you to get different views of the results without re-running the initial Find() or Transform() operation.

💡 Why uCalc? (Comparative Analysis)

In other environments, such as using LINQ in C#, you would typically get a single large list of all results and then filter it manually.

Typical C# LINQ Approach:

// Get all matches and then filter by rule referencevar ruleSpecificMatches = allMatches.Where(m => m.Rule == mySpecificRule).ToList();

While functional, this approach performs the filtering in the host application after retrieving all the data. uCalc's design is more efficient:

  • Engine-Side Filtering: By passing the options and calling the property on a specific Rule, the filtering logic is executed inside the highly optimized uCalc engine.
  • Direct Access: It provides a more direct and declarative way to ask, "Show me just the results for this pattern," leading to cleaner and more readable code.

Examples

A succinct example showing the difference between counting all matches versus matches for a specific rule.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "A B C A B C";

var ruleA = t.Pattern("A");
var ruleB = t.Pattern("B");

t.Find();

Console.WriteLine($"Total matches (all rules): {t.Matches.Count()}");
Console.WriteLine($"Matches for Rule A only: {ruleA.Matches.Count()}");
Console.WriteLine($"Matches for Rule B only: {ruleB.Matches.Count()}");
				
			
Total matches (all rules): 4
Matches for Rule A only: 2
Matches for Rule B only: 2
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("A B C A B C");

   auto ruleA = t.Pattern("A");
   auto ruleB = t.Pattern("B");

   t.Find();

   cout << "Total matches (all rules): " << t.Matches().Count() << endl;
   cout << "Matches for Rule A only: " << ruleA.Matches().Count() << endl;
   cout << "Matches for Rule B only: " << ruleB.Matches().Count() << endl;
}
				
			
Total matches (all rules): 4
Matches for Rule A only: 2
Matches for Rule B only: 2
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "A B C A B C"
      
      Dim ruleA = t.Pattern("A")
      Dim ruleB = t.Pattern("B")
      
      t.Find()
      
      Console.WriteLine($"Total matches (all rules): {t.Matches.Count()}")
      Console.WriteLine($"Matches for Rule A only: {ruleA.Matches.Count()}")
      Console.WriteLine($"Matches for Rule B only: {ruleB.Matches.Count()}")
   End Sub
End Module
				
			
Total matches (all rules): 4
Matches for Rule A only: 2
Matches for Rule B only: 2
A practical example using `MatchesOption::FocusableOnly` to retrieve results only from rules marked as focusable.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "ID:100, Name:Admin, ID:200";

// Mark 'ID' rules as focusable, but 'Name' rules as secondary.
var idRule = t.Pattern("ID:{@Number}").SetFocusable(true);
var nameRule = t.Pattern("Name:{@Alpha}").SetFocusable(false);
t.Find();

// Get the matches for the 'idRule' specifically, filtered to only focusable results.
var focusableIdMatches = idRule.GetMatches(MatchesOption.FocusableOnly);

Console.WriteLine($"Focusable 'ID' matches found: {focusableIdMatches.Count()}");
Console.WriteLine(focusableIdMatches.Text);
				
			
Focusable 'ID' matches found: 2
ID:100
ID:200
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("ID:100, Name:Admin, ID:200");

   // Mark 'ID' rules as focusable, but 'Name' rules as secondary.
   auto idRule = t.Pattern("ID:{@Number}").SetFocusable(true);
   auto nameRule = t.Pattern("Name:{@Alpha}").SetFocusable(false);
   t.Find();

   // Get the matches for the 'idRule' specifically, filtered to only focusable results.
   auto focusableIdMatches = idRule.GetMatches(MatchesOption::FocusableOnly);

   cout << "Focusable 'ID' matches found: " << focusableIdMatches.Count() << endl;
   cout << focusableIdMatches.Text() << endl;
}
				
			
Focusable 'ID' matches found: 2
ID:100
ID:200
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "ID:100, Name:Admin, ID:200"
      
      '// Mark 'ID' rules as focusable, but 'Name' rules as secondary.
      Dim idRule = t.Pattern("ID:{@Number}").SetFocusable(true)
      Dim nameRule = t.Pattern("Name:{@Alpha}").SetFocusable(false)
      t.Find()
      
      '// Get the matches for the 'idRule' specifically, filtered to only focusable results.
      Dim focusableIdMatches = idRule.GetMatches(MatchesOption.FocusableOnly)
      
      Console.WriteLine($"Focusable 'ID' matches found: {focusableIdMatches.Count()}")
      Console.WriteLine(focusableIdMatches.Text)
   End Sub
End Module
				
			
Focusable 'ID' matches found: 2
ID:100
ID:200
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);
Console.WriteLine("");

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

Console.WriteLine($"Only H3Tag matches -- count = {H3Tag.Matches.Count()}");
Console.WriteLine("-----------------------------");
Console.WriteLine(H3Tag.Matches);
				
			
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() << endl;
   cout << "" << endl;

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

   cout << "Only H3Tag matches -- count = " << H3Tag.Matches().Count() << endl;
   cout << "-----------------------------" << endl;
   cout << H3Tag.Matches() << 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)
      Console.WriteLine("")
      
      Console.WriteLine($"Only BoldTag matches -- count = {BoldTag.Matches.Count()}")
      Console.WriteLine("-------------------------------")
      Console.WriteLine(BoldTag.Matches)
      Console.WriteLine("")
      
      Console.WriteLine($"Only H3Tag matches -- count = {H3Tag.Matches.Count()}")
      Console.WriteLine("-----------------------------")
      Console.WriteLine(H3Tag.Matches)
   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>
Using IndexOf() in Matches
				
					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>");
//     ^             ^                    ^               ^                ^
//     012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789
//     0         10        20        30        40        50        60        70        80
// Carrets (^) point to Start locations of the matches

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("IndexOf   StartPos   Match");
Console.WriteLine("");

Console.WriteLine("All Matches");
Console.WriteLine("-----------");
foreach(var match in t.Matches) {
   Console.WriteLine($"{t.Matches.IndexOf(match.StartPosition)}         {match.StartPosition}          {match.Text}");
}
Console.WriteLine("");

Console.WriteLine("Bold Matches");
Console.WriteLine("------------");
foreach(var BoldMatch in BoldTag.Matches) {
   Console.WriteLine($"{t.Matches.IndexOf(BoldMatch.StartPosition)}         {BoldMatch.StartPosition}          {BoldMatch.Text}");
}
Console.WriteLine("");

Console.WriteLine("H3 Matches");
Console.WriteLine("----------");
foreach(var H3Match in H3Tag.Matches) {
   Console.WriteLine($"{t.Matches.IndexOf(H3Match.StartPosition)}         {H3Match.StartPosition}          {H3Match.Text}");
}
Console.WriteLine("");

Console.WriteLine("Other Matches");
Console.WriteLine("-------------");
foreach(var AnyOtherMatch in AnyOtherTag.Matches) {
   Console.WriteLine($"{t.Matches.IndexOf(AnyOtherMatch.StartPosition)}         {AnyOtherMatch.StartPosition}          {AnyOtherMatch.Text}");
}
				
			
IndexOf   StartPos   Match

All Matches
-----------
0         0          <h3>Title</h3>
1         14          <b>Bold statement</b>
2         35          <h3>Title B</h3>
3         51          <b>Other text</b>
4         68          <p>My paragraph</p>

Bold Matches
------------
1         14          <b>Bold statement</b>
3         51          <b>Other text</b>

H3 Matches
----------
0         0          <h3>Title</h3>
2         35          <h3>Title B</h3>

Other Matches
-------------
4         68          <p>My paragraph</p>
				
					#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>");
   //     ^             ^                    ^               ^                ^
   //     012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789
   //     0         10        20        30        40        50        60        70        80
   // Carrets (^) point to Start locations of the matches

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

   cout << "IndexOf   StartPos   Match" << endl;
   cout << "" << endl;

   cout << "All Matches" << endl;
   cout << "-----------" << endl;
   for(auto match : t.Matches()) {
      cout << t.Matches().IndexOf(match.StartPosition()) << "         " << match.StartPosition() << "          " << match.Text() << endl;
   }
   cout << "" << endl;

   cout << "Bold Matches" << endl;
   cout << "------------" << endl;
   for(auto BoldMatch : BoldTag.Matches()) {
      cout << t.Matches().IndexOf(BoldMatch.StartPosition()) << "         " << BoldMatch.StartPosition() << "          " << BoldMatch.Text() << endl;
   }
   cout << "" << endl;

   cout << "H3 Matches" << endl;
   cout << "----------" << endl;
   for(auto H3Match : H3Tag.Matches()) {
      cout << t.Matches().IndexOf(H3Match.StartPosition()) << "         " << H3Match.StartPosition() << "          " << H3Match.Text() << endl;
   }
   cout << "" << endl;

   cout << "Other Matches" << endl;
   cout << "-------------" << endl;
   for(auto AnyOtherMatch : AnyOtherTag.Matches()) {
      cout << t.Matches().IndexOf(AnyOtherMatch.StartPosition()) << "         " << AnyOtherMatch.StartPosition() << "          " << AnyOtherMatch.Text() << endl;
   }
}
				
			
IndexOf   StartPos   Match

All Matches
-----------
0         0          <h3>Title</h3>
1         14          <b>Bold statement</b>
2         35          <h3>Title B</h3>
3         51          <b>Other text</b>
4         68          <p>My paragraph</p>

Bold Matches
------------
1         14          <b>Bold statement</b>
3         51          <b>Other text</b>

H3 Matches
----------
0         0          <h3>Title</h3>
2         35          <h3>Title B</h3>

Other Matches
-------------
4         68          <p>My paragraph</p>
				
					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>")
      '//     ^             ^                    ^               ^                ^
      '//     012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789
      '//     0         10        20        30        40        50        60        70        80
      '// Carrets (^) point to Start locations of the matches
      
      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("IndexOf   StartPos   Match")
      Console.WriteLine("")
      
      Console.WriteLine("All Matches")
      Console.WriteLine("-----------")
      For Each match In t.Matches
         Console.WriteLine($"{t.Matches.IndexOf(match.StartPosition)}         {match.StartPosition}          {match.Text}")
      Next
      Console.WriteLine("")
      
      Console.WriteLine("Bold Matches")
      Console.WriteLine("------------")
      For Each BoldMatch In BoldTag.Matches
         Console.WriteLine($"{t.Matches.IndexOf(BoldMatch.StartPosition)}         {BoldMatch.StartPosition}          {BoldMatch.Text}")
      Next
      Console.WriteLine("")
      
      Console.WriteLine("H3 Matches")
      Console.WriteLine("----------")
      For Each H3Match In H3Tag.Matches
         Console.WriteLine($"{t.Matches.IndexOf(H3Match.StartPosition)}         {H3Match.StartPosition}          {H3Match.Text}")
      Next
      Console.WriteLine("")
      
      Console.WriteLine("Other Matches")
      Console.WriteLine("-------------")
      For Each AnyOtherMatch In AnyOtherTag.Matches
         Console.WriteLine($"{t.Matches.IndexOf(AnyOtherMatch.StartPosition)}         {AnyOtherMatch.StartPosition}          {AnyOtherMatch.Text}")
      Next
   End Sub
End Module
				
			
IndexOf   StartPos   Match

All Matches
-----------
0         0          <h3>Title</h3>
1         14          <b>Bold statement</b>
2         35          <h3>Title B</h3>
3         51          <b>Other text</b>
4         68          <p>My paragraph</p>

Bold Matches
------------
1         14          <b>Bold statement</b>
3         51          <b>Other text</b>

H3 Matches
----------
0         0          <h3>Title</h3>
2         35          <h3>Title B</h3>

Other Matches
-------------
4         68          <p>My paragraph</p>
Previous
Next