🎯 The Matches Collection: Your Search Results

The uCalc.Matches object is a collection that holds the results of a pattern-matching operation performed by a uCalc.Transformer. It is not created directly; instead, it is returned by the Matches property of a Transformer after calling Find(), Filter(), or Transform().

⚙️ Core Concepts

• Read-Only Snapshot: A Matches object is a snapshot of the results at a moment in time. The collection itself doesn't change if you re-run a transform, but you can get a new Matches object with updated results.
• Collection-like Behavior: It acts like a list or array. You can get its Count(), iterate through it, and access individual Match objects by index.
• Rich Metadata: Each element in the collection is not just a string, but a rich Match object containing details like the captured text, its start and end positions, its length, and—crucially—a reference to the Rule that generated the match.

How to Use It

The typical workflow is simple:

1. Configure a Transformer with rules.
2. Run an operation like Find().
3. Get the results via the Matches property.
4. Loop through the collection to analyze each Match.

using uCalcSoftware;

var uc = new uCalc();

using (var t = new uCalc.Transformer()) {
   t.Pattern("{@Alphanumeric}");
   t.Text("One two three");
   t.Find();

   var m = t.Matches();
   Console.WriteLine($"Found {m.Count()} matches.");
   for (var i = 0; i <= m.Count() - 1; i++) {
      Console.WriteLine($" - Match {i}: '{m[i].Text()}' at position {m[i].StartPosition()}");
   }
}

📜 Members of the Matches Collection

This section provides a high-level overview. For details on the individual Match object, see the Match class documentation.

⚖️ Comparative Analysis: uCalc.Matches vs. Regex MatchCollection

• Token Awareness: Regex matches are character-based. A uCalc.Matches collection contains results from a token-aware engine, so the matches are structurally sound and respect boundaries like quotes and brackets by default.
• Introspection: A standard regex Match provides the captured string and its position. A uCalc Match provides much richer context. The ability to retrieve the specific Rule that generated the match via match.Rule() is invaluable for debugging and for building applications with complex, layered logic where you need to know why something was matched.
• Filtering: uCalc provides built-in, engine-side filtering via MatchesOption flags (e.g., RootLevelOnly, InnermostOnly) which is more efficient than filtering a full result set in application code.