Enum regex_automata::MatchError

pub enum MatchError {
    Quit {
        byte: u8,
        offset: usize,
    },
    GaveUp {
        offset: usize,
    },
}

An error type indicating that a search stopped prematurely without finding a match.

This error type implies that one cannot assume that no matches occur, since the search stopped before completing.

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.

Advice

While this form of error reporting adds complexity, it is generally possible for callers to configure regex engines to never give up a search, and thus never return an error. Indeed, the default configuration for every regex engine in this crate is such that they will never stop searching early. Therefore, the only way to get a match error is if the regex engine is explicitly configured to do so. Options that enable this behavior document the new error conditions they imply.

Regex engines for which no errors are possible for any configuration will return the normal Option<Match> and not use this error type at all.

For example, regex engines in the dfa sub-module will only report MatchError::Quit if instructed by either enabling Unicode word boundaries or by explicitly specifying one or more quit bytes.

Variants

Quit

Fields

byte: u8

The “quit” byte that was observed that caused the search to stop.

offset: usize

The offset at which the quit byte was observed.

The search saw a “quit” byte at which it was instructed to stop searching.

GaveUp

Fields

offset: usize

The offset at which the search stopped. This corresponds to the position immediately following the last byte scanned.

The search, based on heuristics, determined that it would be better to stop, typically to provide the caller an opportunity to use an alternative regex engine.

Currently, the only way for this to occur is via the lazy DFA and only when it is configured to do so (it will not return this error by default).

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

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

The lower-level source of this error, if any.

fn backtrace(&self) -> Option<&Backtrace>

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

Returns a stack backtrace, if available, of where this error occurred.

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

impl Hash for MatchError

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, 

Feeds a slice of this type into the given Hasher.

impl PartialEq<MatchError> for MatchError

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

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

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

This method tests for !=.

impl Eq for MatchError

impl StructuralEq for MatchError

impl StructuralPartialEq for MatchError