Struct regex_automata::hybrid::dfa::Builder

pub struct Builder { /* private fields */ }

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:

• Things such as \w, . and \b are no longer Unicode-aware. \w and \b are ASCII-only while . matches any byte except for \n (instead of any UTF-8 encoding of a Unicode scalar value except for \n). Things that are Unicode only, such as \pL, are not allowed.
• The pattern itself is permitted to match invalid UTF-8. For example, things like [^a] that match any byte except for a are permitted.
• Unanchored patterns can search through invalid UTF-8. That is, for unanchored patterns, the implicit prefix is (?s-u:.)*? instead of (?s:.)*?.

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

let dfa = DFA::builder()
    .configure(DFA::config().cache_capacity(5_000))
    .syntax(SyntaxConfig::new().unicode(false).utf8(false))
    .thompson(thompson::Config::new().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.find_leftmost_fwd(&mut cache, haystack)?;
assert_eq!(expected, got);

Implementations

impl Builder

pub fn new() -> Builder

Create a new lazy DFA builder with the default configuration.

pub fn build(&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.

pub fn build_many<P: AsRef<str>>(
    &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.

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

Build a DFA from the given NFA.

Note that this requires an Arc<thompson::NFA> instead of a &thompson::NFA because the lazy DFA builds itself from the NFA at search time. This means that the lazy DFA must hold on to its source NFA for the entirety of its lifetime. An Arc is used so that callers aren’t forced to clone the NFA if it is needed elsewhere.

Example

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

use std::sync::Arc;
use regex_automata::{hybrid::dfa::DFA, nfa::thompson, HalfMatch};

let haystack = "foo123bar".as_bytes();

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

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

Apply the given lazy DFA configuration options to this builder.

pub fn syntax(&mut self, config: SyntaxConfig) -> &mut Builder

Set the syntax configuration for this builder using SyntaxConfig.

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.

pub fn thompson(&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.

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Builder

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

Formats the value using the given formatter.