Enum regex_automata::Anchored

source ·
pub enum Anchored {
    No,
    Yes,
    Pattern(PatternID),
}
Expand description

The type of anchored search to perform.

This is almost a boolean option. That is, you can either do an unanchored search for any pattern in a regex, or you can do an anchored search for any pattern in a regex.

A third option exists that, assuming the regex engine supports it, permits you to do an anchored search for a specific pattern.

Note that there is no way to run an unanchored search for a specific pattern. If you need that, you’ll need to build separate regexes for each pattern.

§Errors

If a regex engine does not support the anchored mode selected, then the regex engine will return an error. While any non-trivial regex engine should support at least one of the available anchored modes, there is no singular mode that is guaranteed to be universally supported. Some regex engines might only support unanchored searches (DFAs compiled without anchored starting states) and some regex engines might only support anchored searches (like the one-pass DFA).

The specific error returned is a MatchError with a MatchErrorKind::UnsupportedAnchored kind. The kind includes the Anchored value given that is unsupported.

Note that regex engines should report “no match” if, for example, an Anchored::Pattern is provided with an invalid pattern ID but where anchored searches for a specific pattern are supported. This is smooths out behavior such that it’s possible to guarantee that an error never occurs based on how the regex engine is configured. All regex engines in this crate report “no match” when searching for an invalid pattern ID, but where searching for a valid pattern ID is otherwise supported.

§Example

This example shows how to use the various Anchored modes to run a search. We use the PikeVM because it supports all modes unconditionally. Some regex engines, like the onepass::DFA cannot support unanchored searches.

use regex_automata::{
    nfa::thompson::pikevm::PikeVM,
    Anchored, Input, Match, PatternID,
};

let re = PikeVM::new_many(&[
    r"Mrs. \w+",
    r"Miss \w+",
    r"Mr. \w+",
    r"Ms. \w+",
])?;
let mut cache = re.create_cache();
let hay = "Hello Mr. Springsteen!";

// The default is to do an unanchored search.
assert_eq!(Some(Match::must(2, 6..21)), re.find(&mut cache, hay));
// Explicitly ask for an unanchored search. Same as above.
let input = Input::new(hay).anchored(Anchored::No);
assert_eq!(Some(Match::must(2, 6..21)), re.find(&mut cache, hay));

// Now try an anchored search. Since the match doesn't start at the
// beginning of the haystack, no match is found!
let input = Input::new(hay).anchored(Anchored::Yes);
assert_eq!(None, re.find(&mut cache, input));

// We can try an anchored search again, but move the location of where
// we start the search. Note that the offsets reported are still in
// terms of the overall haystack and not relative to where we started
// the search.
let input = Input::new(hay).anchored(Anchored::Yes).range(6..);
assert_eq!(Some(Match::must(2, 6..21)), re.find(&mut cache, input));

// Now try an anchored search for a specific pattern. We specifically
// choose a pattern that we know doesn't match to prove that the search
// only looks for the pattern we provide.
let input = Input::new(hay)
    .anchored(Anchored::Pattern(PatternID::must(1)))
    .range(6..);
assert_eq!(None, re.find(&mut cache, input));

// But if we switch it to the pattern that we know matches, then we find
// the match.
let input = Input::new(hay)
    .anchored(Anchored::Pattern(PatternID::must(2)))
    .range(6..);
assert_eq!(Some(Match::must(2, 6..21)), re.find(&mut cache, input));

Variants§

§

No

Run an unanchored search. This means a match may occur anywhere at or after the start position of the search.

This search can return a match for any pattern in the regex.

§

Yes

Run an anchored search. This means that a match must begin at the start position of the search.

This search can return a match for any pattern in the regex.

§

Pattern(PatternID)

Run an anchored search for a specific pattern. This means that a match must be for the given pattern and must begin at the start position of the search.

Implementations§

source§

impl Anchored

source

pub fn is_anchored(&self) -> bool

Returns true if and only if this anchor mode corresponds to any kind of anchored search.

§Example

This examples shows that both Anchored::Yes and Anchored::Pattern are considered anchored searches.

use regex_automata::{Anchored, PatternID};

assert!(!Anchored::No.is_anchored());
assert!(Anchored::Yes.is_anchored());
assert!(Anchored::Pattern(PatternID::ZERO).is_anchored());
source

pub fn pattern(&self) -> Option<PatternID>

Returns the pattern ID associated with this configuration if it is an anchored search for a specific pattern. Otherwise None is returned.

§Example
use regex_automata::{Anchored, PatternID};

assert_eq!(None, Anchored::No.pattern());
assert_eq!(None, Anchored::Yes.pattern());

let pid = PatternID::must(5);
assert_eq!(Some(pid), Anchored::Pattern(pid).pattern());

Trait Implementations§

source§

impl Clone for Anchored

source§

fn clone(&self) -> Anchored

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 Anchored

source§

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

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

impl PartialEq for Anchored

source§

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

source§

impl Eq for Anchored

source§

impl StructuralPartialEq for Anchored

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