MatchError in regex_automata - Rust (original) (raw)
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, likehybrid::dfa::Config::unicode_word_boundary.)
There are a couple other ways a search can fail. For example, when using theBoundedBacktrackerwith a haystack that is too long, or trying to run an unanchored search with a one-pass DFA.
Create a new error value with the given kind.
This is a more verbose version of the kind-specific constructors, e.g., MatchError::quit.
Returns a reference to the underlying error kind.
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 aMatchErrorKind::Quit kind.
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 aMatchErrorKind::GaveUp kind.
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 aMatchErrorKind::HaystackTooLong kind.
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 aMatchErrorKind::UnsupportedAnchored kind.
The lower-level source of this error, if any. Read more
👎Deprecated since 1.42.0: use the Display impl or to_string()
👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting
🔬This is a nightly-only experimental API. (error_generic_member_access)
Provides type based access to context intended for error reports. Read more
This method tests for self and other values to be equal, and is used by ==.
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.