Struct MatchError

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

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

pub 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.

pub fn kind(&self) -> &MatchErrorKind

Returns a reference to the underlying error kind.

pub 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.

pub 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.

pub 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.

pub 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.

Trait Implementations

impl Clone for MatchError

fn clone(&self) -> MatchError

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MatchError

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

Formats the value using the given formatter.

impl Display for MatchError

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

Formats the value using the given formatter.

impl Error for MatchError

Available on crate feature std only.

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl PartialEq for MatchError

fn eq(&self, other: &MatchError) -> 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 Eq for MatchError

impl StructuralPartialEq for MatchError