Struct regex_automata::RegexBuilder

pub struct RegexBuilder { /* private fields */ }

A builder for a regex based on deterministic finite automatons.

This builder permits configuring several aspects of the construction process such as case insensitivity, Unicode support and various options that impact the size of the underlying DFAs. In some cases, options (like performing DFA minimization) can come with a substantial additional cost.

This builder generally constructs two 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 dense::Builder to construct a single DFA, which is cheaper than building two DFAs.

Implementations

impl RegexBuilder

pub fn new() -> RegexBuilder

Create a new regex builder with the default configuration.

pub fn build(&self, pattern: &str) -> Result<Regex, Error>

Build a regex from the given pattern.

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

pub fn build_sparse(
    &self,
    pattern: &str
) -> Result<Regex<SparseDFA<Vec<u8>, usize>>, Error>

Build a regex from the given pattern using sparse DFAs.

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

pub fn build_with_size<S: StateID>(
    &self,
    pattern: &str
) -> Result<Regex<DenseDFA<Vec<S>, S>>, Error>

Build a regex from the given pattern using a specific representation for the underlying DFA state IDs.

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

The representation of state IDs is determined by the S type parameter. In general, S is usually one of u8, u16, u32, u64 or usize, where usize is the default used for build. The purpose of specifying a representation for state IDs is to reduce the memory footprint of the underlying DFAs.

When using this routine, the chosen state ID representation will be used throughout determinization and minimization, if minimization was requested. Even if the minimized DFAs can fit into the chosen state ID representation but the initial determinized DFA cannot, then this will still return an error. To get a minimized DFA with a smaller state ID representation, first build it with a bigger state ID representation, and then shrink the sizes of the DFAs using one of its conversion routines, such as DenseDFA::to_u16. Finally, reconstitute the regex via Regex::from_dfa.

pub fn build_with_size_sparse<S: StateID>(
    &self,
    pattern: &str
) -> Result<Regex<SparseDFA<Vec<u8>, S>>, Error>

Build a regex from the given pattern using a specific representation for the underlying DFA state IDs using sparse DFAs.

pub fn anchored(&mut self, yes: bool) -> &mut RegexBuilder

Set whether matching must be anchored at the beginning of the input.

When enabled, a match must begin at the start of the input. When disabled, the regex will act as if the pattern started with a .*?, which enables a match to appear anywhere.

By default this is disabled.

pub fn case_insensitive(&mut self, yes: bool) -> &mut RegexBuilder

Enable or disable the case insensitive flag by default.

By default this is disabled. It may alternatively be selectively enabled in the regular expression itself via the i flag.

pub fn ignore_whitespace(&mut self, yes: bool) -> &mut RegexBuilder

Enable verbose mode in the regular expression.

When enabled, verbose mode permits insigificant whitespace in many places in the regular expression, as well as comments. Comments are started using # and continue until the end of the line.

By default, this is disabled. It may be selectively enabled in the regular expression by using the x flag regardless of this setting.

pub fn dot_matches_new_line(&mut self, yes: bool) -> &mut RegexBuilder

Enable or disable the “dot matches any character” flag by default.

By default this is disabled. It may alternatively be selectively enabled in the regular expression itself via the s flag.

pub fn swap_greed(&mut self, yes: bool) -> &mut RegexBuilder

Enable or disable the “swap greed” flag by default.

By default this is disabled. It may alternatively be selectively enabled in the regular expression itself via the U flag.

pub fn unicode(&mut self, yes: bool) -> &mut RegexBuilder

Enable or disable the Unicode flag (u) by default.

By default this is enabled. It may alternatively be selectively disabled in the regular expression itself via the u flag.

Note that unless allow_invalid_utf8 is enabled (it’s disabled by default), a regular expression will fail to parse if Unicode mode is disabled and a sub-expression could possibly match invalid UTF-8.

pub fn allow_invalid_utf8(&mut self, yes: bool) -> &mut RegexBuilder

When enabled, the builder will permit the construction of a regular expression that may match invalid UTF-8.

When disabled (the default), the builder is guaranteed to produce a regex that will only ever match valid UTF-8 (otherwise, the builder will return an error).

pub fn nest_limit(&mut self, limit: u32) -> &mut RegexBuilder

Set the nesting limit used for the regular expression parser.

The nesting limit controls how deep the abstract syntax tree is allowed to be. If the AST exceeds the given limit (e.g., with too many nested groups), then an error is returned by the parser.

The purpose of this limit is to act as a heuristic to prevent stack overflow when building a finite automaton from a regular expression’s abstract syntax tree. In particular, construction currently uses recursion. In the future, the implementation may stop using recursion and this option will no longer be necessary.

This limit is not checked until the entire AST is parsed. Therefore, if callers want to put a limit on the amount of heap space used, then they should impose a limit on the length, in bytes, of the concrete pattern string. In particular, this is viable since the parser will limit itself to heap space proportional to the lenth of the pattern string.

Note that a nest limit of 0 will return a nest limit error for most patterns but not all. For example, a nest limit of 0 permits a but not ab, since ab requires a concatenation AST item, which results in a nest depth of 1. In general, a nest limit is not something that manifests in an obvious way in the concrete syntax, therefore, it should not be used in a granular way.

pub fn minimize(&mut self, yes: bool) -> &mut RegexBuilder

Minimize the underlying DFAs.

When enabled, the DFAs powering the resulting regex will be minimized such that it is as small as possible.

Whether one enables minimization or not depends on the types of costs you’re willing to pay and how much you care about its benefits. In particular, minimization has worst case O(n*k*logn) time and O(k*n) space, where n is the number of DFA states and k is the alphabet size. In practice, minimization can be quite costly in terms of both space and time, so it should only be done if you’re willing to wait longer to produce a DFA. In general, you might want a minimal DFA in the following circumstances:

1. You would like to optimize for the size of the automaton. This can manifest in one of two ways. Firstly, if you’re converting the DFA into Rust code (or a table embedded in the code), then a minimal DFA will translate into a corresponding reduction in code size, and thus, also the final compiled binary size. Secondly, if you are building many DFAs and putting them on the heap, you’ll be able to fit more if they are smaller. Note though that building a minimal DFA itself requires additional space; you only realize the space savings once the minimal DFA is constructed (at which point, the space used for minimization is freed).
2. You’ve observed that a smaller DFA results in faster match performance. Naively, this isn’t guaranteed since there is no inherent difference between matching with a bigger-than-minimal DFA and a minimal DFA. However, a smaller DFA may make use of your CPU’s cache more efficiently.
3. You are trying to establish an equivalence between regular languages. The standard method for this is to build a minimal DFA for each language and then compare them. If the DFAs are equivalent (up to state renaming), then the languages are equivalent.

This option is disabled by default.

pub fn premultiply(&mut self, yes: bool) -> &mut RegexBuilder

Premultiply state identifiers in the underlying DFA transition tables.

When enabled, state identifiers are premultiplied to point to their corresponding row in the DFA’s transition table. That is, given the ith state, its corresponding premultiplied identifier is i * k where k is the alphabet size of the DFA. (The alphabet size is at most 256, but is in practice smaller if byte classes is enabled.)

When state identifiers are not premultiplied, then the identifier of the ith state is i.

The advantage of premultiplying state identifiers is that is saves a multiplication instruction per byte when searching with the DFA. This has been observed to lead to a 20% performance benefit in micro-benchmarks.

The primary disadvantage of premultiplying state identifiers is that they require a larger integer size to represent. For example, if your DFA has 200 states, then its premultiplied form requires 16 bits to represent every possible state identifier, where as its non-premultiplied form only requires 8 bits.

This option is enabled by default.

pub fn byte_classes(&mut self, yes: bool) -> &mut RegexBuilder

Shrink the size of the underlying DFA alphabet by mapping bytes to their equivalence classes.

When enabled, each DFA will use a map from all possible bytes to their corresponding equivalence class. Each equivalence class represents a set of bytes that does not discriminate between a match and a non-match in the DFA. For example, the pattern [ab]+ has at least two equivalence classes: a set containing a and b and a set containing every byte except for a and b. a and b are in the same equivalence classes because they never discriminate between a match and a non-match.

The advantage of this map is that the size of the transition table can be reduced drastically from #states * 256 * sizeof(id) to #states * k * sizeof(id) where k is the number of equivalence classes. As a result, total space usage can decrease substantially. Moreover, since a smaller alphabet is used, compilation becomes faster as well.

The disadvantage of this map is that every byte searched must be passed through this map before it can be used to determine the next transition. This has a small match time performance cost.

This option is enabled by default.

Trait Implementations

impl Clone for RegexBuilder

fn clone(&self) -> RegexBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RegexBuilder

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

Formats the value using the given formatter.

impl Default for RegexBuilder

fn default() -> RegexBuilder

Returns the “default value” for a type.