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
impl Anchored
Sourcepub fn is_anchored(&self) -> bool
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());Sourcepub fn pattern(&self) -> Option<PatternID>
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());