Module regex_automata::util::captures

Provides types for dealing with capturing groups.

Capturing groups refer to sub-patterns of regexes that some regex engines can report matching offsets for. For example, matching [a-z]([0-9]+) against a789 would give a789 as the overall match (for the implicit capturing group at index 0) and 789 as the match for the capturing group ([0-9]+) (an explicit capturing group at index 1).

Not all regex engines can report match offsets for capturing groups. Indeed, to a first approximation, regex engines that can report capturing group offsets tend to be quite a bit slower than regex engines that can’t. This is because tracking capturing groups at search time usually requires more “power” that in turn adds overhead.

Other regex implementations might call capturing groups “submatches.”

Overview

The main types in this module are:

• Captures records the capturing group offsets found during a search. It provides convenience routines for looking up capturing group offsets by either index or name.
• GroupInfo records the mapping between capturing groups and “slots,” where the latter are how capturing groups are recorded during a regex search. This also keeps a mapping from capturing group name to index, and capture group index to name. A GroupInfo is used by Captures internally to provide a convenient API. It is unlikely that you’ll use a GroupInfo directly, but for example, if you’ve compiled an Thompson NFA, then you can use thompson::NFA::group_info to get its underlying GroupInfo.

Structs

• Captures
  The span offsets of capturing groups after a match has been found.
• CapturesPatternIter
  An iterator over all capturing groups in a Captures value.
• GroupInfo
  Represents information about capturing groups in a compiled regex.
• GroupInfoAllNames
  An iterator over capturing groups and their names for a GroupInfo.
• GroupInfoError
  An error that may occur when building a GroupInfo.
• GroupInfoPatternNames
  An iterator over capturing groups and their names for a specific pattern.