Enum Anchored

pub enum Anchored {
    No,
    Yes,
    Pattern(PatternID),
}

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

impl Anchored

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());

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

impl Clone for Anchored

fn clone(&self) -> Anchored

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Anchored

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

Formats the value using the given formatter.

impl PartialEq for Anchored

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

impl Eq for Anchored

impl StructuralPartialEq for Anchored