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.

Matches = [Matches]

Property

Product: 

Transformer Library

Class: 

Rule

Retrieves the collection of matches found exclusively by this rule, allowing for a filtered view of a transformation's results.

Remarks

🎯 Rule.Matches 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.

💡 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

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>
MatchesOption: RootLevelOnly and InnermostOnly
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var txt = "<p id='aa'>xyz</p><p id='bb'>Hello</p ><p id='cc'>World</p>";
t.Str(txt);

t.Pattern("<p {etc}>").LocalTransformer.FromTo("id={@string:id}", "{id}");
t.Filter();


Console.WriteLine("All matches");
Console.WriteLine("-----------");
Console.WriteLine(t.GetMatches(MatchesOption.All).Text); // All is the default
Console.WriteLine("");

Console.WriteLine("RootLevelOnly");
Console.WriteLine("-------------");
Console.WriteLine(t.GetMatches(MatchesOption.RootLevelOnly).Text);
Console.WriteLine("");

Console.WriteLine("InnermostOnly");
Console.WriteLine("-------------");
Console.WriteLine(t.GetMatches(MatchesOption.InnermostOnly).Text);
Console.WriteLine("");
				
			
All matches
-----------
<p aa>
aa
<p bb>
bb
<p cc>
cc

RootLevelOnly
-------------
<p aa>
<p bb>
<p cc>

InnermostOnly
-------------
aa
bb
cc
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto txt = "<p id='aa'>xyz</p><p id='bb'>Hello</p ><p id='cc'>World</p>";
   t.Str(txt);

   t.Pattern("<p {etc}>").LocalTransformer().FromTo("id={@string:id}", "{id}");
   t.Filter();


   cout << "All matches" << endl;
   cout << "-----------" << endl;
   cout << t.GetMatches(MatchesOption::All).Text() << endl; // All is the default
   cout << "" << endl;

   cout << "RootLevelOnly" << endl;
   cout << "-------------" << endl;
   cout << t.GetMatches(MatchesOption::RootLevelOnly).Text() << endl;
   cout << "" << endl;

   cout << "InnermostOnly" << endl;
   cout << "-------------" << endl;
   cout << t.GetMatches(MatchesOption::InnermostOnly).Text() << endl;
   cout << "" << endl;
}
				
			
All matches
-----------
<p aa>
aa
<p bb>
bb
<p cc>
cc

RootLevelOnly
-------------
<p aa>
<p bb>
<p cc>

InnermostOnly
-------------
aa
bb
cc
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim txt = "<p id='aa'>xyz</p><p id='bb'>Hello</p ><p id='cc'>World</p>"
      t.Str(txt)
      
      t.Pattern("<p {etc}>").LocalTransformer.FromTo("id={@string:id}", "{id}")
      t.Filter()
      
      
      Console.WriteLine("All matches")
      Console.WriteLine("-----------")
      Console.WriteLine(t.GetMatches(MatchesOption.All).Text) '// All is the default
      Console.WriteLine("")
      
      Console.WriteLine("RootLevelOnly")
      Console.WriteLine("-------------")
      Console.WriteLine(t.GetMatches(MatchesOption.RootLevelOnly).Text)
      Console.WriteLine("")
      
      Console.WriteLine("InnermostOnly")
      Console.WriteLine("-------------")
      Console.WriteLine(t.GetMatches(MatchesOption.InnermostOnly).Text)
      Console.WriteLine("")
   End Sub
End Module
				
			
All matches
-----------
<p aa>
aa
<p bb>
bb
<p cc>
cc

RootLevelOnly
-------------
<p aa>
<p bb>
<p cc>

InnermostOnly
-------------
aa
bb
cc
Previous
Next