Struct Match

pub struct Match { /* private fields */ }

A representation of a match reported by a regex engine.

A match has two essential pieces of information: the PatternID that matches, and the Span of the match in a haystack.

The pattern is identified by an ID, which corresponds to its position (starting from 0) relative to other patterns used to construct the corresponding regex engine. If only a single pattern is provided, then all matches are guaranteed to have a pattern ID of 0.

Every match reported by a regex engine guarantees that its span has its start offset as less than or equal to its end offset.

Implementations

impl Match

pub fn new<S: Into<Span>>(pattern: PatternID, span: S) -> Match

Create a new match from a pattern ID and a span.

This constructor is generic over how a span is provided. While a Span may be given directly, one may also provide a std::ops::Range<usize>.

Panics

This panics if end < start.

Example

This shows how to create a match for the first pattern in a regex object using convenient range syntax.

use regex_automata::{Match, PatternID};

let m = Match::new(PatternID::ZERO, 5..10);
assert_eq!(0, m.pattern().as_usize());
assert_eq!(5, m.start());
assert_eq!(10, m.end());

pub fn must<S: Into<Span>>(pattern: usize, span: S) -> Match

Create a new match from a pattern ID and a byte offset span.

This constructor is generic over how a span is provided. While a Span may be given directly, one may also provide a std::ops::Range<usize>.

This is like Match::new, but accepts a usize instead of a PatternID. This panics if the given usize is not representable as a PatternID.

Panics

This panics if end < start or if pattern > PatternID::MAX.

Example

This shows how to create a match for the third pattern in a regex object using convenient range syntax.

use regex_automata::Match;

let m = Match::must(3, 5..10);
assert_eq!(3, m.pattern().as_usize());
assert_eq!(5, m.start());
assert_eq!(10, m.end());

pub fn pattern(&self) -> PatternID

Returns the ID of the pattern that matched.

The ID of a pattern is derived from the position in which it was originally inserted into the corresponding regex engine. The first pattern has identifier 0, and each subsequent pattern is 1, 2 and so on.

pub fn start(&self) -> usize

The starting position of the match.

This is a convenience routine for Match::span().start.

pub fn end(&self) -> usize

The ending position of the match.

This is a convenience routine for Match::span().end.

pub fn range(&self) -> Range<usize>

Returns the match span as a range.

This is a convenience routine for Match::span().range().

pub fn span(&self) -> Span

Returns the span for this match.

pub fn is_empty(&self) -> bool

Returns true when the span in this match is empty.

An empty match can only be returned when the regex itself can match the empty string.

pub fn len(&self) -> usize

Returns the length of this match.

This returns 0 in precisely the cases that is_empty returns true.

Trait Implementations

impl Clone for Match

fn clone(&self) -> Match

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Match

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Match

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Match

fn eq(&self, other: &Match) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Match

impl Eq for Match

impl StructuralPartialEq for Match