Struct RegexOptionsBuilder 

pub struct RegexOptionsBuilder { /* private fields */ }

A builder for a Regex to allow configuring options.

Implementations

impl RegexOptionsBuilder

pub fn new() -> Self

Create a new regex options builder.

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

Build a Regex from the given pattern.

Returns an Error if the pattern could not be parsed.

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

Override default case insensitive this is to enable/disable casing via builder instead of a flag within the raw string pattern which will be parsed

Default is false

pub fn multi_line(&mut self, yes: bool) -> &mut Self

Enable multi-line regex

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

Allow ignore whitespace

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

Enable or disable the “dot matches any character” flag. When this is enabled, . will match any character. When it’s disabled, then . will match any character except for a new line character.

pub fn crlf(&mut self, yes: bool) -> &mut Self

Enable or disable the CRLF mode flag (R).

When enabled, \r\n is treated as a single line ending for the purposes of ^ and $ in multi-line mode, instead of treating \r and \n as separate line endings.

By default, this is disabled. It may be selectively enabled in the regular expression by using the R flag, e.g. (?mR) or (?Rm).

pub fn verbose_mode(&mut self, yes: bool) -> &mut Self

Enable verbose mode in the regular expression.

The same as ignore_whitespace

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 unicode_mode(&mut self, yes: bool) -> &mut Self

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

By default this is enabled. The inline u flag inside a pattern is only accepted when it matches the current builder setting (e.g. (?u) when unicode is already enabled, or (?-u) when it is already disabled). Attempts to change the mode inline are rejected with a ParseError::ChangingUnicodeModeUnsupported error. Use this builder method to set the desired mode instead.

Effect on str input (default)

When matching against &str (the default), the underlying engine requires that all matches respect UTF-8 boundaries. Disabling Unicode therefore has the following effects:

• \w, \d, \s become ASCII-only ([a-zA-Z0-9_], [0-9], and ASCII whitespace respectively).
• \W, \D, \S, bare ., and \p{...} Unicode properties fail to compile, because they could match byte sequences that violate UTF-8 boundaries.

If you need those constructs with unicode_mode(false), use the bytes API with BytesMode::Ascii instead.

Effect on byte input

When matching against &[u8] (via BytesMode::Ascii), all constructs work as expected in ASCII mode (. matches any byte, \W/\D/\S match non-ASCII byte values, etc.).

WARNING: Unicode mode can greatly increase the size of the compiled DFA, which can noticeably impact both memory usage and compilation time. This is especially noticeable if your regex contains character classes like \w that are impacted by whether Unicode is enabled or not. If Unicode is not necessary, you are encouraged to disable it.

pub fn backtrack_limit(&mut self, limit: usize) -> &mut Self

Limit for how many times backtracking should be attempted for fancy regexes (where backtracking is used). If this limit is exceeded, execution returns an error with Error::BacktrackLimitExceeded. This is for preventing a regex with catastrophic backtracking to run for too long.

Default is 1_000_000 (1 million).

pub fn delegate_size_limit(&mut self, limit: usize) -> &mut Self

Set the approximate size limit of the compiled regular expression.

This option is forwarded from the wrapped regex crate. Note that depending on the used regex features there may be multiple delegated sub-regexes fed to the regex crate. As such the actual limit is closer to <number of delegated regexes> * delegate_size_limit.

pub fn delegate_dfa_size_limit(&mut self, limit: usize) -> &mut Self

Set the approximate size of the cache used by the DFA.

This option is forwarded from the wrapped regex crate. Note that depending on the used regex features there may be multiple delegated sub-regexes fed to the regex crate. As such the actual limit is closer to <number of delegated regexes> * delegate_dfa_size_limit.

pub fn find_not_empty(&mut self, yes: bool) -> &mut Self

Require that matches are non-empty (i.e. match at least one character).

When this is enabled, any match attempt that would result in a zero-length match is rejected.

Default is false.

N.B. When find_not_empty is set and analysis determines the pattern will only ever produce an empty match, compiling the regex will return CompileError::PatternCanNeverMatch instead of silently constructing a regex that can never return a result. This catches the user error at compile time rather than allowing the combination to execute pointlessly at runtime.

pub fn ignore_numbered_groups_when_named_groups_exist( &mut self, yes: bool, ) -> &mut Self

Treat unnamed capture groups as non-capturing when named groups exist. Prevents accessing capture groups by number from within the pattern (backrefs, subroutine calls) when named groups are present.

pub fn seek(&mut self, yes: bool) -> &mut Self

⚠️ Experimental: This API may change, be removed without notice, or cause matches to be skipped. This requires more real-world testing to prove correctness and observe in which circumstances it brings performance benefits and in which it has the opposite effect. Feedback (and benchmarks on real-world patterns/haystacks) would be very welcome!

Enable the Seek pre-filter optimization for hard (backtracking) patterns.

When enabled, the compiler attempts to derive a regular approximation of the pattern which is used to skip to the earliest plausible match position in the haystack before invoking the backtracking VM. This can dramatically speed up searches in long haystacks when the pattern can only match at infrequent positions.

The seek pattern is always a conservative over-approximation — it may report false-positive positions but will never skip a true match.

When yes is true, uses the default seek_pattern_is_useful filter to decide whether the derived pattern is worth using. When false, disables seek entirely.

To supply a custom filter, use seek_filter instead.

pub fn seek_filter(&mut self, filter: fn(&str) -> bool) -> &mut Self

Set a custom filter function that decides whether the derived seek pattern is useful.

The function receives the seek pattern string and returns true if the pattern should be used as a pre-filter, or false to fall back to the standard unanchored search.

Calling this method implicitly enables seek. Pass seek_pattern_is_useful to restore the default behavior.

Example

use fancy_regex::{RegexOptionsBuilder, seek_pattern_is_useful};

// Use the default filter (equivalent to seek(true))
let mut builder = RegexOptionsBuilder::new();
builder.seek_filter(seek_pattern_is_useful);

// Use a custom filter that additionally requires the pattern to be longer than 3 bytes
let mut builder = RegexOptionsBuilder::new();
builder.seek_filter(|pat| pat.len() > 3 && seek_pattern_is_useful(pat));

pub fn oniguruma_mode(&mut self, yes: bool) -> &mut Self

Attempts to better match Oniguruma’s default parsing behavior

Currently this amounts to changing behavior with:

Left and right word bounds

fancy-regex follows the default of other regex engines such as the regex crate itself where \< and \> correspond to a left and right word-bound respectively. This differs from Oniguruma’s defaults which treat them as matching the literals < and >. When this option is set using \< and \> in the pattern will match the literals < and > instead of word bounds.

Repetition/Quantifiers on empty groups

fancy-regex would normally reject patterns like (?:)+ because the + has nothing to target. In Oniguruma mode, the empty repeat is silently dropped at parse time.

Swapped order quantifiers

fancy-regex would normally treat x{0,3} as a syntax error because the minimum is greater than the maximum. In Oniguruma mode, the limits are swapped (behaving as x{3,0}) and the resulting repeat is treated as atomic (possessive), matching Oniguruma’s behavior.

Adjacent quantifiers

fancy-regex would normally reject adjacent quantifiers like a{3}{2}, treating the second as having nothing to target. In Oniguruma mode, each quantifier wraps the previous result (e.g. a{3}{2} becomes (?:a{3}){2}).

Outside Oniguruma mode, + after {...} is a possessive modifier (e.g. x{2}+ is possessive). In Oniguruma mode, + after a user-specified {...} repeat is treated as another repeat modifier — x{2}+ is equivalent to (?:x{2})+.

Start of line (^) in multiline mode

In multiline mode ((?m)), ^ normally matches at the start of the input and after any newline. In Oniguruma mode, it additionally rejects a match at the absolute end of the input when it is preceded by a trailing newline. Inside lookarounds, ^ behaves as a plain line start without the end-of-input rejection.

Example

use fancy_regex::{Regex, RegexBuilder};

let haystack = "turbo::<Fish>";
let regex = r"\<\w*\>";

// By default `\<` and `\>` will match the start and end of a word boundary
let word_bounds_regex = Regex::new(regex).unwrap();
let word_bounds = word_bounds_regex.find(haystack).unwrap().unwrap();
assert_eq!(word_bounds.as_str(), "turbo");

// With the option set they instead match the literal `<` and `>` characters
let literals_regex = RegexBuilder::new(regex).oniguruma_mode(true).build().unwrap();
let literals = literals_regex.find(haystack).unwrap().unwrap();
assert_eq!(literals.as_str(), "<Fish>");

pub fn bytes_mode(&mut self, mode: BytesMode) -> &mut Self

Set the input encoding mode for the regex.

Controls how the regex engine handles input encoding. See BytesMode for details on each variant.

Default is BytesMode::Unicode.

Example

use fancy_regex::{BytesMode, RegexBuilder};

// ASCII bytes mode: . matches any byte including non-UTF-8
let re = RegexBuilder::new(r".+")
    .bytes_mode(BytesMode::Ascii)
    .build()
    .unwrap();
assert!(re.is_match(b"\x80\x81\x82").unwrap());

// Default Unicode mode: . only matches valid UTF-8 codepoints
let re = RegexBuilder::new(r".+")
    .build()
    .unwrap();
assert!(!re.is_match(b"\x80\x81\x82").unwrap());

pub fn disallow_empty_match_at_eof_after_newline( &mut self, yes: bool, ) -> &mut Self

Sometimes you want to pass in a haystack containing a trailing newline, and have that last position ignored for the purposes of anchors like ^ and $ and even for lookarounds, unless \z is specifically used to anchor to the end of the string. This is how Oniguruma works for example.

pub fn allow_input_assertion_overrides(&mut self, yes: bool) -> &mut Self

Allow RegexInput assertion suppression overrides at runtime.

When enabled, patterns containing \A and \z are treated as hard and compiled to the VM so that RegexInput::start_text and RegexInput::end_text can suppress those assertions.

When disabled (the default), those runtime overrides are ignored.

Trait Implementations

impl Debug for RegexOptionsBuilder

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

Formats the value using the given formatter.

impl Default for RegexOptionsBuilder

fn default() -> Self

Returns the “default value” for a type.