Rust Regex Search Contracts

Search configuration is part of correctness. A faster engine is interchangeable only when its match policy, boundary context, offsets, and failure behavior match the caller's contract.

Choose the contract first

Prefer the meta engine unless measured requirements justify owning lower-level limitations. It composes engines and fallbacks; choosing a standalone DFA also transfers unsupported-input handling to you.

Preserve context

With regex-automata = "=0.4.13":

use regex_automata::{meta::Regex, Anchored, Input};
let re = Regex::new(r"\bcat\b")?;
let hay = "bobcat!";
assert!(re.is_match(&hay[3..6])); // Wrong context: invents a word.
assert!(!re.is_match(Input::new(hay).span(3..6)));

let token = Regex::new(r"[a-z]+")?;
let input = Input::new("!cat").span(0..4).anchored(Anchored::Yes);
assert!(token.find(input).is_none()); // Reject the gap; don't skip '!'.

Anchored::Yes refers to the search start. Default ^ refers to the haystack start; multiline mode changes its meaning again. Validate input ranges before searching. Keep returned offsets in the original byte coordinate system.

Before replacing an engine, compare pattern IDs, spans, captures, empty matches, Unicode cases, and errors, not just match counts. The fixture provides six failure/remedy cases; provenance records runtime limits.

Pitfalls

• Reordering alternatives or patterns changes leftmost-first results. Longest-token lexing needs its own explicit selection policy.
• earliest(true) may change the chosen match; it is not a semantics-preserving speed switch.
• MatchKind::All is not a drop-in “find every occurrence” mode for ordinary unanchored iteration.
• Handwritten cursor loops can stall on empty matches; use the engine's iterator when its non-overlapping semantics fit.