<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="This crate provides routines for searching strings for matches of a regular expression (aka “regex”). The regex syntax supported by this crate is similar to other regex engines, but it lacks several features that are not known how to implement efficiently. This includes, but is not limited to, look-around and backreferences. In exchange, all regex searches in this crate have worst case `O(m * n)` time complexity, where `m` is proportional to the size of the regex and `n` is proportional to the size of the string being searched."><title>regex - Rust</title><script>if(window.location.protocol!=="file:")document.write(`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2">`)</script><linkrel="stylesheet"href="../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../static.files/rustdoc-e935ef01ae1c1829.css"><metaname="rustdoc-vars"data-root-path="../"data-static-root-path="../static.files/"data-current-crate="regex"data-themes=""data-resource-suffix=""data-rustdoc-version="1.78.0 (9b00956e5 2024-04-29)"data-channel="1.78.0"data-search-js="search-42d8da7a6b9792c2.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../static.files/storage-4c98445ec4002617.js"></script><scriptdefersrc="../crates.js"></script><scriptdefersrc="../static.files/main-12cf3b4f4f9dc36d.js"></script><noscript><linkrel="stylesheet"href="../static.files/noscript-04d5337699b92874.css"></noscript><linkrel="alternate icon"type="image/png"href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><linkrel="alternate icon"type="image/png"href="../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle"title="show sidebar"></button></nav><navclass="sidebar"><divclass="sidebar-crate"><h2><ahref="../regex/index.html">regex</a><spanclass="version">1.10.4</span></h2></div><divclass="sidebar-elems"><ulclass="block">
<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../regex/all.html"title="show sidebar"></a></div><inputclass="search-input"name="search"aria-label="Run search in the documentation"autocomplete="off"spellcheck="false"placeholder="Click or press ‘S’ to search, ‘?’ for more options…"type="search"><divid="help-button"tabindex="-1"><ahref="../help.html"title="help">?</a></div><divid="settings-menu"tabindex="-1"><ahref="../settings.html"title="settings"><imgwidth="22"height="22"alt="Change settings"src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><sectionid="main-content"class="content"><divclass="main-heading"><h1>Crate <aclass="mod"href="#">regex</a><buttonid="copy-path"title="Copy item path to clipboard"><imgsrc="../static.files/clipboard-7571035ce49a181d.svg"width="19"height="18"alt="Copy item path"></button></h1><spanclass="out-of-band"><aclass="src"href="../src/regex/lib.rs.html#1-1346">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>This crate provides routines for searching strings for matches of a <ahref="https://en.wikipedia.org/wiki/Regular_expression">regular
expression</a> (aka “regex”). The regex syntax supported by this crate is similar
to other regex engines, but it lacks several features that are not known how to
implement efficiently. This includes, but is not limited to, look-around and
backreferences. In exchange, all regex searches in this crate have worst case
<code>O(m * n)</code> time complexity, where <code>m</code> is proportional to the size of the regex
and <code>n</code> is proportional to the size of the string being searched.</p>
<p>If you just want API documentation, then skip to the <ahref="struct.Regex.html"title="struct regex::Regex"><code>Regex</code></a> type. Otherwise,
here’s a quick example showing one way of parsing the output of a grep-like
<p>The primary type in this crate is a <ahref="struct.Regex.html"title="struct regex::Regex"><code>Regex</code></a>. Its most important methods are
as follows:</p>
<ul>
<li><ahref="struct.Regex.html#method.new"title="associated function regex::Regex::new"><code>Regex::new</code></a> compiles a regex using the default configuration. A
<ahref="struct.RegexBuilder.html"title="struct regex::RegexBuilder"><code>RegexBuilder</code></a> permits setting a non-default configuration. (For example,
case insensitive matching, verbose mode and others.)</li>
<li><ahref="struct.Regex.html#method.is_match"title="method regex::Regex::is_match"><code>Regex::is_match</code></a> reports whether a match exists in a particular haystack.</li>
<li><ahref="struct.Regex.html#method.find"title="method regex::Regex::find"><code>Regex::find</code></a> reports the byte offsets of a match in a haystack, if one
exists. <ahref="struct.Regex.html#method.find_iter"title="method regex::Regex::find_iter"><code>Regex::find_iter</code></a> returns an iterator over all such matches.</li>
<li><ahref="struct.Regex.html#method.captures"title="method regex::Regex::captures"><code>Regex::captures</code></a> returns a <ahref="struct.Captures.html"title="struct regex::Captures"><code>Captures</code></a>, which reports both the byte
offsets of a match in a haystack and the byte offsets of each matching capture
group from the regex in the haystack.
<ahref="struct.Regex.html#method.captures_iter"title="method regex::Regex::captures_iter"><code>Regex::captures_iter</code></a> returns an iterator over all such matches.</li>
</ul>
<p>There is also a <ahref="struct.RegexSet.html"title="struct regex::RegexSet"><code>RegexSet</code></a>, which permits searching for multiple regex
patterns simultaneously in a single search. However, it currently only reports
which patterns match and <em>not</em> the byte offsets of a match.</p>
<p>Otherwise, this top-level crate documentation is organized as follows:</p>
<ul>
<li><ahref="#usage">Usage</a> shows how to add the <code>regex</code> crate to your Rust project.</li>
<li><ahref="#examples">Examples</a> provides a limited selection of regex search examples.</li>
<li><ahref="#performance">Performance</a> provides a brief summary of how to optimize regex
searching speed.</li>
<li><ahref="#unicode">Unicode</a> discusses support for non-ASCII patterns.</li>
<li><ahref="#syntax">Syntax</a> enumerates the specific regex syntax supported by this
crate.</li>
<li><ahref="#untrusted-input">Untrusted input</a> discusses how this crate deals with regex
patterns or haystacks that are untrusted.</li>
<li><ahref="#crate-features">Crate features</a> documents the Cargo features that can be
enabled or disabled for this crate.</li>
<li><ahref="#other-crates">Other crates</a> links to other crates in the <code>regex</code> family.</li>
<spanclass="macro">println!</span>(<spanclass="string">"The name is: {}"</span>, <spanclass="kw-2">&</span>caps[<spanclass="string">"name"</span>]);
}</code></pre></div>
<p>Fourth, run it with <code>cargo run</code>:</p>
<divclass="example-wrap"><preclass="language-text"><code>$ cargo run
<p>There are a few things worth noticing here in our first example:</p>
<ul>
<li>The <code>.</code> is a special pattern meta character that means “match any single
character except for new lines.” (More precisely, in this crate, it means
“match any UTF-8 encoding of any Unicode scalar value other than <code>\n</code>.”)</li>
<li>We can match an actual <code>.</code> literally by escaping it, i.e., <code>\.</code>.</li>
<li>We use Rust’s <ahref="https://doc.rust-lang.org/stable/reference/tokens.html#raw-string-literals">raw strings</a> to avoid needing to deal with escape sequences in
both the regex pattern syntax and in Rust’s string literal syntax. If we didn’t
use raw strings here, we would have had to use <code>\\.</code> to match a literal <code>.</code>
character. That is, <code>r"\."</code> and <code>"\\."</code> are equivalent patterns.</li>
<li>We put our wildcard <code>.</code> instruction in parentheses. These parentheses have a
special meaning that says, “make whatever part of the haystack matches within
these parentheses available as a capturing group.” After finding a match, we
access this capture group with <code>&caps[1]</code>.</li>
</ul>
<p>Otherwise, we execute a search using <code>re.captures(hay)</code> and return from our
function if no match occurred. We then reference the middle initial by asking
for the part of the haystack that matched the capture group indexed at <code>1</code>.
(The capture group at index 0 is implicit and always corresponds to the entire
match. In this case, that’s <code>Homer J. Simpson</code>.)</p>
<h4id="example-validating-a-particular-date-format"><aclass="doc-anchor"href="#example-validating-a-particular-date-format">§</a>Example: validating a particular date format</h4>
<h4id="example-finding-dates-in-a-haystack"><aclass="doc-anchor"href="#example-finding-dates-in-a-haystack">§</a>Example: finding dates in a haystack</h4>
<p>We can also iterate over <ahref="struct.Captures.html"title="struct regex::Captures"><code>Captures</code></a> values instead of <ahref="struct.Match.html"title="struct regex::Match"><code>Match</code></a> values, and
that in turn permits accessing each component of the date via capturing groups:</p>
<h4id="example-simpler-capture-group-extraction"><aclass="doc-anchor"href="#example-simpler-capture-group-extraction">§</a>Example: simpler capture group extraction</h4>
<p>One can use <ahref="struct.Captures.html#method.extract"title="method regex::Captures::extract"><code>Captures::extract</code></a> to make the code from the previous example a
<h4id="example-replacement-with-named-capture-groups"><aclass="doc-anchor"href="#example-replacement-with-named-capture-groups">§</a>Example: replacement with named capture groups</h4>
<p>Building on the previous example, perhaps we’d like to rearrange the date
formats. This can be done by finding each match and replacing it with
something different. The <ahref="struct.Regex.html#method.replace_all"title="method regex::Regex::replace_all"><code>Regex::replace_all</code></a> routine provides a convenient
way to do this, including by supporting references to named groups in the
<p>When running a search with a regex, there are generally three different types
of information one can ask for:</p>
<ol>
<li>Does a regex match in a haystack?</li>
<li>Where does a regex match in a haystack?</li>
<li>Where do each of the capturing groups match in a haystack?</li>
</ol>
<p>Generally speaking, this crate could provide a function to answer only #3,
which would subsume #1 and #2 automatically. However, it can be significantly
more expensive to compute the location of capturing group matches, so it’s best
not to do it if you don’t need to.</p>
<p>Therefore, only ask for what you need. For example, don’t use <ahref="struct.Regex.html#method.find"title="method regex::Regex::find"><code>Regex::find</code></a>
if you only need to test if a regex matches a haystack. Use <ahref="struct.Regex.html#method.is_match"title="method regex::Regex::is_match"><code>Regex::is_match</code></a>
<h4id="unicode-can-impact-memory-usage-and-search-speed"><aclass="doc-anchor"href="#unicode-can-impact-memory-usage-and-search-speed">§</a>Unicode can impact memory usage and search speed</h4>
<h4id="avoid-re-compiling-regexes-especially-in-a-loop"><aclass="doc-anchor"href="#avoid-re-compiling-regexes-especially-in-a-loop">§</a>Avoid re-compiling regexes, especially in a loop</h4>
<h4id="sharing-a-regex-across-threads-can-result-in-contention"><aclass="doc-anchor"href="#sharing-a-regex-across-threads-can-result-in-contention">§</a>Sharing a regex across threads can result in contention</h4>
<p>This section discusses what kind of Unicode support this regex library has.
Before showing some examples, we’ll summarize the relevant points:</p>
<ul>
<li>This crate almost fully implements “Basic Unicode Support” (Level 1) as
specified by the <ahref="https://unicode.org/reports/tr18/">Unicode Technical Standard #18</a>. The full details
of what is supported are documented in <ahref="https://github.com/rust-lang/regex/blob/master/UNICODE.md">UNICODE.md</a> in the root of the regex
crate repository. There is virtually no support for “Extended Unicode Support”
(Level 2) from UTS#18.</li>
<li>The top-level <ahref="struct.Regex.html"title="struct regex::Regex"><code>Regex</code></a> runs searches <em>as if</em> iterating over each of the
codepoints in the haystack. That is, the fundamental atom of matching is a
single codepoint.</li>
<li><ahref="bytes/struct.Regex.html"title="struct regex::bytes::Regex"><code>bytes::Regex</code></a>, in contrast, permits disabling Unicode mode for part of all
of your pattern in all cases. When Unicode mode is disabled, then a search is
run <em>as if</em> iterating over each byte in the haystack. That is, the fundamental
atom of matching is a single byte. (A top-level <code>Regex</code> also permits disabling
Unicode and thus matching <em>as if</em> it were one byte at a time, but only when
doing so wouldn’t permit matching invalid UTF-8.)</li>
<li>When Unicode mode is enabled (the default), <code>.</code> will match an entire Unicode
scalar value, even when it is encoded using multiple bytes. When Unicode mode
is disabled (e.g., <code>(?-u:.)</code>), then <code>.</code> will match a single byte in all cases.</li>
<li>The character classes <code>\w</code>, <code>\d</code> and <code>\s</code> are all Unicode-aware by default.
Use <code>(?-u:\w)</code>, <code>(?-u:\d)</code> and <code>(?-u:\s)</code> to get their ASCII-only definitions.</li>
<li>Similarly, <code>\b</code> and <code>\B</code> use a Unicode definition of a “word” character.
To get ASCII-only word boundaries, use <code>(?-u:\b)</code> and <code>(?-u:\B)</code>. This also
applies to the special word boundary assertions. (That is, <code>\b{start}</code>,
<p>The <ahref="bytes/struct.Regex.html"title="struct regex::bytes::Regex"><code>bytes::Regex</code></a> type that can be used to search <code>&[u8]</code> haystacks. By
default, haystacks are conventionally treated as UTF-8 just like it is with the
main <code>Regex</code> type. However, this behavior can be disabled by turning off the
<code>u</code> flag, even if doing so could result in matching invalid UTF-8. For example,
when the <code>u</code> flag is disabled, <code>.</code> will match any byte instead of any Unicode
scalar value.</p>
<p>Disabling the <code>u</code> flag is also possible with the standard <code>&str</code>-based <code>Regex</code>
type, but it is only allowed where the UTF-8 invariant is maintained. For
example, <code>(?-u:\w)</code> is an ASCII-only <code>\w</code> character class and is legal in an
<code>&str</code>-based <code>Regex</code>, but <code>(?-u:\W)</code> will attempt to match <em>any byte</em> that
isn’t in <code>(?-u:\w)</code>, which in turn includes bytes that are invalid UTF-8.
Similarly, <code>(?-u:\xFF)</code> will attempt to match the raw byte <code>\xFF</code> (instead of
<code>U+00FF</code>), which is invalid UTF-8 and therefore is illegal in <code>&str</code>-based
regexes.</p>
<p>Finally, since Unicode support requires bundling large Unicode data
tables, this crate exposes knobs to disable the compilation of those
data tables, which can be useful for shrinking binary size and reducing
compilation times. For details on how to do that, see the section on <ahref="#crate-features">crate
\b{end}, \> a Unicode end-of-word boundary (\w on the left, \W|\z on the right))
\b{start-half} half of a Unicode start-of-word boundary (\W|\A on the left)
\b{end-half} half of a Unicode end-of-word boundary (\W|\z on the right)
</pre>
<p>The empty regex is valid and matches the empty string. For example, the
empty regex matches <code>abc</code> at positions <code>0</code>, <code>1</code>, <code>2</code> and <code>3</code>. When using the
top-level <ahref="struct.Regex.html"title="struct regex::Regex"><code>Regex</code></a> on <code>&str</code> haystacks, an empty match that splits a codepoint
is guaranteed to never be returned. However, such matches are permitted when
using a <ahref="bytes/struct.Regex.html"title="struct regex::bytes::Regex"><code>bytes::Regex</code></a>. For example:</p>
<h4id="perl-character-classes-unicode-friendly"><aclass="doc-anchor"href="#perl-character-classes-unicode-friendly">§</a>Perl character classes (Unicode friendly)</h4>
<p>Outside of clearly documented cases, most APIs in this crate are intended to
never panic regardless of the inputs given to them. For example, <code>Regex::new</code>,
<code>Regex::is_match</code>, <code>Regex::find</code> and <code>Regex::captures</code> should never panic. That
is, it is an API promise that those APIs will never panic no matter what inputs
are given to them. With that said, regex engines are complicated beasts, and
providing a rock solid guarantee that these APIs literally never panic is
essentially equivalent to saying, “there are no bugs in this library.” That is
a bold claim, and not really one that can be feasibly made with a straight
face.</p>
<p>Don’t get the wrong impression here. This crate is extensively tested, not just
with unit and integration tests, but also via fuzz testing. For example, this
crate is part of the <ahref="https://android.googlesource.com/platform/external/oss-fuzz/+/refs/tags/android-t-preview-1/projects/rust-regex/">OSS-fuzz project</a>. Panics should be incredibly rare, but
it is possible for bugs to exist, and thus possible for a panic to occur. If
you need a rock solid guarantee against panics, then you should wrap calls into
this library with <ahref="https://doc.rust-lang.org/std/panic/fn.catch_unwind.html"><code>std::panic::catch_unwind</code></a>.</p>
<p>It’s also worth pointing out that this library will <em>generally</em> panic when
other regex engines would commit undefined behavior. When undefined behavior
occurs, your program might continue as if nothing bad has happened, but it also
might mean your program is open to the worst kinds of exploits. In contrast,
the worst thing a panic can do is a denial of service.</p>
<p>The principal way this crate deals with them is by limiting their size by
default. The size limit can be configured via <ahref="struct.RegexBuilder.html#method.size_limit"title="method regex::RegexBuilder::size_limit"><code>RegexBuilder::size_limit</code></a>. The
idea of a size limit is that compiling a pattern into a <code>Regex</code> will fail if it
becomes “too big.” Namely, while <em>most</em> resources consumed by compiling a regex
are approximately proportional (albeit with some high constant factors in some
cases, such as with Unicode character classes) to the length of the pattern
itself, there is one particular exception to this: counted repetitions. Namely,
<p>In both of these cases, the actual pattern string is quite small, but the
resulting <code>Regex</code> value is quite large. Indeed, as the first pattern shows,
it isn’t enough to locally limit the size of each repetition because they can
be stacked in a way that results in exponential growth.</p>
<p>To provide a bit more context, a simplified view of regex compilation looks
like this:</p>
<ul>
<li>The pattern string is parsed into a structured representation called an AST.
Counted repetitions are not expanded and Unicode character classes are not
looked up in this stage. That is, the size of the AST is proportional to the
size of the pattern with “reasonable” constant factors. In other words, one
can reasonably limit the memory used by an AST by limiting the length of the
pattern string.</li>
<li>The AST is translated into an HIR. Counted repetitions are still <em>not</em>
expanded at this stage, but Unicode character classes are embedded into the
HIR. The memory usage of a HIR is still proportional to the length of the
original pattern string, but the constant factors—mostly as a result of
Unicode character classes—can be quite high. Still though, the memory used by
an HIR can be reasonably limited by limiting the length of the pattern string.</li>
<li>The HIR is compiled into a <ahref="https://en.wikipedia.org/wiki/Thompson%27s_construction">Thompson NFA</a>. This is the stage at which
something like <code>\w{5}</code> is rewritten to <code>\w\w\w\w\w</code>. Thus, this is the stage
at which <ahref="struct.RegexBuilder.html#method.size_limit"title="method regex::RegexBuilder::size_limit"><code>RegexBuilder::size_limit</code></a> is enforced. If the NFA exceeds the
configured size, then this stage will fail.</li>
</ul>
<p>The size limit helps avoid two different kinds of exorbitant resource usage:</p>
<ul>
<li>It avoids permitting exponential memory usage based on the size of the
pattern string.</li>
<li>It avoids long search times. This will be discussed in more detail in the
next section, but worst case search time <em>is</em> dependent on the size of the
regex. So keeping regexes limited to a reasonable size is also a way of keeping
search times reasonable.</li>
</ul>
<p>Finally, it’s worth pointing out that regex compilation is guaranteed to take
worst case <code>O(m)</code> time, where <code>m</code> is proportional to the size of regex. The
size of the regex here is <em>after</em> the counted repetitions have been expanded.</p>
<p><strong>Advice for those using untrusted regexes</strong>: limit the pattern length to
something small and expand it as needed. Configure <ahref="struct.RegexBuilder.html#method.size_limit"title="method regex::RegexBuilder::size_limit"><code>RegexBuilder::size_limit</code></a>
to something small and then expand it as needed.</p>
<p>One thing that is perhaps easy to miss is that the worst case time
complexity bound of <code>O(m * n)</code> applies to methods like <ahref="struct.Regex.html#method.is_match"title="method regex::Regex::is_match"><code>Regex::is_match</code></a>,
<ahref="struct.Regex.html#method.find"title="method regex::Regex::find"><code>Regex::find</code></a> and <ahref="struct.Regex.html#method.captures"title="method regex::Regex::captures"><code>Regex::captures</code></a>. It does <strong>not</strong> apply to
<ahref="struct.Regex.html#method.find_iter"title="method regex::Regex::find_iter"><code>Regex::find_iter</code></a> or <ahref="struct.Regex.html#method.captures_iter"title="method regex::Regex::captures_iter"><code>Regex::captures_iter</code></a>. Namely, since iterating over
all matches can execute many searches, and each search can scan the entire
haystack, the worst case time complexity for iterators is <code>O(m * n^2)</code>.</p>
<p>One example of where this occurs is when a pattern consists of an alternation,
where an earlier branch of the alternation requires scanning the entire
haystack only to discover that there is no match. It also requires a later
branch of the alternation to have matched at the beginning of the search. For
example, consider the pattern <code>.*[^A-Z]|[A-Z]</code> and the haystack <code>AAAAA</code>. The
first search will scan to the end looking for matches of <code>.*[^A-Z]</code> even though
a finite automata engine (as in this crate) knows that <code>[A-Z]</code> has already
matched the first character of the haystack. This is due to the greedy nature
of regex searching. That first search will report a match at the first <code>A</code> only
after scanning to the end to discover that no other match exists. The next
search then begins at the second <code>A</code> and the behavior repeats.</p>
<p>There is no way to avoid this. This means that if both patterns and haystacks
are untrusted and you’re iterating over all matches, you’re susceptible to
worst case quadratic time complexity. One possible way to mitigate this
is to drop down to the lower level <code>regex-automata</code> crate and use its
<code>meta::Regex</code> iterator APIs. There, you can configure the search to operate
in “earliest” mode by passing a <code>Input::new(haystack).earliest(true)</code> to
<code>meta::Regex::find_iter</code> (for example). By enabling this mode, you give up
the normal greedy match semantics of regex searches and instead ask the regex
engine to immediately stop as soon as a match has been found. Enabling this
mode will thus restore the worst case <code>O(m * n)</code> time complexity bound, but at
<p>While providing a <code>O(m * n)</code> worst case time bound on all searches goes a long
way toward preventing <ahref="https://en.wikipedia.org/wiki/ReDoS">ReDoS</a>, that doesn’t mean every search you can possibly
run will complete without burning CPU time. In general, there are a few ways
for the <code>m * n</code> time bound to still bite you:</p>
<ul>
<li>You are searching an exceptionally long haystack. No matter how you slice
it, a longer haystack will take more time to search. This crate may often make
very quick work of even long haystacks because of its literal optimizations,
but those aren’t available for all regexes.</li>
<li>Unicode character classes can cause searches to be quite slow in some cases.
This is especially true when they are combined with counted repetitions. While
the regex size limit above will protect you from the most egregious cases,
the default size limit still permits pretty big regexes that can execute more
slowly than one might expect.</li>
<li>While routines like <ahref="struct.Regex.html#method.find"title="method regex::Regex::find"><code>Regex::find</code></a> and <ahref="struct.Regex.html#method.captures"title="method regex::Regex::captures"><code>Regex::captures</code></a> guarantee
worst case <code>O(m * n)</code> search time, routines like <ahref="struct.Regex.html#method.find_iter"title="method regex::Regex::find_iter"><code>Regex::find_iter</code></a> and
<ahref="struct.Regex.html#method.captures_iter"title="method regex::Regex::captures_iter"><code>Regex::captures_iter</code></a> actually have worst case <code>O(m * n^2)</code> search time.
This is because <code>find_iter</code> runs many searches, and each search takes worst
case <code>O(m * n)</code> time. Thus, iteration of all matches in a haystack has
worst case <code>O(m * n^2)</code>. A good example of a pattern that exhibits this is
<code>(?:A+){1000}|</code> or even <code>.*[^A-Z]|[A-Z]</code>.</li>
</ul>
<p>In general, unstrusted haystacks are easier to stomach than untrusted patterns.
Untrusted patterns give a lot more control to the caller to impact the
performance of a search. In many cases, a regex search will actually execute in
average case <code>O(n)</code> time (i.e., not dependent on the size of the regex), but
this can’t be guaranteed in general. Therefore, permitting untrusted patterns
means that your only line of defense is to put a limit on how big <code>m</code> (and
perhaps also <code>n</code>) can be in <code>O(m * n)</code>. <code>n</code> is limited by simply inspecting
the length of the haystack while <code>m</code> is limited by <em>both</em> applying a limit to
the length of the pattern <em>and</em> a limit on the compiled size of the regex via
</div></details><h2id="modules"class="section-header">Modules<ahref="#modules"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="mod"href="bytes/index.html"title="mod regex::bytes">bytes</a></div><divclass="desc docblock-short">Search for regex matches in <code>&[u8]</code> haystacks.</div></li></ul><h2id="structs"class="section-header">Structs<ahref="#structs"class="anchor">§</a></h2><ulclass="item-table"><li><divclass="item-name"><aclass="struct"href="struct.CaptureLocations.html"title="struct regex::CaptureLocations">CaptureLocations</a></div><divclass="desc docblock-short">A low level representation of the byte offsets of each capture group.</div></li><li><divclass="item-name"><aclass="struct"href="struct.CaptureMatches.html"title="struct regex::CaptureMatches">CaptureMatches</a></div><divclass="desc docblock-short">An iterator over all non-overlapping capture matches in a haystack.</div></li><li><divclass="item-name"><aclass="struct"href="struct.CaptureNames.html"title="struct regex::CaptureNames">CaptureNames</a></div><divclass="desc docblock-short">An iterator over the names of all capture groups in a regex.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Captures.html"title="struct regex::Captures">Captures</a></div><divclass="desc docblock-short">Represents the capture groups for a single match.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Match.html"title="struct regex::Match">Match</a></div><divclass="desc docblock-short">Represents a single match of a regex in a haystack.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Matches.html"title="struct regex::Matches">Matches</a></div><divclass="desc docblock-short">An iterator over all non-overlapping matches in a haystack.</div></li><li><divclass="item-name"><aclass="struct"href="struct.NoExpand.html"title="struct regex::NoExpand">NoExpand</a></div><divclass="desc docblock-short">A helper type for forcing literal string replacement.</div></li><li><divclass="item-name"><aclass="struct"href="struct.Regex.html"title="struct regex::Regex">Regex</a></div><divclass="desc docblock-short">A compiled regular expression for searching Unicode haystacks.</div></li><li><divclass="item-name"><aclass="struct"href="struct.RegexBuilder.html"title="struct regex::RegexBuilder">RegexBuilder</a></div><divclass="desc docblock-short">A configurable builder for a <ahref="struct.Regex.html"title="struct regex::Regex"><code>Regex</code></a>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.RegexSet.html"title="struct regex::RegexSet">RegexSet</a></div><divclass="desc docblock-short">Match multiple, possibly overlapping, regexes in a single search.</div></li><li><divclass="item-name"><aclass="struct"href="struct.RegexSetBuilder.html"title="struct regex::RegexSetBuilder">RegexSetBuilder</a></div><divclass="desc docblock-short">A configurable builder for a <ahref="struct.RegexSet.html"title="struct regex::RegexSet"><code>RegexSet</code></a>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.ReplacerRef.html"title="struct regex::ReplacerRef">ReplacerRef</a></div><divclass="desc docblock-short">A by-reference adaptor for a <ahref="trait.Replacer.html"title="trait regex::Replacer"><code>Replacer</code></a>.</div></li><li><divclass="item-name"><aclass="struct"href="struct.SetMatches.html"title="struct regex::SetMatches">SetMatches</a></div><divclass="desc docblock-short">A set of matches returned by a regex set.</div></li><li><divclass="item-name"><aclass="struct"href="struct.SetMatchesIntoIter.html"title="struct regex::SetMatchesIntoIter">SetMatchesIntoIter</a></div><divclass="desc docblock-short">An owned iterator over the set of matches from a regex set.</div></li><li><divclass="item-name"><aclass="struct"href="struct.SetMatchesIter.html"title="struct regex::SetMatchesIter">SetMatchesIter</a></div><divclass="desc docblock-short">A borrowed iterator over the set of matches from a
