Struct Builder

struct Builder { ... }

A builder for constructing a lazy deterministic finite automaton from regular expressions.

As a convenience, DFA::builder is an alias for Builder::new. The advantage of the former is that it often lets you avoid importing the Builder type directly.

This builder provides two main things:

  1. It provides a few different build routines for actually constructing a DFA from different kinds of inputs. The most convenient is Builder::build, which builds a DFA directly from a pattern string. The most flexible is Builder::build_from_nfa, which builds a DFA straight from an NFA.
  2. The builder permits configuring a number of things. Builder::configure is used with Config to configure aspects of the DFA and the construction process itself. Builder::syntax and Builder::thompson permit configuring the regex parser and Thompson NFA construction, respectively. The syntax and thompson configurations only apply when building from a pattern string.

This builder always constructs a single lazy DFA. As such, this builder can only be used to construct regexes that either detect the presence of a match or find the end location of a match. A single DFA cannot produce both the start and end of a match. For that information, use a Regex, which can be similarly configured using regex::Builder. The main reason to use a DFA directly is if the end location of a match is enough for your use case. Namely, a Regex will construct two lazy DFAs instead of one, since a second reverse DFA is needed to find the start of a match.

Example

This example shows how to build a lazy DFA that uses a tiny cache capacity and completely disables Unicode. That is:

use regex_automata::{
    hybrid::dfa::DFA,
    nfa::thompson,
    util::syntax,
    HalfMatch, Input,
};

let dfa = DFA::builder()
    .configure(DFA::config().cache_capacity(5_000))
    .thompson(thompson::Config::new().utf8(false))
    .syntax(syntax::Config::new().unicode(false).utf8(false))
    .build(r"foo[^b]ar.*")?;
let mut cache = dfa.create_cache();

let haystack = b"\xFEfoo\xFFar\xE2\x98\xFF\n";
let expected = Some(HalfMatch::must(0, 10));
let got = dfa.try_search_fwd(&mut cache, &Input::new(haystack))?;
assert_eq!(expected, got);

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

Implementations

impl Builder

fn new() -> Builder

Create a new lazy DFA builder with the default configuration.

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

Build a lazy DFA 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<DFA, BuildError>

Build a lazy DFA from the given patterns.

When matches are returned, the pattern ID corresponds to the index of the pattern in the slice given.

fn build_from_nfa(self: &Self, nfa: NFA) -> Result<DFA, BuildError>

Build a DFA from the given NFA.

Note that this requires owning a thompson::NFA. While this may force you to clone the NFA, such a clone is not a deep clone. Namely, NFAs are defined internally to support shared ownership such that cloning is very cheap.

Example

This example shows how to build a lazy DFA if you already have an NFA in hand.

use regex_automata::{
    hybrid::dfa::DFA,
    nfa::thompson,
    HalfMatch, Input,
};

let haystack = "foo123bar";

// This shows how to set non-default options for building an NFA.
let nfa = thompson::Compiler::new()
    .configure(thompson::Config::new().shrink(true))
    .build(r"[0-9]+")?;
let dfa = DFA::builder().build_from_nfa(nfa)?;
let mut cache = dfa.create_cache();
let expected = Some(HalfMatch::must(0, 6));
let got = dfa.try_search_fwd(&mut cache, &Input::new(haystack))?;
assert_eq!(expected, got);

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

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

Apply the given lazy DFA configuration options to this builder.

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.

These settings only apply when constructing a lazy DFA directly from a pattern.

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 the DFA should match the regex in reverse or if additional time should be spent shrinking the size of the NFA.

These settings only apply when constructing a DFA directly from a pattern.

impl Clone for Builder

fn clone(self: &Self) -> Builder

impl Debug for Builder

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

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>