Struct `Builder`

struct Builder { ... }

A builder for a regex based on a hybrid NFA/DFA.

This builder permits configuring options for the syntax of a pattern, the NFA construction, the lazy DFA construction and finally the regex searching itself. This builder is different from a general purpose regex builder in that it permits fine grain configuration of the construction process. The trade off for this is complexity, and the possibility of setting a configuration that might not make sense. For example, there are two different UTF-8 modes:

syntax::Config::utf8 controls whether the pattern itself can contain sub-expressions that match invalid UTF-8.
thompson::Config::utf8 controls how the regex iterators themselves advance the starting position of the next search when a match with zero length is found.

Generally speaking, callers will want to either enable all of these or disable all of these.

Internally, building a regex requires building two hybrid NFA/DFAs, where one is responsible for finding the end of a match and the other is responsible for finding the start of a match. If you only need to detect whether something matched, or only the end of a match, then you should use a dfa::Builder to construct a single hybrid NFA/DFA, which is cheaper than building two of them.

Example

This example shows how to disable UTF-8 mode in the syntax and the regex itself. This is generally what you want for matching on arbitrary bytes.

# if cfg!(miri) { return Ok(()); } // miri takes too long
use regex_automata::{
    hybrid::regex::Regex, nfa::thompson, util::syntax, Match,
};

let re = Regex::builder()
    .syntax(syntax::Config::new().utf8(false))
    .thompson(thompson::Config::new().utf8(false))
    .build(r"foo(?-u:[^b])ar.*")?;
let mut cache = re.create_cache();

let haystack = b"\xFEfoo\xFFarzz\xE2\x98\xFF\n";
let expected = Some(Match::must(0, 1..9));
let got = re.find(&mut cache, haystack);
assert_eq!(expected, got);
// Notice that `(?-u:[^b])` matches invalid UTF-8,
// but the subsequent `.*` does not! Disabling UTF-8
// on the syntax permits this.
assert_eq!(b"foo\xFFarzz", &haystack[got.unwrap().range()]);

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

Implementations

`impl Builder`

fn new() -> Builder

Create a new regex builder with the default configuration.

fn build(self: &Self, pattern: &str) -> Result<Regex, BuildError>

Build a regex from the given pattern.

If there was a problem parsing or compiling the pattern, then an error is returned.

fn build_many<P: AsRef<str>>(self: &Self, patterns: &[P]) -> Result<Regex, BuildError>

Build a regex from the given patterns.

fn build_from_dfas(self: &Self, forward: DFA, reverse: DFA) -> Regex

Build a regex from its component forward and reverse hybrid NFA/DFAs.

This is useful when you've built a forward and reverse lazy DFA separately, and want to combine them into a single regex. Once build, the individual DFAs given can still be accessed via Regex::forward and Regex::reverse.

It is important that the reverse lazy DFA be compiled under the following conditions:

It should use MatchKind::All semantics.
It should match in reverse.
Otherwise, its configuration should match the forward DFA.

If these conditions aren't satisfied, then the behavior of searches is unspecified.

Note that when using this constructor, no configuration is applied. Since this routine provides the DFAs to the builder, there is no opportunity to apply other configuration options.

Example

This shows how to build individual lazy forward and reverse DFAs, and then combine them into a single Regex.

use regex_automata::{
    hybrid::{dfa::DFA, regex::Regex},
    nfa::thompson,
    MatchKind,
};

let fwd = DFA::new(r"foo[0-9]+")?;
let rev = DFA::builder()
    .configure(DFA::config().match_kind(MatchKind::All))
    .thompson(thompson::Config::new().reverse(true))
    .build(r"foo[0-9]+")?;

let re = Regex::builder().build_from_dfas(fwd, rev);
let mut cache = re.create_cache();
assert_eq!(true, re.is_match(&mut cache, "foo123"));
# Ok::<(), Box<dyn std::error::Error>>(())

fn syntax(self: &mut Self, config: Config) -> &mut Builder

Set the syntax configuration for this builder using syntax::Config.

This permits setting things like case insensitivity, Unicode and multi line mode.

fn thompson(self: &mut Self, config: Config) -> &mut Builder

Set the Thompson NFA configuration for this builder using nfa::thompson::Config.

This permits setting things like whether additional time should be spent shrinking the size of the NFA.

fn dfa(self: &mut Self, config: Config) -> &mut Builder

Set the lazy DFA compilation configuration for this builder using dfa::Config.

This permits setting things like whether Unicode word boundaries should be heuristically supported or settings how the behavior of the cache.

`impl Clone for Builder`

fn clone(self: &Self) -> Builder

`impl Debug for Builder`

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

`impl Default for Builder`

fn default() -> Builder

`impl Freeze for Builder`

`impl RefUnwindSafe for Builder`

`impl Send for Builder`

`impl Sync for Builder`

`impl Unpin for Builder`

`impl UnsafeUnpin for Builder`

`impl UnwindSafe for Builder`

`impl<T> Any for Builder`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for Builder`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for Builder`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for Builder`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for Builder`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for Builder`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for Builder`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for Builder`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for Builder`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>