A configurable builder for a regular expression.
A builder can be used to configure how the regex is built, for example, by setting the default flags (which can be overridden in the expression itself) or setting various limits.
pub fn new(pattern: &str) -> RegexBuilder[src]
Create a new regular expression builder with the given pattern.
If the pattern is invalid, then an error will be returned when
build is called.
Consume the builder and compile the regular expression.
Note that calling
as_str on the resulting
Regex will produce the
pattern given to
new verbatim. Notably, it will not incorporate any
of the flags set on this builder.
pub fn case_insensitive(&mut self, yes: bool) -> &mut RegexBuilder[src]
Set the value for the case insensitive (
When enabled, letters in the pattern will match both upper case and lower case variants.
pub fn multi_line(&mut self, yes: bool) -> &mut RegexBuilder[src]
Set the value for the multi-line matching (
^ matches the beginning of lines and
$ matches the
end of lines.
By default, they match beginning/end of the input.
pub fn dot_matches_new_line(&mut self, yes: bool) -> &mut RegexBuilder[src]
Set the value for the any character (
s) flag, where in
s is set and matches anything except for new line when
it is not set (the default).
N.B. "matches anything" means "any byte" when Unicode is disabled and means "any valid UTF-8 encoding of any Unicode scalar value" when Unicode is enabled.
pub fn swap_greed(&mut self, yes: bool) -> &mut RegexBuilder[src]
Set the value for the greedy swap (
When enabled, a pattern like
a* is lazy (tries to find shortest
a*? is greedy (tries to find longest match).
a* is greedy and
a*? is lazy.
pub fn ignore_whitespace(&mut self, yes: bool) -> &mut RegexBuilder[src]
Set the value for the ignore whitespace (
When enabled, whitespace such as new lines and spaces will be ignored
between expressions of the pattern, and
# can be used to start a
comment until the next new line.
pub fn unicode(&mut self, yes: bool) -> &mut RegexBuilder[src]
Set the value for the Unicode (
Enabled by default. When disabled, character classes such as
match ASCII word characters instead of all Unicode word characters.
pub fn octal(&mut self, yes: bool) -> &mut RegexBuilder[src]
Whether to support octal syntax or not.
Octal syntax is a little-known way of uttering Unicode codepoints in
a regular expression. For example,
\141 are all equivalent regular expressions, where the last example
shows octal syntax.
While supporting octal syntax isn't in and of itself a problem, it does
make good error messages harder. That is, in PCRE based regex engines,
\0 invokes a backreference, which is explicitly
unsupported in Rust's regex engine. However, many users expect it to
be supported. Therefore, when octal support is disabled, the error
message will explicitly mention that backreferences aren't supported.
Octal syntax is disabled by default.
pub fn size_limit(&mut self, limit: usize) -> &mut RegexBuilder[src]
Set the approximate size limit of the compiled regular expression.
This roughly corresponds to the number of bytes occupied by a single compiled program. If the program exceeds this number, then a compilation error is returned.
pub fn dfa_size_limit(&mut self, limit: usize) -> &mut RegexBuilder[src]
Set the approximate size of the cache used by the DFA.
This roughly corresponds to the number of bytes that the DFA will use while searching.
Note that this is a per thread limit. There is no way to set a global limit. In particular, if a regex is used from multiple threads simultaneously, then each thread may use up to the number of bytes specified here.
pub fn nest_limit(&mut self, limit: u32) -> &mut RegexBuilder[src]
Set the nesting limit for this 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 for consumers that do structural induction on an
explicit recursion. While this crate never does this (instead using
constant stack space and moving the call stack to the heap), other
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 this parser implementation will limit itself to heap space proportional to the length 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
ab requires a concatenation, which results in a nest
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.
impl RefUnwindSafe for RegexBuilder
impl Send for RegexBuilder
impl Sync for RegexBuilder
impl Unpin for RegexBuilder
impl UnwindSafe for RegexBuilder
type Error = Infallible
The type returned in the event of a conversion error.