Struct `MatchError`

pub struct MatchError(/* private field */);

An error indicating that a search stopped before reporting whether a match exists or not.

To be very clear, this error type implies that one cannot assume that no matches occur, since the search stopped before completing. That is, if you're looking for information about where a search determined that no match can occur, then this error type does not give you that. (Indeed, at the time of writing, if you need such a thing, you have to write your own search routine.)

Normally, when one searches for something, the response is either an affirmative "it was found at this location" or a negative "not found at all." However, in some cases, a regex engine can be configured to stop its search before concluding whether a match exists or not. When this happens, it may be important for the caller to know why the regex engine gave up and where in the input it gave up at. This error type exposes the 'why' and the 'where.'

For example, the DFAs provided by this library generally cannot correctly implement Unicode word boundaries. Instead, they provide an option to eagerly support them on ASCII text (since Unicode word boundaries are equivalent to ASCII word boundaries when searching ASCII text), but will "give up" if a non-ASCII byte is seen. In such cases, one is usually required to either report the failure to the caller (unergonomic) or otherwise fall back to some other regex engine (ergonomic, but potentially costly).

More generally, some regex engines offer the ability for callers to specify certain bytes that will trigger the regex engine to automatically quit if they are seen.

Still yet, there may be other reasons for a failed match. For example, the hybrid DFA provided by this crate can be configured to give up if it believes that it is not efficient. This in turn permits callers to choose a different regex engine.

(Note that DFAs are configured by default to never quit or give up in this fashion. For example, by default, a DFA will fail to build if the regex pattern contains a Unicode word boundary. One needs to opt into the "quit" behavior via options, like hybrid::dfa::Config::unicode_word_boundary.)

There are a couple other ways a search can fail. For example, when using the BoundedBacktracker with a haystack that is too long, or trying to run an unanchored search with a one-pass DFA.

Implementations

`impl MatchError`

fn new(kind: MatchErrorKind) -> MatchError

Create a new error value with the given kind.

This is a more verbose version of the kind-specific constructors, e.g., MatchError::quit.

fn kind(&self) -> &MatchErrorKind

Returns a reference to the underlying error kind.

fn quit(byte: u8, offset: usize) -> MatchError

Create a new "quit" error. The given byte corresponds to the value that tripped a search's quit condition, and offset corresponds to the location in the haystack at which the search quit.

This is the same as calling MatchError::new with a MatchErrorKind::Quit kind.

fn gave_up(offset: usize) -> MatchError

Create a new "gave up" error. The given offset corresponds to the location in the haystack at which the search gave up.

This is the same as calling MatchError::new with a MatchErrorKind::GaveUp kind.

fn haystack_too_long(len: usize) -> MatchError

Create a new "haystack too long" error. The given len corresponds to the length of the haystack that was problematic.

This is the same as calling MatchError::new with a MatchErrorKind::HaystackTooLong kind.

fn unsupported_anchored(mode: Anchored) -> MatchError

Create a new "unsupported anchored" error. This occurs when the caller requests a search with an anchor mode that is not supported by the regex engine.

This is the same as calling MatchError::new with a MatchErrorKind::UnsupportedAnchored kind.