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.

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

The difference between counting all matches versus matches for a specific rule.

ID: 876

See: GetMatches 
				
					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
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("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
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 = "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
Explore 600+ other examples
A practical example using `MatchesOption::FocusableOnly` to retrieve results only from rules marked as focusable.

ID: 877

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

ID: 112

See: GetMatches, GetMatches, Matches = [Matches], Matches = [Matches], Str() 
				
					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>
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() << 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>
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)
      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>
Explore 600+ other examples
Using IndexOf() in Matches

ID: 113

See: GetMatches, IndexOf, Matches = [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>
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>");
   //     ^             ^                    ^               ^                ^
   //     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>
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>")
      '//     ^             ^                    ^               ^                ^
      '//     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>
Explore 600+ other examples