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.

# if cfg!(miri) { return Ok(()); } // miri takes too long
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));

# Ok::<(), Box<dyn std::error::Error>>(())