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

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§

source§

impl MatchError

source

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.

source

pub fn kind(&self) -> &MatchErrorKind

Returns a reference to the underlying error kind.

source

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.

source

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.

source

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.

source

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§

source§

impl Clone for MatchError

source§

fn clone(&self) -> MatchError

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for MatchError

source§

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

Formats the value using the given formatter. Read more
source§

impl Display for MatchError

source§

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

Formats the value using the given formatter. Read more
source§

impl Error for MatchError

1.30.0 · source§

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

The lower-level source of this error, if any. Read more
1.0.0 · source§

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()
1.0.0 · source§

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

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

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. Read more
source§

impl PartialEq for MatchError

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for MatchError

source§

impl StructuralEq for MatchError

source§

impl StructuralPartialEq for MatchError

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.