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.

MatchesOption

Enum

Product: 

Class: 

For filtering list of transformer or search matches

Name ▲ ▼ Value ▲ ▼ Description ▲ ▼
All

Returns all matches (default)
SameAsBefore

Returns list of matches using the same filter as the previous transform or search operation
EmptyList

Returns an empty list
RootLevelOnly

Returns only main level matches, and no child submatches
InnermostOnly

Returns only innermost child matches
FocusableOnly

Returns only matches specified as focusable
NoOffset

Not used

Remarks

This allows you to filter the list of matches returned by [topic: uCalc.Transformer.Matches].

Examples

Focusable to select only patterns from local transformer
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var FruitsXML =
"""

<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <!-- <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' /> -->
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <!-- <Fruit CommonName='Mango' ScientificName='Mangifera indica' /> -->
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <!-- <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' /> -->
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <!-- <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' /> -->
</Fruits>

""";

// List names of fruit within comment, not the whole comment as well
t.Text = FruitsXML;
var CommentedFruits = t.Pattern("<!-- {comment} -->").SetFocusable(false);
var CommentedFruitsTr = CommentedFruits.LocalTransformer;
CommentedFruitsTr.FromTo("CommonName={@string:text}", "{text}").Focusable = true;

t.Filter();
Console.WriteLine("With Focusable()");
Console.WriteLine("----------------");
Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text);
Console.WriteLine("");

// Note: The displayed Fruit element is modified by CommentedFruitsTr.FromTo()
Console.WriteLine("Without Focusable()");
Console.WriteLine("-------------------");
Console.WriteLine(t.Matches.Text);
				
			
With Focusable()
----------------
Grapes
Mango
Rambutan
Watermelon

Without Focusable()
-------------------
<!-- <Fruit Grapes ScientificName='Vitis vinifera' /> -->
Grapes
<!-- <Fruit Mango ScientificName='Mangifera indica' /> -->
Mango
<!-- <Fruit Rambutan ScientificName='Nephelium lappaceum' /> -->
Rambutan
<!-- <Fruit Watermelon ScientificName='Citrullus lanatus' /> -->
Watermelon
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto FruitsXML =
   R"(
<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <!-- <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' /> -->
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <!-- <Fruit CommonName='Mango' ScientificName='Mangifera indica' /> -->
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <!-- <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' /> -->
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <!-- <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' /> -->
</Fruits>
)";

   // List names of fruit within comment, not the whole comment as well
   t.Text(FruitsXML);
   auto CommentedFruits = t.Pattern("<!-- {comment} -->").SetFocusable(false);
   auto CommentedFruitsTr = CommentedFruits.LocalTransformer();
   CommentedFruitsTr.FromTo("CommonName={@string:text}", "{text}").Focusable(true);

   t.Filter();
   cout << "With Focusable()" << endl;
   cout << "----------------" << endl;
   cout << t.GetMatches(MatchesOption::FocusableOnly).Text() << endl;
   cout << "" << endl;

   // Note: The displayed Fruit element is modified by CommentedFruitsTr.FromTo()
   cout << "Without Focusable()" << endl;
   cout << "-------------------" << endl;
   cout << t.Matches().Text() << endl;
}
				
			
With Focusable()
----------------
Grapes
Mango
Rambutan
Watermelon

Without Focusable()
-------------------
<!-- <Fruit Grapes ScientificName='Vitis vinifera' /> -->
Grapes
<!-- <Fruit Mango ScientificName='Mangifera indica' /> -->
Mango
<!-- <Fruit Rambutan ScientificName='Nephelium lappaceum' /> -->
Rambutan
<!-- <Fruit Watermelon ScientificName='Citrullus lanatus' /> -->
Watermelon
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim FruitsXML =
      "
<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <!-- <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' /> -->
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <!-- <Fruit CommonName='Mango' ScientificName='Mangifera indica' /> -->
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <!-- <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' /> -->
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <!-- <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' /> -->
</Fruits>
"
      
      '// List names of fruit within comment, not the whole comment as well
      t.Text = FruitsXML
      Dim CommentedFruits = t.Pattern("<!-- {comment} -->").SetFocusable(false)
      Dim CommentedFruitsTr = CommentedFruits.LocalTransformer
      CommentedFruitsTr.FromTo("CommonName={@string:text}", "{text}").Focusable = true
      
      t.Filter()
      Console.WriteLine("With Focusable()")
      Console.WriteLine("----------------")
      Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text)
      Console.WriteLine("")
      
      '// Note: The displayed Fruit element is modified by CommentedFruitsTr.FromTo()
      Console.WriteLine("Without Focusable()")
      Console.WriteLine("-------------------")
      Console.WriteLine(t.Matches.Text)
   End Sub
End Module
				
			
With Focusable()
----------------
Grapes
Mango
Rambutan
Watermelon

Without Focusable()
-------------------
<!-- <Fruit Grapes ScientificName='Vitis vinifera' /> -->
Grapes
<!-- <Fruit Mango ScientificName='Mangifera indica' /> -->
Mango
<!-- <Fruit Rambutan ScientificName='Nephelium lappaceum' /> -->
Rambutan
<!-- <Fruit Watermelon ScientificName='Citrullus lanatus' /> -->
Watermelon
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