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.

Reset

Method

Product: 

Transformer Library

Class: 

Matches

Clears or re-filters the collection of matches from a Transformer operation.

Syntax

Reset(MatchesOption)

Parameters

options
MatchesOption
(Default = MatchesOption::SameAsBefore)
An enum member specifying how to reset or filter the collection of matches.

Return

void

This method does not return a value; it modifies the Matches object in place.

Remarks

The Reset method modifies the current Matches collection by either clearing it or re-filtering the original result set according to the specified options.

This is primarily a performance optimization. Instead of re-running a potentially expensive Find() operation on a Transformer, you can use Reset to quickly obtain a different view of the matches that were already found.

Filtering with MatchesOption

The behavior of Reset is controlled by the options parameter, which accepts a member of the MatchesOption enum:

  • MatchesOption::EmptyList: Clears the collection, resulting in a count of 0. This is useful for freeing memory associated with the match list.
  • MatchesOption::All: Resets the list to include all matches originally found by the Transformer operation.
  • MatchesOption::FocusableOnly: Filters the list to include only those matches generated by rules that were marked as focusable (e.g., with rule.Focusable(true)).
  • MatchesOption::RootLevelOnly: In a set of nested matches created by a LocalTransformer, this option filters the list to include only the top-level (parent) matches.
  • MatchesOption::InnermostOnly: The opposite of RootLevelOnly; filters the list to include only the most deeply nested (child) matches.
  • MatchesOption::SameAsBefore (Default): Re-applies the same filter option that was used when the Matches object was last retrieved. For example, if you called transformer.Matches(MatchesOption::FocusableOnly), a subsequent call to matches.Reset() would behave as if you called matches.Reset(MatchesOption::FocusableOnly).

⚖️ Comparative Analysis

In a language like C#, developers might filter a collection of results using LINQ:

// C# LINQ examplevar focusableMatches = allMatches.Where(m => m.Rule.IsFocusable).ToList();

This approach is stateless and creates a new collection. uCalc's Reset method is different: it is stateful and modifies the existing Matches collection in-place. This can be more memory-efficient as it avoids allocating a new list for each filtered view. The ability to re-filter without re-running the initial Find operation is a significant performance advantage for complex patterns on large documents.

Examples

Practical: Re-filters a result set to show only 'focusable' matches without re-running the search.
				
					using uCalcSoftware;

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

// Define two rules, but only one is marked as 'focusable'
var idRule = t.Pattern("ID:{@Number}").SetFocusable(true);
var nameRule = t.Pattern("Name:{@Alpha}").SetFocusable(false);
t.Find();

var matches = t.GetMatches(MatchesOption.All);
Console.WriteLine("--- All Matches ---");
Console.WriteLine($"Count: {matches.Count()}");
Console.WriteLine(matches.Text);

// Now, re-filter the same results to get only the focusable ones
matches.Reset(MatchesOption.FocusableOnly);
Console.WriteLine("");
Console.WriteLine("--- Focusable Matches Only ---");
Console.WriteLine($"Count: {matches.Count()}");
Console.WriteLine(matches.Text);
				
			
--- All Matches ---
Count: 3
ID:100
Name:Admin
ID:200

--- Focusable Matches Only ---
Count: 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");

   // Define two rules, but only one is marked as 'focusable'
   auto idRule = t.Pattern("ID:{@Number}").SetFocusable(true);
   auto nameRule = t.Pattern("Name:{@Alpha}").SetFocusable(false);
   t.Find();

   auto matches = t.GetMatches(MatchesOption::All);
   cout << "--- All Matches ---" << endl;
   cout << "Count: " << matches.Count() << endl;
   cout << matches.Text() << endl;

   // Now, re-filter the same results to get only the focusable ones
   matches.Reset(MatchesOption::FocusableOnly);
   cout << "" << endl;
   cout << "--- Focusable Matches Only ---" << endl;
   cout << "Count: " << matches.Count() << endl;
   cout << matches.Text() << endl;
}
				
			
--- All Matches ---
Count: 3
ID:100
Name:Admin
ID:200

--- Focusable Matches Only ---
Count: 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"
      
      '// Define two rules, but only one is marked as 'focusable'
      Dim idRule = t.Pattern("ID:{@Number}").SetFocusable(true)
      Dim nameRule = t.Pattern("Name:{@Alpha}").SetFocusable(false)
      t.Find()
      
      Dim matches = t.GetMatches(MatchesOption.All)
      Console.WriteLine("--- All Matches ---")
      Console.WriteLine($"Count: {matches.Count()}")
      Console.WriteLine(matches.Text)
      
      '// Now, re-filter the same results to get only the focusable ones
      matches.Reset(MatchesOption.FocusableOnly)
      Console.WriteLine("")
      Console.WriteLine("--- Focusable Matches Only ---")
      Console.WriteLine($"Count: {matches.Count()}")
      Console.WriteLine(matches.Text)
   End Sub
End Module
				
			
--- All Matches ---
Count: 3
ID:100
Name:Admin
ID:200

--- Focusable Matches Only ---
Count: 2
ID:100
ID:200
Previous
Next