edg-l/edlang
1
1
Fork 0
mirror of https://github.com/edg-l/edlang.git synced 2024-11-23 08:28:24 +00:00
Code Issues Packages Projects Releases Wiki Activity
edlang/regex_automata/meta/struct.Regex.html

1273 lines
154 KiB
HTML
Raw Normal View History

deploy: 4a83cfd6f9c58b14a87234162281aad1aef83c3e
2024-02-13 06:38:44 +00:00
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="A regex matcher that works by composing several other regex matchers automatically."><title>Regex in regex_automata::meta - Rust</title><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"><link rel="stylesheet" href="../../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../../static.files/rustdoc-ac92e1bbe349e143.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="regex_automata" data-themes="" data-resource-suffix="" data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)" data-channel="1.76.0" data-search-js="search-2b6ce74ff89ae146.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../../static.files/storage-f2adc0d6ca4d09fb.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../static.files/main-305769736d49e732.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-feafe1bb7466e4bd.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc struct"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../regex_automata/index.html">regex_automata</a><span class="version">0.4.5</span></h2></div><h2 class="location"><a href="#">Regex</a></h2><div class="sidebar-elems"><section><h3><a href="#implementations">Methods</a></h3><ul class="block method"><li><a href="#method.builder">builder</a></li><li><a href="#method.captures">captures</a></li><li><a href="#method.captures_iter">captures_iter</a></li><li><a href="#method.captures_len">captures_len</a></li><li><a href="#method.config">config</a></li><li><a href="#method.create_cache">create_cache</a></li><li><a href="#method.create_captures">create_captures</a></li><li><a href="#method.find">find</a></li><li><a href="#method.find_iter">find_iter</a></li><li><a href="#method.get_config">get_config</a></li><li><a href="#method.group_info">group_info</a></li><li><a href="#method.is_accelerated">is_accelerated</a></li><li><a href="#method.is_match">is_match</a></li><li><a href="#method.memory_usage">memory_usage</a></li><li><a href="#method.new">new</a></li><li><a href="#method.new_many">new_many</a></li><li><a href="#method.pattern_len">pattern_len</a></li><li><a href="#method.search">search</a></li><li><a href="#method.search_captures">search_captures</a></li><li><a href="#method.search_captures_with">search_captures_with</a></li><li><a href="#method.search_half">search_half</a></li><li><a href="#method.search_half_with">search_half_with</a></li><li><a href="#method.search_slots">search_slots</a></li><li><a href="#method.search_slots_with">search_slots_with</a></li><li><a href="#method.search_with">search_with</a></li><li><a href="#method.split">split</a></li><li><a href="#method.splitn">splitn</a></li><li><a href="#method.
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../../regex_automata/all.html" title="show sidebar"></a></div><input class="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"><div id="help-button" tabindex="-1"><a href="../../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Struct <a href="../index.html">regex_automata</a>::<wbr><a href="index.html">meta</a>::<wbr><a class="struct" href="#">Regex</a><button id="copy-path" title="Copy item path to clipboard"><img src="../../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../../src/regex_automata/meta/regex.rs.html#235-252">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><pre class="rust item-decl"><code>pub struct Regex { <span class="comment">/* private fields */</span> }</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>A regex matcher that works by composing several other regex matchers
automatically.</p>
<p>In effect, a meta regex papers over a lot of the quirks or performance
problems in each of the regex engines in this crate. Its goal is to provide
an infallible and simple API that “just does the right thing” in the common
case.</p>
<p>A meta regex is the implementation of a <code>Regex</code> in the <code>regex</code> crate.
Indeed, the <code>regex</code> crate API is essentially just a light wrapper over
this type. This includes the <code>regex</code> crate’s <code>RegexSet</code> API!</p>
<h2 id="composition"><a href="#composition">Composition</a></h2>
<p>This is called a “meta” matcher precisely because it uses other regex
matchers to provide a convenient high level regex API. Here are some
examples of how other regex matchers are composed:</p>
<ul>
<li>When calling <a href="struct.Regex.html#method.captures" title="method regex_automata::meta::Regex::captures"><code>Regex::captures</code></a>, instead of immediately
running a slower but more capable regex engine like the
<a href="../nfa/thompson/pikevm/struct.PikeVM.html" title="struct regex_automata::nfa::thompson::pikevm::PikeVM"><code>PikeVM</code></a>, the meta regex engine
will usually first look for the bounds of a match with a higher throughput
regex engine like a <a href="crate::hybrid">lazy DFA</a>. Only when a match is found
is a slower engine like <code>PikeVM</code> used to find the matching span for each
capture group.</li>
<li>While higher throughout engines like the lazy DFA cannot handle
Unicode word boundaries in general, they can still be used on pure ASCII
haystacks by pretending that Unicode word boundaries are just plain ASCII
word boundaries. However, if a haystack is not ASCII, the meta regex engine
will automatically switch to a (possibly slower) regex engine that supports
Unicode word boundaries in general.</li>
<li>In some cases where a regex pattern is just a simple literal or a small
set of literals, an actual regex engine won’t be used at all. Instead,
substring or multi-substring search algorithms will be employed.</li>
</ul>
<p>There are many other forms of composition happening too, but the above
should give a general idea. In particular, it may perhaps be surprising
that <em>multiple</em> regex engines might get executed for a single search. That
is, the decision of what regex engine to use is not <em>just</em> based on the
pattern, but also based on the dynamic execution of the search itself.</p>
<p>The primary reason for this composition is performance. The fundamental
tension is that the faster engines tend to be less capable, and the more
capable engines tend to be slower.</p>
<p>Note that the forms of composition that are allowed are determined by
compile time crate features and configuration. For example, if the <code>hybrid</code>
feature isn’t enabled, or if <a href="struct.Config.html#method.hybrid" title="method regex_automata::meta::Config::hybrid"><code>Config::hybrid</code></a> has been disabled, then the
meta regex engine will never use a lazy DFA.</p>
<h2 id="synchronization-and-cloning"><a href="#synchronization-and-cloning">Synchronization and cloning</a></h2>
<p>Most of the regex engines in this crate require some kind of mutable
“scratch” space to read and write from while performing a search. Since
a meta regex composes these regex engines, a meta regex also requires
mutable scratch space. This scratch space is called a <a href="struct.Cache.html" title="struct regex_automata::meta::Cache"><code>Cache</code></a>.</p>
<p>Most regex engines <em>also</em> usually have a read-only component, typically
a <a href="../nfa/thompson/struct.NFA.html" title="struct regex_automata::nfa::thompson::NFA">Thompson <code>NFA</code></a>.</p>
<p>In order to make the <code>Regex</code> API convenient, most of the routines hide
the fact that a <code>Cache</code> is needed at all. To achieve this, a <a href="../util/pool/struct.Pool.html" title="struct regex_automata::util::pool::Pool">memory
pool</a> is used internally to retrieve <code>Cache</code>
values in a thread safe way that also permits reuse. This in turn implies
that every such search call requires some form of synchronization. Usually
this synchronization is fast enough to not notice, but in some cases, it
can be a bottleneck. This typically occurs when all of the following are
true:</p>
<ul>
<li>The same <code>Regex</code> is shared across multiple threads simultaneously,
usually via a <a href="../util/lazy/struct.Lazy.html" title="struct regex_automata::util::lazy::Lazy"><code>util::lazy::Lazy</code></a> or something
similar from the <code>once_cell</code> or <code>lazy_static</code> crates.</li>
<li>The primary unit of work in each thread is a regex search.</li>
<li>Searches are run on very short haystacks.</li>
</ul>
<p>This particular case can lead to high contention on the pool used by a
<code>Regex</code> internally, which can in turn increase latency to a noticeable
effect. This cost can be mitigated in one of the following ways:</p>
<ul>
<li>Use a distinct copy of a <code>Regex</code> in each thread, usually by cloning it.
Cloning a <code>Regex</code> <em>does not</em> do a deep copy of its read-only component.
But it does lead to each <code>Regex</code> having its own memory pool, which in
turn eliminates the problem of contention. In general, this technique should
not result in any additional memory usage when compared to sharing the same
<code>Regex</code> across multiple threads simultaneously.</li>
<li>Use lower level APIs, like <a href="struct.Regex.html#method.search_with" title="method regex_automata::meta::Regex::search_with"><code>Regex::search_with</code></a>, which permit passing
a <code>Cache</code> explicitly. In this case, it is up to you to determine how best
to provide a <code>Cache</code>. For example, you might put a <code>Cache</code> in thread-local
storage if your use case allows for it.</li>
</ul>
<p>Overall, this is an issue that happens rarely in practice, but it can
happen.</p>
<h2 id="warning-spin-locks-may-be-used-in-alloc-only-mode"><a href="#warning-spin-locks-may-be-used-in-alloc-only-mode">Warning: spin-locks may be used in alloc-only mode</a></h2>
<p>When this crate is built without the <code>std</code> feature and the high level APIs
on a <code>Regex</code> are used, then a spin-lock will be used to synchronize access
to an internal pool of <code>Cache</code> values. This may be undesirable because
a spin-lock is <a href="https://matklad.github.io/2020/01/02/spinlocks-considered-harmful.html">effectively impossible to implement correctly in user
space</a>. That is, more concretely, the spin-lock could
result in a deadlock.</p>
<p>If one wants to avoid the use of spin-locks when the <code>std</code> feature is
disabled, then you must use APIs that accept a <code>Cache</code> value explicitly.
For example, <a href="struct.Regex.html#method.search_with" title="method regex_automata::meta::Regex::search_with"><code>Regex::search_with</code></a>.</p>
<h2 id="example"><a href="#example">Example</a></h2>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r"^[0-9]{4}-[0-9]{2}-[0-9]{2}$"</span>)<span class="question-mark">?</span>;
<span class="macro">assert!</span>(re.is_match(<span class="string">"2010-03-14"</span>));
</code></pre></div>
<h2 id="example-anchored-search"><a href="#example-anchored-search">Example: anchored search</a></h2>
<p>This example shows how to use <a href="../struct.Input.html#method.anchored" title="method regex_automata::Input::anchored"><code>Input::anchored</code></a> to run an anchored
search, even when the regex pattern itself isn’t anchored. An anchored
search guarantees that if a match is found, then the start offset of the
match corresponds to the offset at which the search was started.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Anchored, Input, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">r"\bfoo\b"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>input = Input::new(<span class="string">"xx foo xx"</span>).range(<span class="number">3</span>..).anchored(Anchored::Yes);
<span class="comment">// The offsets are in terms of the original haystack.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">3</span>..<span class="number">6</span>)), re.find(input));
<span class="comment">// Notice that no match occurs here, because \b still takes the
// surrounding context into account, even if it means looking back
// before the start of your search.
</span><span class="kw">let </span>hay = <span class="string">"xxfoo xx"</span>;
<span class="kw">let </span>input = Input::new(hay).range(<span class="number">2</span>..).anchored(Anchored::Yes);
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, re.find(input));
<span class="comment">// Indeed, you cannot achieve the above by simply slicing the
// haystack itself, since the regex engine can't see the
// surrounding context. This is why 'Input' permits setting
// the bounds of a search!
</span><span class="kw">let </span>input = Input::new(<span class="kw-2">&amp;</span>hay[<span class="number">2</span>..]).anchored(Anchored::Yes);
<span class="comment">// WRONG!
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">3</span>)), re.find(input));
</code></pre></div>
<h2 id="example-earliest-search"><a href="#example-earliest-search">Example: earliest search</a></h2>
<p>This example shows how to use <a href="../struct.Input.html#method.earliest" title="method regex_automata::Input::earliest"><code>Input::earliest</code></a> to run a search that
might stop before finding the typical leftmost match.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Anchored, Input, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">r"[a-z]{3}|b"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>input = Input::new(<span class="string">"abc"</span>).earliest(<span class="bool-val">true</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">1</span>..<span class="number">2</span>)), re.find(input));
<span class="comment">// Note that "earliest" isn't really a match semantic unto itself.
// Instead, it is merely an instruction to whatever regex engine
// gets used internally to quit as soon as it can. For example,
// this regex uses a different search technique, and winds up
// producing a different (but valid) match!
</span><span class="kw">let </span>re = Regex::new(<span class="string">r"abc|b"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>input = Input::new(<span class="string">"abc"</span>).earliest(<span class="bool-val">true</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">3</span>)), re.find(input));
</code></pre></div>
<h2 id="example-change-the-line-terminator"><a href="#example-change-the-line-terminator">Example: change the line terminator</a></h2>
<p>This example shows how to enable multi-line mode by default and change
the line terminator to the NUL byte:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, util::syntax, Match};
<span class="kw">let </span>re = Regex::builder()
.syntax(syntax::Config::new().multi_line(<span class="bool-val">true</span>))
.configure(Regex::config().line_terminator(<span class="string">b'\x00'</span>))
.build(<span class="string">r"^foo$"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"\x00foo\x00"</span>;
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">1</span>..<span class="number">4</span>)), re.find(hay));
</code></pre></div>
</div></details><h2 id="implementations" class="section-header">Implementations<a href="#implementations" class="anchor">§</a></h2><div id="implementations-list"><details class="toggle implementors-toggle" open><summary><section id="impl-Regex" class="impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#281-450">source</a><a href="#impl-Regex" class="anchor">§</a><h3 class="code-header">impl <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section></summary><div class="docblock"><p>Convenience constructors for a <code>Regex</code> using the default configuration.</p>
</div><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.new" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#302-304">source</a><h4 class="code-header">pub fn <a href="#method.new" class="fn">new</a>(pattern: &amp;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.str.html">str</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a>, <a class="struct" href="struct.BuildError.html" title="struct regex_automata::meta::BuildError">BuildError</a>&gt;</h4></section></summary><div class="docblock"><p>Builds a <code>Regex</code> from a single pattern string using the default
configuration.</p>
<p>If there was a problem parsing the pattern or a problem turning it into
a regex matcher, then an error is returned.</p>
<p>If you want to change the configuration of a <code>Regex</code>, use a <a href="struct.Builder.html" title="struct regex_automata::meta::Builder"><code>Builder</code></a>
with a <a href="struct.Config.html" title="struct regex_automata::meta::Config"><code>Config</code></a>.</p>
<h5 id="example-1"><a href="#example-1">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">r"(?Rm)^foo$"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"\r\nfoo\r\n"</span>;
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">2</span>..<span class="number">5</span>)), re.find(hay));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.new_many" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#393-397">source</a><h4 class="code-header">pub fn <a href="#method.new_many" class="fn">new_many</a>&lt;P: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.str.html">str</a>&gt;&gt;(patterns: &amp;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.slice.html">[P]</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a>, <a class="struct" href="struct.BuildError.html" title="struct regex_automata::meta::BuildError">BuildError</a>&gt;</h4></section></summary><div class="docblock"><p>Builds a <code>Regex</code> from many pattern strings using the default
configuration.</p>
<p>If there was a problem parsing any of the patterns or a problem turning
them into a regex matcher, then an error is returned.</p>
<p>If you want to change the configuration of a <code>Regex</code>, use a <a href="struct.Builder.html" title="struct regex_automata::meta::Builder"><code>Builder</code></a>
with a <a href="struct.Config.html" title="struct regex_automata::meta::Config"><code>Config</code></a>.</p>
<h5 id="example-simple-lexer"><a href="#example-simple-lexer">Example: simple lexer</a></h5>
<p>This simplistic example leverages the multi-pattern support to build a
simple little lexer. The pattern ID in the match tells you which regex
matched, which in turn might be used to map back to the “type” of the
token returned by the lexer.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Match};
<span class="kw">let </span>re = Regex::new_many(<span class="kw-2">&amp;</span>[
<span class="string">r"[[:space:]]"</span>,
<span class="string">r"[A-Za-z0-9][A-Za-z0-9_]+"</span>,
<span class="string">r"-&gt;"</span>,
<span class="string">r"."</span>,
])<span class="question-mark">?</span>;
<span class="kw">let </span>haystack = <span class="string">"fn is_boss(bruce: i32, springsteen: String) -&gt; bool;"</span>;
<span class="kw">let </span>matches: Vec&lt;Match&gt; = re.find_iter(haystack).collect();
<span class="macro">assert_eq!</span>(matches, <span class="macro">vec!</span>[
Match::must(<span class="number">1</span>, <span class="number">0</span>..<span class="number">2</span>), <span class="comment">// 'fn'
</span>Match::must(<span class="number">0</span>, <span class="number">2</span>..<span class="number">3</span>), <span class="comment">// ' '
</span>Match::must(<span class="number">1</span>, <span class="number">3</span>..<span class="number">10</span>), <span class="comment">// 'is_boss'
</span>Match::must(<span class="number">3</span>, <span class="number">10</span>..<span class="number">11</span>), <span class="comment">// '('
</span>Match::must(<span class="number">1</span>, <span class="number">11</span>..<span class="number">16</span>), <span class="comment">// 'bruce'
</span>Match::must(<span class="number">3</span>, <span class="number">16</span>..<span class="number">17</span>), <span class="comment">// ':'
</span>Match::must(<span class="number">0</span>, <span class="number">17</span>..<span class="number">18</span>), <span class="comment">// ' '
</span>Match::must(<span class="number">1</span>, <span class="number">18</span>..<span class="number">21</span>), <span class="comment">// 'i32'
</span>Match::must(<span class="number">3</span>, <span class="number">21</span>..<span class="number">22</span>), <span class="comment">// ','
</span>Match::must(<span class="number">0</span>, <span class="number">22</span>..<span class="number">23</span>), <span class="comment">// ' '
</span>Match::must(<span class="number">1</span>, <span class="number">23</span>..<span class="number">34</span>), <span class="comment">// 'springsteen'
</span>Match::must(<span class="number">3</span>, <span class="number">34</span>..<span class="number">35</span>), <span class="comment">// ':'
</span>Match::must(<span class="number">0</span>, <span class="number">35</span>..<span class="number">36</span>), <span class="comment">// ' '
</span>Match::must(<span class="number">1</span>, <span class="number">36</span>..<span class="number">42</span>), <span class="comment">// 'String'
</span>Match::must(<span class="number">3</span>, <span class="number">42</span>..<span class="number">43</span>), <span class="comment">// ')'
</span>Match::must(<span class="number">0</span>, <span class="number">43</span>..<span class="number">44</span>), <span class="comment">// ' '
</span>Match::must(<span class="number">2</span>, <span class="number">44</span>..<span class="number">46</span>), <span class="comment">// '-&gt;'
</span>Match::must(<span class="number">0</span>, <span class="number">46</span>..<span class="number">47</span>), <span class="comment">// ' '
</span>Match::must(<span class="number">1</span>, <span class="number">47</span>..<span class="number">51</span>), <span class="comment">// 'bool'
</span>Match::must(<span class="number">3</span>, <span class="number">51</span>..<span class="number">52</span>), <span class="comment">// ';'
</span>]);
</code></pre></div>
<p>One can write a lexer like the above using a regex like
<code>(?P&lt;space&gt;[[:space:]])|(?P&lt;ident&gt;[A-Za-z0-9][A-Za-z0-9_]+)|...</code>,
but then you need to ask whether capture group matched to determine
which branch in the regex matched, and thus, which token the match
corresponds to. In contrast, the above example includes the pattern ID
in the match. There’s no need to use capture groups at all.</p>
<h5 id="example-finding-the-pattern-that-caused-an-error"><a href="#example-finding-the-pattern-that-caused-an-error">Example: finding the pattern that caused an error</a></h5>
<p>When a syntax error occurs, it is possible to ask which pattern
caused the syntax error.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, PatternID};
<span class="kw">let </span>err = Regex::new_many(<span class="kw-2">&amp;</span>[<span class="string">"a"</span>, <span class="string">"b"</span>, <span class="string">r"\p{Foo}"</span>, <span class="string">"c"</span>]).unwrap_err();
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(PatternID::must(<span class="number">2</span>)), err.pattern());</code></pre></div>
<h5 id="example-zero-patterns-is-valid"><a href="#example-zero-patterns-is-valid">Example: zero patterns is valid</a></h5>
<p>Building a regex with zero patterns results in a regex that never
matches anything. Because this routine is generic, passing an empty
slice usually requires a turbo-fish (or something else to help type
inference).</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, util::syntax, Match};
<span class="kw">let </span>re = Regex::new_many::&lt;<span class="kw-2">&amp;</span>str&gt;(<span class="kw-2">&amp;</span>[])<span class="question-mark">?</span>;
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, re.find(<span class="string">""</span>));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.config" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#421-423">source</a><h4 class="code-header">pub fn <a href="#method.config" class="fn">config</a>() -&gt; <a class="struct" href="struct.Config.html" title="struct regex_automata::meta::Config">Config</a></h4></section></summary><div class="docblock"><p>Return a default configuration for a <code>Regex</code>.</p>
<p>This is a convenience routine to avoid needing to import the <a href="struct.Config.html" title="struct regex_automata::meta::Config"><code>Config</code></a>
type when customizing the construction of a <code>Regex</code>.</p>
<h5 id="example-lower-the-nfa-size-limit"><a href="#example-lower-the-nfa-size-limit">Example: lower the NFA size limit</a></h5>
<p>In some cases, the default size limit might be too big. The size limit
can be lowered, which will prevent large regex patterns from compiling.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>result = Regex::builder()
.configure(Regex::config().nfa_size_limit(<span class="prelude-val">Some</span>(<span class="number">20 </span>* (<span class="number">1</span>&lt;&lt;<span class="number">10</span>))))
<span class="comment">// Not even 20KB is enough to build a single large Unicode class!
</span>.build(<span class="string">r"\pL"</span>);
<span class="macro">assert!</span>(result.is_err());
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.builder" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#447-449">source</a><h4 class="code-header">pub fn <a href="#method.builder" class="fn">builder</a>() -&gt; <a class="struct" href="struct.Builder.html" title="struct regex_automata::meta::Builder">Builder</a></h4></section></summary><div class="docblock"><p>Return a builder for configuring the construction of a <code>Regex</code>.</p>
<p>This is a convenience routine to avoid needing to import the
<a href="struct.Builder.html" title="struct regex_automata::meta::Builder"><code>Builder</code></a> type in common cases.</p>
<h5 id="example-change-the-line-terminator-1"><a href="#example-change-the-line-terminator-1">Example: change the line terminator</a></h5>
<p>This example shows how to enable multi-line mode by default and change
the line terminator to the NUL byte:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, util::syntax, Match};
<span class="kw">let </span>re = Regex::builder()
.syntax(syntax::Config::new().multi_line(<span class="bool-val">true</span>))
.configure(Regex::config().line_terminator(<span class="string">b'\x00'</span>))
.build(<span class="string">r"^foo$"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"\x00foo\x00"</span>;
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">1</span>..<span class="number">4</span>)), re.find(hay));
</code></pre></div>
</div></details></div></details><details class="toggle implementors-toggle" open><summary><section id="impl-Regex-1" class="impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#453-895">source</a><a href="#impl-Regex-1" class="anchor">§</a><h3 class="code-header">impl <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section></summary><div class="docblock"><p>High level convenience routines for using a regex to search a haystack.</p>
</div><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.is_match" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#530-540">source</a><h4 class="code-header">pub fn <a href="#method.is_match" class="fn">is_match</a>&lt;'h, I: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'h&gt;&gt;&gt;(&amp;self, input: I) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Returns true if and only if this regex matches the given haystack.</p>
<p>This routine may short circuit if it knows that scanning future input
will never lead to a different result. (Consider how this might make
a difference given the regex <code>a+</code> on the haystack <code>aaaaaaaaaaaaaaa</code>.
This routine <em>may</em> stop after it sees the first <code>a</code>, but routines like
<code>find</code> need to continue searching because <code>+</code> is greedy by default.)</p>
<h5 id="example-2"><a href="#example-2">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">"foo[0-9]+bar"</span>)<span class="question-mark">?</span>;
<span class="macro">assert!</span>(re.is_match(<span class="string">"foo12345bar"</span>));
<span class="macro">assert!</span>(!re.is_match(<span class="string">"foobar"</span>));
</code></pre></div>
<h5 id="example-consistency-with-search-apis"><a href="#example-consistency-with-search-apis">Example: consistency with search APIs</a></h5>
<p><code>is_match</code> is guaranteed to return <code>true</code> whenever <code>find</code> returns a
match. This includes searches that are executed entirely within a
codepoint:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input};
<span class="kw">let </span>re = Regex::new(<span class="string">"a*"</span>)<span class="question-mark">?</span>;
<span class="comment">// This doesn't match because the default configuration bans empty
// matches from splitting a codepoint.
</span><span class="macro">assert!</span>(!re.is_match(Input::new(<span class="string">"☃"</span>).span(<span class="number">1</span>..<span class="number">2</span>)));
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, re.find(Input::new(<span class="string">"☃"</span>).span(<span class="number">1</span>..<span class="number">2</span>)));
</code></pre></div>
<p>Notice that when UTF-8 mode is disabled, then the above reports a
match because the restriction against zero-width matches that split a
codepoint has been lifted:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, Match};
<span class="kw">let </span>re = Regex::builder()
.configure(Regex::config().utf8_empty(<span class="bool-val">false</span>))
.build(<span class="string">"a*"</span>)<span class="question-mark">?</span>;
<span class="macro">assert!</span>(re.is_match(Input::new(<span class="string">"☃"</span>).span(<span class="number">1</span>..<span class="number">2</span>)));
<span class="macro">assert_eq!</span>(
<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">1</span>..<span class="number">1</span>)),
re.find(Input::new(<span class="string">"☃"</span>).span(<span class="number">1</span>..<span class="number">2</span>)),
);
</code></pre></div>
<p>A similar idea applies when using line anchors with CRLF mode enabled,
which prevents them from matching between a <code>\r</code> and a <code>\n</code>.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">r"(?Rm:$)"</span>)<span class="question-mark">?</span>;
<span class="macro">assert!</span>(!re.is_match(Input::new(<span class="string">"\r\n"</span>).span(<span class="number">1</span>..<span class="number">1</span>)));
<span class="comment">// A regular line anchor, which only considers \n as a
// line terminator, will match.
</span><span class="kw">let </span>re = Regex::new(<span class="string">r"(?m:$)"</span>)<span class="question-mark">?</span>;
<span class="macro">assert!</span>(re.is_match(Input::new(<span class="string">"\r\n"</span>).span(<span class="number">1</span>..<span class="number">1</span>)));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.find" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#556-558">source</a><h4 class="code-header">pub fn <a href="#method.find" class="fn">find</a>&lt;'h, I: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'h&gt;&gt;&gt;(&amp;self, input: I) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../struct.Match.html" title="struct regex_automata::Match">Match</a>&gt;</h4></section></summary><div class="docblock"><p>Executes a leftmost search and returns the first match that is found,
if one exists.</p>
<h5 id="example-3"><a href="#example-3">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">"foo[0-9]+"</span>)<span class="question-mark">?</span>;
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">8</span>)), re.find(<span class="string">"foo12345"</span>));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.captures" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#582-588">source</a><h4 class="code-header">pub fn <a href="#method.captures" class="fn">captures</a>&lt;'h, I: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'h&gt;&gt;&gt;(&amp;self, input: I, caps: &amp;mut <a class="struct" href="../util/captures/struct.Captures.html" title="struct regex_automata::util::captures::Captures">Captures</a>)</h4></section></summary><div class="docblock"><p>Executes a leftmost forward search and writes the spans of capturing
groups that participated in a match into the provided <a href="../util/captures/struct.Captures.html" title="struct regex_automata::util::captures::Captures"><code>Captures</code></a>
value. If no match was found, then <a href="../util/captures/struct.Captures.html#method.is_match" title="method regex_automata::util::captures::Captures::is_match"><code>Captures::is_match</code></a> is guaranteed
to return <code>false</code>.</p>
<h5 id="example-4"><a href="#example-4">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Span};
<span class="kw">let </span>re = Regex::new(<span class="string">r"^([0-9]{4})-([0-9]{2})-([0-9]{2})$"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span><span class="kw-2">mut </span>caps = re.create_captures();
re.captures(<span class="string">"2010-03-14"</span>, <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert!</span>(caps.is_match());
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Span::from(<span class="number">0</span>..<span class="number">4</span>)), caps.get_group(<span class="number">1</span>));
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Span::from(<span class="number">5</span>..<span class="number">7</span>)), caps.get_group(<span class="number">2</span>));
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Span::from(<span class="number">8</span>..<span class="number">10</span>)), caps.get_group(<span class="number">3</span>));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.find_iter" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#610-617">source</a><h4 class="code-header">pub fn <a href="#method.find_iter" class="fn">find_iter</a>&lt;'r, 'h, I: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'h&gt;&gt;&gt;(
&amp;'r self,
input: I
) -&gt; <a class="struct" href="struct.FindMatches.html" title="struct regex_automata::meta::FindMatches">FindMatches</a>&lt;'r, 'h&gt; <a href="#" class="tooltip" data-notable-ty="FindMatches&lt;&#39;r, &#39;h&gt;">ⓘ</a></h4></section></summary><div class="docblock"><p>Returns an iterator over all non-overlapping leftmost matches in
the given haystack. If no match exists, then the iterator yields no
elements.</p>
<h5 id="example-5"><a href="#example-5">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">"foo[0-9]+"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>haystack = <span class="string">"foo1 foo12 foo123"</span>;
<span class="kw">let </span>matches: Vec&lt;Match&gt; = re.find_iter(haystack).collect();
<span class="macro">assert_eq!</span>(matches, <span class="macro">vec!</span>[
Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">4</span>),
Match::must(<span class="number">0</span>, <span class="number">5</span>..<span class="number">10</span>),
Match::must(<span class="number">0</span>, <span class="number">11</span>..<span class="number">17</span>),
]);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.captures_iter" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#651-659">source</a><h4 class="code-header">pub fn <a href="#method.captures_iter" class="fn">captures_iter</a>&lt;'r, 'h, I: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'h&gt;&gt;&gt;(
&amp;'r self,
input: I
) -&gt; <a class="struct" href="struct.CapturesMatches.html" title="struct regex_automata::meta::CapturesMatches">CapturesMatches</a>&lt;'r, 'h&gt; <a href="#" class="tooltip" data-notable-ty="CapturesMatches&lt;&#39;r, &#39;h&gt;">ⓘ</a></h4></section></summary><div class="docblock"><p>Returns an iterator over all non-overlapping <code>Captures</code> values. If no
match exists, then the iterator yields no elements.</p>
<p>This yields the same matches as <a href="struct.Regex.html#method.find_iter" title="method regex_automata::meta::Regex::find_iter"><code>Regex::find_iter</code></a>, but it includes
the spans of all capturing groups that participate in each match.</p>
<p><strong>Tip:</strong> See <a href="../util/iter/struct.Searcher.html" title="struct regex_automata::util::iter::Searcher"><code>util::iter::Searcher</code></a> for
how to correctly iterate over all matches in a haystack while avoiding
the creation of a new <code>Captures</code> value for every match. (Which you are
forced to do with an <code>Iterator</code>.)</p>
<h5 id="example-6"><a href="#example-6">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Span};
<span class="kw">let </span>re = Regex::new(<span class="string">"foo(?P&lt;numbers&gt;[0-9]+)"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>haystack = <span class="string">"foo1 foo12 foo123"</span>;
<span class="kw">let </span>matches: Vec&lt;Span&gt; = re
.captures_iter(haystack)
<span class="comment">// The unwrap is OK since 'numbers' matches if the pattern matches.
</span>.map(|caps| caps.get_group_by_name(<span class="string">"numbers"</span>).unwrap())
.collect();
<span class="macro">assert_eq!</span>(matches, <span class="macro">vec!</span>[
Span::from(<span class="number">3</span>..<span class="number">4</span>),
Span::from(<span class="number">8</span>..<span class="number">10</span>),
Span::from(<span class="number">14</span>..<span class="number">17</span>),
]);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.split" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#815-820">source</a><h4 class="code-header">pub fn <a href="#method.split" class="fn">split</a>&lt;'r, 'h, I: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'h&gt;&gt;&gt;(&amp;'r self, input: I) -&gt; <a class="struct" href="struct.Split.html" title="struct regex_automata::meta::Split">Split</a>&lt;'r, 'h&gt; <a href="#" class="tooltip" data-notable-ty="Split&lt;&#39;r, &#39;h&gt;">ⓘ</a></h4></section></summary><div class="docblock"><p>Returns an iterator of spans of the haystack given, delimited by a
match of the regex. Namely, each element of the iterator corresponds to
a part of the haystack that <em>isn’t</em> matched by the regular expression.</p>
<h5 id="example-7"><a href="#example-7">Example</a></h5>
<p>To split a string delimited by arbitrary amounts of spaces or tabs:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r"[ \t]+"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"a b \t c\td e"</span>;
<span class="kw">let </span>fields: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|span| <span class="kw-2">&amp;</span>hay[span]).collect();
<span class="macro">assert_eq!</span>(fields, <span class="macro">vec!</span>[<span class="string">"a"</span>, <span class="string">"b"</span>, <span class="string">"c"</span>, <span class="string">"d"</span>, <span class="string">"e"</span>]);
</code></pre></div>
<h5 id="example-more-cases"><a href="#example-more-cases">Example: more cases</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r" "</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"Mary had a little lamb"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"Mary"</span>, <span class="string">"had"</span>, <span class="string">"a"</span>, <span class="string">"little"</span>, <span class="string">"lamb"</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"X"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">""</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">""</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"X"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"lionXXtigerXleopard"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"lion"</span>, <span class="string">""</span>, <span class="string">"tiger"</span>, <span class="string">"leopard"</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"::"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"lion::tiger::leopard"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"lion"</span>, <span class="string">"tiger"</span>, <span class="string">"leopard"</span>]);
</code></pre></div>
<p>If a haystack contains multiple contiguous matches, you will end up
with empty spans yielded by the iterator:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r"X"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"XXXXaXXbXc"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">""</span>, <span class="string">""</span>, <span class="string">""</span>, <span class="string">""</span>, <span class="string">"a"</span>, <span class="string">""</span>, <span class="string">"b"</span>, <span class="string">"c"</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"/"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"(///)"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"("</span>, <span class="string">""</span>, <span class="string">""</span>, <span class="string">")"</span>]);
</code></pre></div>
<p>Separators at the start or end of a haystack are neighbored by empty
spans.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r"0"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"010"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">""</span>, <span class="string">"1"</span>, <span class="string">""</span>]);
</code></pre></div>
<p>When the empty string is used as a regex, it splits at every valid
UTF-8 boundary by default (which includes the beginning and end of the
haystack):</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r""</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"rust"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">""</span>, <span class="string">"r"</span>, <span class="string">"u"</span>, <span class="string">"s"</span>, <span class="string">"t"</span>, <span class="string">""</span>]);
<span class="comment">// Splitting by an empty string is UTF-8 aware by default!
</span><span class="kw">let </span>re = Regex::new(<span class="string">r""</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"☃"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">""</span>, <span class="string">"☃"</span>, <span class="string">""</span>]);
</code></pre></div>
<p>But note that UTF-8 mode for empty strings can be disabled, which will
then result in a match at every byte offset in the haystack,
including between every UTF-8 code unit.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::builder()
.configure(Regex::config().utf8_empty(<span class="bool-val">false</span>))
.build(<span class="string">r""</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"☃"</span>.as_bytes();
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>[u8]&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[
<span class="comment">// Writing byte string slices is just brutal. The problem is that
// b"foo" has type &amp;[u8; 3] instead of &amp;[u8].
</span><span class="kw-2">&amp;</span>[][..], <span class="kw-2">&amp;</span>[<span class="string">b'\xE2'</span>][..], <span class="kw-2">&amp;</span>[<span class="string">b'\x98'</span>][..], <span class="kw-2">&amp;</span>[<span class="string">b'\x83'</span>][..], <span class="kw-2">&amp;</span>[][..],
]);
</code></pre></div>
<p>Contiguous separators (commonly shows up with whitespace), can lead to
possibly surprising behavior. For example, this code is correct:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r" "</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">" a b c"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">""</span>, <span class="string">""</span>, <span class="string">""</span>, <span class="string">""</span>, <span class="string">"a"</span>, <span class="string">""</span>, <span class="string">"b"</span>, <span class="string">"c"</span>]);
</code></pre></div>
<p>It does <em>not</em> give you <code>[&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]</code>. For that behavior, you’d want
to match contiguous space characters:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r" +"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">" a b c"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.split(hay).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="comment">// N.B. This does still include a leading empty span because ' +'
// matches at the beginning of the haystack.
</span><span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">""</span>, <span class="string">"a"</span>, <span class="string">"b"</span>, <span class="string">"c"</span>]);
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.splitn" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#888-894">source</a><h4 class="code-header">pub fn <a href="#method.splitn" class="fn">splitn</a>&lt;'r, 'h, I: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'h&gt;&gt;&gt;(
&amp;'r self,
input: I,
limit: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>
) -&gt; <a class="struct" href="struct.SplitN.html" title="struct regex_automata::meta::SplitN">SplitN</a>&lt;'r, 'h&gt; <a href="#" class="tooltip" data-notable-ty="SplitN&lt;&#39;r, &#39;h&gt;">ⓘ</a></h4></section></summary><div class="docblock"><p>Returns an iterator of at most <code>limit</code> spans of the haystack given,
delimited by a match of the regex. (A <code>limit</code> of <code>0</code> will return no
spans.) Namely, each element of the iterator corresponds to a part
of the haystack that <em>isn’t</em> matched by the regular expression. The
remainder of the haystack that is not split will be the last element in
the iterator.</p>
<h5 id="example-8"><a href="#example-8">Example</a></h5>
<p>Get the first two words in some haystack:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r"\W+"</span>).unwrap();
<span class="kw">let </span>hay = <span class="string">"Hey! How are you?"</span>;
<span class="kw">let </span>fields: Vec&lt;<span class="kw-2">&amp;</span>str&gt; =
re.splitn(hay, <span class="number">3</span>).map(|span| <span class="kw-2">&amp;</span>hay[span]).collect();
<span class="macro">assert_eq!</span>(fields, <span class="macro">vec!</span>[<span class="string">"Hey"</span>, <span class="string">"How"</span>, <span class="string">"are you?"</span>]);
</code></pre></div>
<h5 id="examples-more-cases"><a href="#examples-more-cases">Examples: more cases</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r" "</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"Mary had a little lamb"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.splitn(hay, <span class="number">3</span>).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"Mary"</span>, <span class="string">"had"</span>, <span class="string">"a little lamb"</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"X"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">""</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.splitn(hay, <span class="number">3</span>).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">""</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"X"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"lionXXtigerXleopard"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.splitn(hay, <span class="number">3</span>).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"lion"</span>, <span class="string">""</span>, <span class="string">"tigerXleopard"</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"::"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"lion::tiger::leopard"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.splitn(hay, <span class="number">2</span>).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"lion"</span>, <span class="string">"tiger::leopard"</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"X"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"abcXdef"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.splitn(hay, <span class="number">1</span>).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"abcXdef"</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"X"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"abcdef"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.splitn(hay, <span class="number">2</span>).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert_eq!</span>(got, <span class="macro">vec!</span>[<span class="string">"abcdef"</span>]);
<span class="kw">let </span>re = Regex::new(<span class="string">r"X"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>hay = <span class="string">"abcXdef"</span>;
<span class="kw">let </span>got: Vec&lt;<span class="kw-2">&amp;</span>str&gt; = re.splitn(hay, <span class="number">0</span>).map(|sp| <span class="kw-2">&amp;</span>hay[sp]).collect();
<span class="macro">assert!</span>(got.is_empty());
</code></pre></div>
</div></details></div></details><details class="toggle implementors-toggle" open><summary><section id="impl-Regex-2" class="impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#898-1204">source</a><a href="#impl-Regex-2" class="anchor">§</a><h3 class="code-header">impl <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section></summary><div class="docblock"><p>Lower level search routines that give more control.</p>
</div><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.search" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#919-945">source</a><h4 class="code-header">pub fn <a href="#method.search" class="fn">search</a>(&amp;self, input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../struct.Match.html" title="struct regex_automata::Match">Match</a>&gt;</h4></section></summary><div class="docblock"><p>Returns the start and end offset of the leftmost match. If no match
exists, then <code>None</code> is returned.</p>
<p>This is like <a href="struct.Regex.html#method.find" title="method regex_automata::meta::Regex::find"><code>Regex::find</code></a> but, but it accepts a concrete <code>&amp;Input</code>
instead of an <code>Into&lt;Input&gt;</code>.</p>
<h5 id="example-9"><a href="#example-9">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">r"Samwise|Sam"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>input = Input::new(
<span class="string">"one of the chief characters, Samwise the Brave"</span>,
);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">29</span>..<span class="number">36</span>)), re.search(<span class="kw-2">&amp;</span>input));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.search_half" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#975-984">source</a><h4 class="code-header">pub fn <a href="#method.search_half" class="fn">search_half</a>(&amp;self, input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../struct.HalfMatch.html" title="struct regex_automata::HalfMatch">HalfMatch</a>&gt;</h4></section></summary><div class="docblock"><p>Returns the end offset of the leftmost match. If no match exists, then
<code>None</code> is returned.</p>
<p>This is distinct from <a href="struct.Regex.html#method.search" title="method regex_automata::meta::Regex::search"><code>Regex::search</code></a> in that it only returns the end
of a match and not the start of the match. Depending on a variety of
implementation details, this <em>may</em> permit the regex engine to do less
overall work. For example, if a DFA is being used to execute a search,
then the start of a match usually requires running a separate DFA in
reverse to the find the start of a match. If one only needs the end of
a match, then the separate reverse scan to find the start of a match
can be skipped. (Note that the reverse scan is avoided even when using
<code>Regex::search</code> when possible, for example, in the case of an anchored
search.)</p>
<h5 id="example-10"><a href="#example-10">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, HalfMatch};
<span class="kw">let </span>re = Regex::new(<span class="string">r"Samwise|Sam"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>input = Input::new(
<span class="string">"one of the chief characters, Samwise the Brave"</span>,
);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(HalfMatch::must(<span class="number">0</span>, <span class="number">36</span>)), re.search_half(<span class="kw-2">&amp;</span>input));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.search_captures" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1063-1067">source</a><h4 class="code-header">pub fn <a href="#method.search_captures" class="fn">search_captures</a>(&amp;self, input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;, caps: &amp;mut <a class="struct" href="../util/captures/struct.Captures.html" title="struct regex_automata::util::captures::Captures">Captures</a>)</h4></section></summary><div class="docblock"><p>Executes a leftmost forward search and writes the spans of capturing
groups that participated in a match into the provided <a href="../util/captures/struct.Captures.html" title="struct regex_automata::util::captures::Captures"><code>Captures</code></a>
value. If no match was found, then <a href="../util/captures/struct.Captures.html#method.is_match" title="method regex_automata::util::captures::Captures::is_match"><code>Captures::is_match</code></a> is guaranteed
to return <code>false</code>.</p>
<p>This is like <a href="struct.Regex.html#method.captures" title="method regex_automata::meta::Regex::captures"><code>Regex::captures</code></a>, but it accepts a concrete <code>&amp;Input</code>
instead of an <code>Into&lt;Input&gt;</code>.</p>
<h5 id="example-specific-pattern-search"><a href="#example-specific-pattern-search">Example: specific pattern search</a></h5>
<p>This example shows how to build a multi-pattern <code>Regex</code> that permits
searching for specific patterns.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{
meta::Regex,
Anchored, Match, PatternID, Input,
};
<span class="kw">let </span>re = Regex::new_many(<span class="kw-2">&amp;</span>[<span class="string">"[a-z0-9]{6}"</span>, <span class="string">"[a-z][a-z0-9]{5}"</span>])<span class="question-mark">?</span>;
<span class="kw">let </span><span class="kw-2">mut </span>caps = re.create_captures();
<span class="kw">let </span>haystack = <span class="string">"foo123"</span>;
<span class="comment">// Since we are using the default leftmost-first match and both
// patterns match at the same starting position, only the first pattern
// will be returned in this case when doing a search for any of the
// patterns.
</span><span class="kw">let </span>expected = <span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">6</span>));
re.search_captures(<span class="kw-2">&amp;</span>Input::new(haystack), <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert_eq!</span>(expected, caps.get_match());
<span class="comment">// But if we want to check whether some other pattern matches, then we
// can provide its pattern ID.
</span><span class="kw">let </span>expected = <span class="prelude-val">Some</span>(Match::must(<span class="number">1</span>, <span class="number">0</span>..<span class="number">6</span>));
<span class="kw">let </span>input = Input::new(haystack)
.anchored(Anchored::Pattern(PatternID::must(<span class="number">1</span>)));
re.search_captures(<span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert_eq!</span>(expected, caps.get_match());
</code></pre></div>
<h5 id="example-specifying-the-bounds-of-a-search"><a href="#example-specifying-the-bounds-of-a-search">Example: specifying the bounds of a search</a></h5>
<p>This example shows how providing the bounds of a search can produce
different results than simply sub-slicing the haystack.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Match, Input};
<span class="kw">let </span>re = Regex::new(<span class="string">r"\b[0-9]{3}\b"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span><span class="kw-2">mut </span>caps = re.create_captures();
<span class="kw">let </span>haystack = <span class="string">"foo123bar"</span>;
<span class="comment">// Since we sub-slice the haystack, the search doesn't know about
// the larger context and assumes that `123` is surrounded by word
// boundaries. And of course, the match position is reported relative
// to the sub-slice as well, which means we get `0..3` instead of
// `3..6`.
</span><span class="kw">let </span>expected = <span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">3</span>));
<span class="kw">let </span>input = Input::new(<span class="kw-2">&amp;</span>haystack[<span class="number">3</span>..<span class="number">6</span>]);
re.search_captures(<span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert_eq!</span>(expected, caps.get_match());
<span class="comment">// But if we provide the bounds of the search within the context of the
// entire haystack, then the search can take the surrounding context
// into account. (And if we did find a match, it would be reported
// as a valid offset into `haystack` instead of its sub-slice.)
</span><span class="kw">let </span>expected = <span class="prelude-val">None</span>;
<span class="kw">let </span>input = Input::new(haystack).range(<span class="number">3</span>..<span class="number">6</span>);
re.search_captures(<span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert_eq!</span>(expected, caps.get_match());
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.search_slots" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1126-1139">source</a><h4 class="code-header">pub fn <a href="#method.search_slots" class="fn">search_slots</a>(
&amp;self,
input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;,
slots: &amp;mut [<a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../util/primitives/struct.NonMaxUsize.html" title="struct regex_automata::util::primitives::NonMaxUsize">NonMaxUsize</a>&gt;]
) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../struct.PatternID.html" title="struct regex_automata::PatternID">PatternID</a>&gt;</h4></section></summary><div class="docblock"><p>Executes a leftmost forward search and writes the spans of capturing
groups that participated in a match into the provided <code>slots</code>, and
returns the matching pattern ID. The contents of the slots for patterns
other than the matching pattern are unspecified. If no match was found,
then <code>None</code> is returned and the contents of <code>slots</code> is unspecified.</p>
<p>This is like <a href="struct.Regex.html#method.search" title="method regex_automata::meta::Regex::search"><code>Regex::search</code></a>, but it accepts a raw slots slice
instead of a <code>Captures</code> value. This is useful in contexts where you
don’t want or need to allocate a <code>Captures</code>.</p>
<p>It is legal to pass <em>any</em> number of slots to this routine. If the regex
engine would otherwise write a slot offset that doesn’t fit in the
provided slice, then it is simply skipped. In general though, there are
usually three slice lengths you might want to use:</p>
<ul>
<li>An empty slice, if you only care about which pattern matched.</li>
<li>A slice with <a href="struct.Regex.html#method.pattern_len" title="method regex_automata::meta::Regex::pattern_len"><code>pattern_len() * 2</code></a> slots, if you
only care about the overall match spans for each matching pattern.</li>
<li>A slice with
<a href="../util/captures/struct.GroupInfo.html#method.slot_len" title="method regex_automata::util::captures::GroupInfo::slot_len"><code>slot_len()</code></a> slots, which
permits recording match offsets for every capturing group in every
pattern.</li>
</ul>
<h5 id="example-11"><a href="#example-11">Example</a></h5>
<p>This example shows how to find the overall match offsets in a
multi-pattern search without allocating a <code>Captures</code> value. Indeed, we
can put our slots right on the stack.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, PatternID, Input};
<span class="kw">let </span>re = Regex::new_many(<span class="kw-2">&amp;</span>[
<span class="string">r"\pL+"</span>,
<span class="string">r"\d+"</span>,
])<span class="question-mark">?</span>;
<span class="kw">let </span>input = Input::new(<span class="string">"!@#123"</span>);
<span class="comment">// We only care about the overall match offsets here, so we just
// allocate two slots for each pattern. Each slot records the start
// and end of the match.
</span><span class="kw">let </span><span class="kw-2">mut </span>slots = [<span class="prelude-val">None</span>; <span class="number">4</span>];
<span class="kw">let </span>pid = re.search_slots(<span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>slots);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(PatternID::must(<span class="number">1</span>)), pid);
<span class="comment">// The overall match offsets are always at 'pid * 2' and 'pid * 2 + 1'.
// See 'GroupInfo' for more details on the mapping between groups and
// slot indices.
</span><span class="kw">let </span>slot_start = pid.unwrap().as_usize() * <span class="number">2</span>;
<span class="kw">let </span>slot_end = slot_start + <span class="number">1</span>;
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">3</span>), slots[slot_start].map(|s| s.get()));
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">6</span>), slots[slot_end].map(|s| s.get()));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.which_overlapping_matches" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1187-1203">source</a><h4 class="code-header">pub fn <a href="#method.which_overlapping_matches" class="fn">which_overlapping_matches</a>(
&amp;self,
input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;,
patset: &amp;mut <a class="struct" href="../struct.PatternSet.html" title="struct regex_automata::PatternSet">PatternSet</a>
)</h4></section></summary><div class="docblock"><p>Writes the set of patterns that match anywhere in the given search
configuration to <code>patset</code>. If multiple patterns match at the same
position and this <code>Regex</code> was configured with <a href="../enum.MatchKind.html#variant.All" title="variant regex_automata::MatchKind::All"><code>MatchKind::All</code></a>
semantics, then all matching patterns are written to the given set.</p>
<p>Unless all of the patterns in this <code>Regex</code> are anchored, then generally
speaking, this will scan the entire haystack.</p>
<p>This search routine <em>does not</em> clear the pattern set. This gives some
flexibility to the caller (e.g., running multiple searches with the
same pattern set), but does make the API bug-prone if you’re reusing
the same pattern set for multiple searches but intended them to be
independent.</p>
<p>If a pattern ID matched but the given <code>PatternSet</code> does not have
sufficient capacity to store it, then it is not inserted and silently
dropped.</p>
<h5 id="example-12"><a href="#example-12">Example</a></h5>
<p>This example shows how to find all matching patterns in a haystack,
even when some patterns match at the same position as other patterns.
It is important that we configure the <code>Regex</code> with <a href="../enum.MatchKind.html#variant.All" title="variant regex_automata::MatchKind::All"><code>MatchKind::All</code></a>
semantics here, or else overlapping matches will not be reported.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, MatchKind, PatternSet};
<span class="kw">let </span>patterns = <span class="kw-2">&amp;</span>[
<span class="string">r"\w+"</span>, <span class="string">r"\d+"</span>, <span class="string">r"\pL+"</span>, <span class="string">r"foo"</span>, <span class="string">r"bar"</span>, <span class="string">r"barfoo"</span>, <span class="string">r"foobar"</span>,
];
<span class="kw">let </span>re = Regex::builder()
.configure(Regex::config().match_kind(MatchKind::All))
.build_many(patterns)<span class="question-mark">?</span>;
<span class="kw">let </span>input = Input::new(<span class="string">"foobar"</span>);
<span class="kw">let </span><span class="kw-2">mut </span>patset = PatternSet::new(re.pattern_len());
re.which_overlapping_matches(<span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>patset);
<span class="kw">let </span>expected = <span class="macro">vec!</span>[<span class="number">0</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">6</span>];
<span class="kw">let </span>got: Vec&lt;usize&gt; = patset.iter().map(|p| p.as_usize()).collect();
<span class="macro">assert_eq!</span>(expected, got);
</code></pre></div>
</div></details></div></details><details class="toggle implementors-toggle" open><summary><section id="impl-Regex-3" class="impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1208-1494">source</a><a href="#impl-Regex-3" class="anchor">§</a><h3 class="code-header">impl <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section></summary><div class="docblock"><p>Lower level search routines that give more control, and require the caller
to provide an explicit <a href="struct.Cache.html" title="struct regex_automata::meta::Cache"><code>Cache</code></a> parameter.</p>
</div><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.search_with" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1240-1249">source</a><h4 class="code-header">pub fn <a href="#method.search_with" class="fn">search_with</a>(&amp;self, cache: &amp;mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>, input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../struct.Match.html" title="struct regex_automata::Match">Match</a>&gt;</h4></section></summary><div class="docblock"><p>This is like <a href="struct.Regex.html#method.search" title="method regex_automata::meta::Regex::search"><code>Regex::search</code></a>, but requires the caller to
explicitly pass a <a href="struct.Cache.html" title="struct regex_automata::meta::Cache"><code>Cache</code></a>.</p>
<h5 id="why-pass-a-cache-explicitly"><a href="#why-pass-a-cache-explicitly">Why pass a <code>Cache</code> explicitly?</a></h5>
<p>Passing a <code>Cache</code> explicitly will bypass the use of an internal memory
pool used by <code>Regex</code> to get a <code>Cache</code> for a search. The use of this
pool can be slower in some cases when a <code>Regex</code> is used from multiple
threads simultaneously. Typically, performance only becomes an issue
when there is heavy contention, which in turn usually only occurs
when each thread’s primary unit of work is a regex search on a small
haystack.</p>
<h5 id="example-13"><a href="#example-13">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">r"Samwise|Sam"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span><span class="kw-2">mut </span>cache = re.create_cache();
<span class="kw">let </span>input = Input::new(
<span class="string">"one of the chief characters, Samwise the Brave"</span>,
);
<span class="macro">assert_eq!</span>(
<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">29</span>..<span class="number">36</span>)),
re.search_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>input),
);
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.search_half_with" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1282-1291">source</a><h4 class="code-header">pub fn <a href="#method.search_half_with" class="fn">search_half_with</a>(
&amp;self,
cache: &amp;mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>,
input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;
) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../struct.HalfMatch.html" title="struct regex_automata::HalfMatch">HalfMatch</a>&gt;</h4></section></summary><div class="docblock"><p>This is like <a href="struct.Regex.html#method.search_half" title="method regex_automata::meta::Regex::search_half"><code>Regex::search_half</code></a>, but requires the caller to
explicitly pass a <a href="struct.Cache.html" title="struct regex_automata::meta::Cache"><code>Cache</code></a>.</p>
<h5 id="why-pass-a-cache-explicitly-1"><a href="#why-pass-a-cache-explicitly-1">Why pass a <code>Cache</code> explicitly?</a></h5>
<p>Passing a <code>Cache</code> explicitly will bypass the use of an internal memory
pool used by <code>Regex</code> to get a <code>Cache</code> for a search. The use of this
pool can be slower in some cases when a <code>Regex</code> is used from multiple
threads simultaneously. Typically, performance only becomes an issue
when there is heavy contention, which in turn usually only occurs
when each thread’s primary unit of work is a regex search on a small
haystack.</p>
<h5 id="example-14"><a href="#example-14">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, HalfMatch};
<span class="kw">let </span>re = Regex::new(<span class="string">r"Samwise|Sam"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span><span class="kw-2">mut </span>cache = re.create_cache();
<span class="kw">let </span>input = Input::new(
<span class="string">"one of the chief characters, Samwise the Brave"</span>,
);
<span class="macro">assert_eq!</span>(
<span class="prelude-val">Some</span>(HalfMatch::must(<span class="number">0</span>, <span class="number">36</span>)),
re.search_half_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>input),
);
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.search_captures_with" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1375-1384">source</a><h4 class="code-header">pub fn <a href="#method.search_captures_with" class="fn">search_captures_with</a>(
&amp;self,
cache: &amp;mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>,
input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;,
caps: &amp;mut <a class="struct" href="../util/captures/struct.Captures.html" title="struct regex_automata::util::captures::Captures">Captures</a>
)</h4></section></summary><div class="docblock"><p>This is like <a href="struct.Regex.html#method.search_captures" title="method regex_automata::meta::Regex::search_captures"><code>Regex::search_captures</code></a>, but requires the caller to
explicitly pass a <a href="struct.Cache.html" title="struct regex_automata::meta::Cache"><code>Cache</code></a>.</p>
<h5 id="why-pass-a-cache-explicitly-2"><a href="#why-pass-a-cache-explicitly-2">Why pass a <code>Cache</code> explicitly?</a></h5>
<p>Passing a <code>Cache</code> explicitly will bypass the use of an internal memory
pool used by <code>Regex</code> to get a <code>Cache</code> for a search. The use of this
pool can be slower in some cases when a <code>Regex</code> is used from multiple
threads simultaneously. Typically, performance only becomes an issue
when there is heavy contention, which in turn usually only occurs
when each thread’s primary unit of work is a regex search on a small
haystack.</p>
<h5 id="example-specific-pattern-search-1"><a href="#example-specific-pattern-search-1">Example: specific pattern search</a></h5>
<p>This example shows how to build a multi-pattern <code>Regex</code> that permits
searching for specific patterns.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{
meta::Regex,
Anchored, Match, PatternID, Input,
};
<span class="kw">let </span>re = Regex::new_many(<span class="kw-2">&amp;</span>[<span class="string">"[a-z0-9]{6}"</span>, <span class="string">"[a-z][a-z0-9]{5}"</span>])<span class="question-mark">?</span>;
<span class="kw">let </span>(<span class="kw-2">mut </span>cache, <span class="kw-2">mut </span>caps) = (re.create_cache(), re.create_captures());
<span class="kw">let </span>haystack = <span class="string">"foo123"</span>;
<span class="comment">// Since we are using the default leftmost-first match and both
// patterns match at the same starting position, only the first pattern
// will be returned in this case when doing a search for any of the
// patterns.
</span><span class="kw">let </span>expected = <span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">6</span>));
re.search_captures_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>Input::new(haystack), <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert_eq!</span>(expected, caps.get_match());
<span class="comment">// But if we want to check whether some other pattern matches, then we
// can provide its pattern ID.
</span><span class="kw">let </span>expected = <span class="prelude-val">Some</span>(Match::must(<span class="number">1</span>, <span class="number">0</span>..<span class="number">6</span>));
<span class="kw">let </span>input = Input::new(haystack)
.anchored(Anchored::Pattern(PatternID::must(<span class="number">1</span>)));
re.search_captures_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert_eq!</span>(expected, caps.get_match());
</code></pre></div>
<h5 id="example-specifying-the-bounds-of-a-search-1"><a href="#example-specifying-the-bounds-of-a-search-1">Example: specifying the bounds of a search</a></h5>
<p>This example shows how providing the bounds of a search can produce
different results than simply sub-slicing the haystack.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Match, Input};
<span class="kw">let </span>re = Regex::new(<span class="string">r"\b[0-9]{3}\b"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span>(<span class="kw-2">mut </span>cache, <span class="kw-2">mut </span>caps) = (re.create_cache(), re.create_captures());
<span class="kw">let </span>haystack = <span class="string">"foo123bar"</span>;
<span class="comment">// Since we sub-slice the haystack, the search doesn't know about
// the larger context and assumes that `123` is surrounded by word
// boundaries. And of course, the match position is reported relative
// to the sub-slice as well, which means we get `0..3` instead of
// `3..6`.
</span><span class="kw">let </span>expected = <span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">3</span>));
<span class="kw">let </span>input = Input::new(<span class="kw-2">&amp;</span>haystack[<span class="number">3</span>..<span class="number">6</span>]);
re.search_captures_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert_eq!</span>(expected, caps.get_match());
<span class="comment">// But if we provide the bounds of the search within the context of the
// entire haystack, then the search can take the surrounding context
// into account. (And if we did find a match, it would be reported
// as a valid offset into `haystack` instead of its sub-slice.)
</span><span class="kw">let </span>expected = <span class="prelude-val">None</span>;
<span class="kw">let </span>input = Input::new(haystack).range(<span class="number">3</span>..<span class="number">6</span>);
re.search_captures_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>caps);
<span class="macro">assert_eq!</span>(expected, caps.get_match());
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.search_slots_with" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1434-1444">source</a><h4 class="code-header">pub fn <a href="#method.search_slots_with" class="fn">search_slots_with</a>(
&amp;self,
cache: &amp;mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>,
input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;,
slots: &amp;mut [<a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../util/primitives/struct.NonMaxUsize.html" title="struct regex_automata::util::primitives::NonMaxUsize">NonMaxUsize</a>&gt;]
) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="struct" href="../struct.PatternID.html" title="struct regex_automata::PatternID">PatternID</a>&gt;</h4></section></summary><div class="docblock"><p>This is like <a href="struct.Regex.html#method.search_slots" title="method regex_automata::meta::Regex::search_slots"><code>Regex::search_slots</code></a>, but requires the caller to
explicitly pass a <a href="struct.Cache.html" title="struct regex_automata::meta::Cache"><code>Cache</code></a>.</p>
<h5 id="why-pass-a-cache-explicitly-3"><a href="#why-pass-a-cache-explicitly-3">Why pass a <code>Cache</code> explicitly?</a></h5>
<p>Passing a <code>Cache</code> explicitly will bypass the use of an internal memory
pool used by <code>Regex</code> to get a <code>Cache</code> for a search. The use of this
pool can be slower in some cases when a <code>Regex</code> is used from multiple
threads simultaneously. Typically, performance only becomes an issue
when there is heavy contention, which in turn usually only occurs
when each thread’s primary unit of work is a regex search on a small
haystack.</p>
<h5 id="example-15"><a href="#example-15">Example</a></h5>
<p>This example shows how to find the overall match offsets in a
multi-pattern search without allocating a <code>Captures</code> value. Indeed, we
can put our slots right on the stack.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, PatternID, Input};
<span class="kw">let </span>re = Regex::new_many(<span class="kw-2">&amp;</span>[
<span class="string">r"\pL+"</span>,
<span class="string">r"\d+"</span>,
])<span class="question-mark">?</span>;
<span class="kw">let </span><span class="kw-2">mut </span>cache = re.create_cache();
<span class="kw">let </span>input = Input::new(<span class="string">"!@#123"</span>);
<span class="comment">// We only care about the overall match offsets here, so we just
// allocate two slots for each pattern. Each slot records the start
// and end of the match.
</span><span class="kw">let </span><span class="kw-2">mut </span>slots = [<span class="prelude-val">None</span>; <span class="number">4</span>];
<span class="kw">let </span>pid = re.search_slots_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>slots);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(PatternID::must(<span class="number">1</span>)), pid);
<span class="comment">// The overall match offsets are always at 'pid * 2' and 'pid * 2 + 1'.
// See 'GroupInfo' for more details on the mapping between groups and
// slot indices.
</span><span class="kw">let </span>slot_start = pid.unwrap().as_usize() * <span class="number">2</span>;
<span class="kw">let </span>slot_end = slot_start + <span class="number">1</span>;
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">3</span>), slots[slot_start].map(|s| s.get()));
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">6</span>), slots[slot_end].map(|s| s.get()));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.which_overlapping_matches_with" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1483-1493">source</a><h4 class="code-header">pub fn <a href="#method.which_overlapping_matches_with" class="fn">which_overlapping_matches_with</a>(
&amp;self,
cache: &amp;mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>,
input: &amp;<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a>&lt;'_&gt;,
patset: &amp;mut <a class="struct" href="../struct.PatternSet.html" title="struct regex_automata::PatternSet">PatternSet</a>
)</h4></section></summary><div class="docblock"><p>This is like <a href="struct.Regex.html#method.which_overlapping_matches" title="method regex_automata::meta::Regex::which_overlapping_matches"><code>Regex::which_overlapping_matches</code></a>, but requires the
caller to explicitly pass a <a href="struct.Cache.html" title="struct regex_automata::meta::Cache"><code>Cache</code></a>.</p>
<p>Passing a <code>Cache</code> explicitly will bypass the use of an internal memory
pool used by <code>Regex</code> to get a <code>Cache</code> for a search. The use of this
pool can be slower in some cases when a <code>Regex</code> is used from multiple
threads simultaneously. Typically, performance only becomes an issue
when there is heavy contention, which in turn usually only occurs
when each thread’s primary unit of work is a regex search on a small
haystack.</p>
<h5 id="why-pass-a-cache-explicitly-4"><a href="#why-pass-a-cache-explicitly-4">Why pass a <code>Cache</code> explicitly?</a></h5><h5 id="example-16"><a href="#example-16">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, MatchKind, PatternSet};
<span class="kw">let </span>patterns = <span class="kw-2">&amp;</span>[
<span class="string">r"\w+"</span>, <span class="string">r"\d+"</span>, <span class="string">r"\pL+"</span>, <span class="string">r"foo"</span>, <span class="string">r"bar"</span>, <span class="string">r"barfoo"</span>, <span class="string">r"foobar"</span>,
];
<span class="kw">let </span>re = Regex::builder()
.configure(Regex::config().match_kind(MatchKind::All))
.build_many(patterns)<span class="question-mark">?</span>;
<span class="kw">let </span><span class="kw-2">mut </span>cache = re.create_cache();
<span class="kw">let </span>input = Input::new(<span class="string">"foobar"</span>);
<span class="kw">let </span><span class="kw-2">mut </span>patset = PatternSet::new(re.pattern_len());
re.which_overlapping_matches_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>input, <span class="kw-2">&amp;mut </span>patset);
<span class="kw">let </span>expected = <span class="macro">vec!</span>[<span class="number">0</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">6</span>];
<span class="kw">let </span>got: Vec&lt;usize&gt; = patset.iter().map(|p| p.as_usize()).collect();
<span class="macro">assert_eq!</span>(expected, got);
</code></pre></div>
</div></details></div></details><details class="toggle implementors-toggle" open><summary><section id="impl-Regex-4" class="impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1498-1897">source</a><a href="#impl-Regex-4" class="anchor">§</a><h3 class="code-header">impl <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section></summary><div class="docblock"><p>Various non-search routines for querying properties of a <code>Regex</code> and
convenience routines for creating <a href="../util/captures/struct.Captures.html" title="struct regex_automata::util::captures::Captures"><code>Captures</code></a> and <a href="struct.Cache.html" title="struct regex_automata::meta::Cache"><code>Cache</code></a> values.</p>
</div><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.create_captures" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1558-1560">source</a><h4 class="code-header">pub fn <a href="#method.create_captures" class="fn">create_captures</a>(&amp;self) -&gt; <a class="struct" href="../util/captures/struct.Captures.html" title="struct regex_automata::util::captures::Captures">Captures</a></h4></section></summary><div class="docblock"><p>Creates a new object for recording capture group offsets. This is used
in search APIs like <a href="struct.Regex.html#method.captures" title="method regex_automata::meta::Regex::captures"><code>Regex::captures</code></a> and <a href="struct.Regex.html#method.search_captures" title="method regex_automata::meta::Regex::search_captures"><code>Regex::search_captures</code></a>.</p>
<p>This is a convenience routine for
<code>Captures::all(re.group_info().clone())</code>. Callers may build other types
of <code>Captures</code> values that record less information (and thus require
less work from the regex engine) using <a href="../util/captures/struct.Captures.html#method.matches" title="associated function regex_automata::util::captures::Captures::matches"><code>Captures::matches</code></a> and
<a href="../util/captures/struct.Captures.html#method.empty" title="associated function regex_automata::util::captures::Captures::empty"><code>Captures::empty</code></a>.</p>
<h5 id="example-17"><a href="#example-17">Example</a></h5>
<p>This shows some alternatives to <a href="struct.Regex.html#method.create_captures" title="method regex_automata::meta::Regex::create_captures"><code>Regex::create_captures</code></a>:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{
meta::Regex,
util::captures::Captures,
Match, PatternID, Span,
};
<span class="kw">let </span>re = Regex::new(<span class="string">r"(?&lt;first&gt;[A-Z][a-z]+) (?&lt;last&gt;[A-Z][a-z]+)"</span>)<span class="question-mark">?</span>;
<span class="comment">// This is equivalent to Regex::create_captures. It stores matching
// offsets for all groups in the regex.
</span><span class="kw">let </span><span class="kw-2">mut </span>all = Captures::all(re.group_info().clone());
re.captures(<span class="string">"Bruce Springsteen"</span>, <span class="kw-2">&amp;mut </span>all);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">17</span>)), all.get_match());
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Span::from(<span class="number">0</span>..<span class="number">5</span>)), all.get_group_by_name(<span class="string">"first"</span>));
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Span::from(<span class="number">6</span>..<span class="number">17</span>)), all.get_group_by_name(<span class="string">"last"</span>));
<span class="comment">// In this version, we only care about the implicit groups, which
// means offsets for the explicit groups will be unavailable. It can
// sometimes be faster to ask for fewer groups, since the underlying
// regex engine needs to do less work to keep track of them.
</span><span class="kw">let </span><span class="kw-2">mut </span>matches = Captures::matches(re.group_info().clone());
re.captures(<span class="string">"Bruce Springsteen"</span>, <span class="kw-2">&amp;mut </span>matches);
<span class="comment">// We still get the overall match info.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">17</span>)), matches.get_match());
<span class="comment">// But now the explicit groups are unavailable.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, matches.get_group_by_name(<span class="string">"first"</span>));
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, matches.get_group_by_name(<span class="string">"last"</span>));
<span class="comment">// Finally, in this version, we don't ask to keep track of offsets for
// *any* groups. All we get back is whether a match occurred, and if
// so, the ID of the pattern that matched.
</span><span class="kw">let </span><span class="kw-2">mut </span>empty = Captures::empty(re.group_info().clone());
re.captures(<span class="string">"Bruce Springsteen"</span>, <span class="kw-2">&amp;mut </span>empty);
<span class="comment">// it's a match!
</span><span class="macro">assert!</span>(empty.is_match());
<span class="comment">// for pattern ID 0
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(PatternID::ZERO), empty.pattern());
<span class="comment">// Match offsets are unavailable.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, empty.get_match());
<span class="comment">// And of course, explicit groups are unavailable too.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, empty.get_group_by_name(<span class="string">"first"</span>));
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, empty.get_group_by_name(<span class="string">"last"</span>));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.create_cache" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1586-1588">source</a><h4 class="code-header">pub fn <a href="#method.create_cache" class="fn">create_cache</a>(&amp;self) -&gt; <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a></h4></section></summary><div class="docblock"><p>Creates a new cache for use with lower level search APIs like
<a href="struct.Regex.html#method.search_with" title="method regex_automata::meta::Regex::search_with"><code>Regex::search_with</code></a>.</p>
<p>The cache returned should only be used for searches for this <code>Regex</code>.
If you want to reuse the cache for another <code>Regex</code>, then you must call
<a href="struct.Cache.html#method.reset" title="method regex_automata::meta::Cache::reset"><code>Cache::reset</code></a> with that <code>Regex</code>.</p>
<p>This is a convenience routine for <a href="struct.Cache.html#method.new" title="associated function regex_automata::meta::Cache::new"><code>Cache::new</code></a>.</p>
<h5 id="example-18"><a href="#example-18">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{meta::Regex, Input, Match};
<span class="kw">let </span>re = Regex::new(<span class="string">r"(?-u)m\w+\s+m\w+"</span>)<span class="question-mark">?</span>;
<span class="kw">let </span><span class="kw-2">mut </span>cache = re.create_cache();
<span class="kw">let </span>input = Input::new(<span class="string">"crazy janey and her mission man"</span>);
<span class="macro">assert_eq!</span>(
<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">20</span>..<span class="number">31</span>)),
re.search_with(<span class="kw-2">&amp;mut </span>cache, <span class="kw-2">&amp;</span>input),
);
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.pattern_len" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1616-1618">source</a><h4 class="code-header">pub fn <a href="#method.pattern_len" class="fn">pattern_len</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a></h4></section></summary><div class="docblock"><p>Returns the total number of patterns in this regex.</p>
<p>The standard <a href="struct.Regex.html#method.new" title="associated function regex_automata::meta::Regex::new"><code>Regex::new</code></a> constructor always results in a <code>Regex</code>
with a single pattern, but <a href="struct.Regex.html#method.new_many" title="associated function regex_automata::meta::Regex::new_many"><code>Regex::new_many</code></a> permits building a
multi-pattern regex.</p>
<p>A <code>Regex</code> guarantees that the maximum possible <code>PatternID</code> returned in
any match is <code>Regex::pattern_len() - 1</code>. In the case where the number
of patterns is <code>0</code>, a match is impossible.</p>
<h5 id="example-19"><a href="#example-19">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>re = Regex::new(<span class="string">r"(?m)^[a-z]$"</span>)<span class="question-mark">?</span>;
<span class="macro">assert_eq!</span>(<span class="number">1</span>, re.pattern_len());
<span class="kw">let </span>re = Regex::new_many::&lt;<span class="kw-2">&amp;</span>str&gt;(<span class="kw-2">&amp;</span>[])<span class="question-mark">?</span>;
<span class="macro">assert_eq!</span>(<span class="number">0</span>, re.pattern_len());
<span class="kw">let </span>re = Regex::new_many(<span class="kw-2">&amp;</span>[<span class="string">"a"</span>, <span class="string">"b"</span>, <span class="string">"c"</span>])<span class="question-mark">?</span>;
<span class="macro">assert_eq!</span>(<span class="number">3</span>, re.pattern_len());
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.captures_len" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1671-1677">source</a><h4 class="code-header">pub fn <a href="#method.captures_len" class="fn">captures_len</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a></h4></section></summary><div class="docblock"><p>Returns the total number of capturing groups.</p>
<p>This includes the implicit capturing group corresponding to the
entire match. Therefore, the minimum value returned is <code>1</code>.</p>
<h5 id="example-20"><a href="#example-20">Example</a></h5>
<p>This shows a few patterns and how many capture groups they have.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>len = |pattern| {
Regex::new(pattern).map(|re| re.captures_len())
};
<span class="macro">assert_eq!</span>(<span class="number">1</span>, len(<span class="string">"a"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">2</span>, len(<span class="string">"(a)"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">3</span>, len(<span class="string">"(a)|(b)"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">5</span>, len(<span class="string">"(a)(b)|(c)(d)"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">2</span>, len(<span class="string">"(a)|b"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">2</span>, len(<span class="string">"a|(b)"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">2</span>, len(<span class="string">"(b)*"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">2</span>, len(<span class="string">"(b)+"</span>)<span class="question-mark">?</span>);
</code></pre></div>
<h5 id="example-multiple-patterns"><a href="#example-multiple-patterns">Example: multiple patterns</a></h5>
<p>This routine also works for multiple patterns. The total number is
the sum of the capture groups of each pattern.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>len = |patterns| {
Regex::new_many(patterns).map(|re| re.captures_len())
};
<span class="macro">assert_eq!</span>(<span class="number">2</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"a"</span>, <span class="string">"b"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">4</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"(a)"</span>, <span class="string">"(b)"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">6</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"(a)|(b)"</span>, <span class="string">"(c)|(d)"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">8</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"(a)(b)|(c)(d)"</span>, <span class="string">"(x)(y)"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">3</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"(a)"</span>, <span class="string">"b"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">3</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"a"</span>, <span class="string">"(b)"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">4</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"(a)"</span>, <span class="string">"(b)*"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="number">4</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"(a)+"</span>, <span class="string">"(b)+"</span>])<span class="question-mark">?</span>);
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.static_captures_len" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1740-1746">source</a><h4 class="code-header">pub fn <a href="#method.static_captures_len" class="fn">static_captures_len</a>(&amp;self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>&gt;</h4></section></summary><div class="docblock"><p>Returns the total number of capturing groups that appear in every
possible match.</p>
<p>If the number of capture groups can vary depending on the match, then
this returns <code>None</code>. That is, a value is only returned when the number
of matching groups is invariant or “static.”</p>
<p>Note that like <a href="struct.Regex.html#method.captures_len" title="method regex_automata::meta::Regex::captures_len"><code>Regex::captures_len</code></a>, this <strong>does</strong> include the
implicit capturing group corresponding to the entire match. Therefore,
when a non-None value is returned, it is guaranteed to be at least <code>1</code>.
Stated differently, a return value of <code>Some(0)</code> is impossible.</p>
<h5 id="example-21"><a href="#example-21">Example</a></h5>
<p>This shows a few cases where a static number of capture groups is
available and a few cases where it is not.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>len = |pattern| {
Regex::new(pattern).map(|re| re.static_captures_len())
};
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">1</span>), len(<span class="string">"a"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">2</span>), len(<span class="string">"(a)"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">2</span>), len(<span class="string">"(a)|(b)"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">3</span>), len(<span class="string">"(a)(b)|(c)(d)"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, len(<span class="string">"(a)|b"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, len(<span class="string">"a|(b)"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, len(<span class="string">"(b)*"</span>)<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">2</span>), len(<span class="string">"(b)+"</span>)<span class="question-mark">?</span>);
</code></pre></div>
<h5 id="example-multiple-patterns-1"><a href="#example-multiple-patterns-1">Example: multiple patterns</a></h5>
<p>This property extends to regexes with multiple patterns as well. In
order for their to be a static number of capture groups in this case,
every pattern must have the same static number.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="kw">let </span>len = |patterns| {
Regex::new_many(patterns).map(|re| re.static_captures_len())
};
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">1</span>), len(<span class="kw-2">&amp;</span>[<span class="string">"a"</span>, <span class="string">"b"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">2</span>), len(<span class="kw-2">&amp;</span>[<span class="string">"(a)"</span>, <span class="string">"(b)"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">2</span>), len(<span class="kw-2">&amp;</span>[<span class="string">"(a)|(b)"</span>, <span class="string">"(c)|(d)"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">3</span>), len(<span class="kw-2">&amp;</span>[<span class="string">"(a)(b)|(c)(d)"</span>, <span class="string">"(x)(y)"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"(a)"</span>, <span class="string">"b"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"a"</span>, <span class="string">"(b)"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, len(<span class="kw-2">&amp;</span>[<span class="string">"(a)"</span>, <span class="string">"(b)*"</span>])<span class="question-mark">?</span>);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(<span class="number">2</span>), len(<span class="kw-2">&amp;</span>[<span class="string">"(a)+"</span>, <span class="string">"(b)+"</span>])<span class="question-mark">?</span>);
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.group_info" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1812-1814">source</a><h4 class="code-header">pub fn <a href="#method.group_info" class="fn">group_info</a>(&amp;self) -&gt; &amp;<a class="struct" href="../util/captures/struct.GroupInfo.html" title="struct regex_automata::util::captures::GroupInfo">GroupInfo</a></h4></section></summary><div class="docblock"><p>Return information about the capture groups in this <code>Regex</code>.</p>
<p>A <code>GroupInfo</code> is an immutable object that can be cheaply cloned. It
is responsible for maintaining a mapping between the capture groups
in the concrete syntax of zero or more regex patterns and their
internal representation used by some of the regex matchers. It is also
responsible for maintaining a mapping between the name of each group
(if one exists) and its corresponding group index.</p>
<p>A <code>GroupInfo</code> is ultimately what is used to build a <a href="../util/captures/struct.Captures.html" title="struct regex_automata::util::captures::Captures"><code>Captures</code></a> value,
which is some mutable space where group offsets are stored as a result
of a search.</p>
<h5 id="example-22"><a href="#example-22">Example</a></h5>
<p>This shows some alternatives to <a href="struct.Regex.html#method.create_captures" title="method regex_automata::meta::Regex::create_captures"><code>Regex::create_captures</code></a>:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::{
meta::Regex,
util::captures::Captures,
Match, PatternID, Span,
};
<span class="kw">let </span>re = Regex::new(<span class="string">r"(?&lt;first&gt;[A-Z][a-z]+) (?&lt;last&gt;[A-Z][a-z]+)"</span>)<span class="question-mark">?</span>;
<span class="comment">// This is equivalent to Regex::create_captures. It stores matching
// offsets for all groups in the regex.
</span><span class="kw">let </span><span class="kw-2">mut </span>all = Captures::all(re.group_info().clone());
re.captures(<span class="string">"Bruce Springsteen"</span>, <span class="kw-2">&amp;mut </span>all);
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">17</span>)), all.get_match());
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Span::from(<span class="number">0</span>..<span class="number">5</span>)), all.get_group_by_name(<span class="string">"first"</span>));
<span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Span::from(<span class="number">6</span>..<span class="number">17</span>)), all.get_group_by_name(<span class="string">"last"</span>));
<span class="comment">// In this version, we only care about the implicit groups, which
// means offsets for the explicit groups will be unavailable. It can
// sometimes be faster to ask for fewer groups, since the underlying
// regex engine needs to do less work to keep track of them.
</span><span class="kw">let </span><span class="kw-2">mut </span>matches = Captures::matches(re.group_info().clone());
re.captures(<span class="string">"Bruce Springsteen"</span>, <span class="kw-2">&amp;mut </span>matches);
<span class="comment">// We still get the overall match info.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">0</span>, <span class="number">0</span>..<span class="number">17</span>)), matches.get_match());
<span class="comment">// But now the explicit groups are unavailable.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, matches.get_group_by_name(<span class="string">"first"</span>));
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, matches.get_group_by_name(<span class="string">"last"</span>));
<span class="comment">// Finally, in this version, we don't ask to keep track of offsets for
// *any* groups. All we get back is whether a match occurred, and if
// so, the ID of the pattern that matched.
</span><span class="kw">let </span><span class="kw-2">mut </span>empty = Captures::empty(re.group_info().clone());
re.captures(<span class="string">"Bruce Springsteen"</span>, <span class="kw-2">&amp;mut </span>empty);
<span class="comment">// it's a match!
</span><span class="macro">assert!</span>(empty.is_match());
<span class="comment">// for pattern ID 0
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(PatternID::ZERO), empty.pattern());
<span class="comment">// Match offsets are unavailable.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, empty.get_match());
<span class="comment">// And of course, explicit groups are unavailable too.
</span><span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, empty.get_group_by_name(<span class="string">"first"</span>));
<span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, empty.get_group_by_name(<span class="string">"last"</span>));
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.get_config" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1821-1823">source</a><h4 class="code-header">pub fn <a href="#method.get_config" class="fn">get_config</a>(&amp;self) -&gt; &amp;<a class="struct" href="struct.Config.html" title="struct regex_automata::meta::Config">Config</a></h4></section></summary><div class="docblock"><p>Returns the configuration object used to build this <code>Regex</code>.</p>
<p>If no configuration object was explicitly passed, then the
configuration returned represents the default.</p>
</div></details><details class="toggle method-toggle" open><summary><section id="method.is_accelerated" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1872-1874">source</a><h4 class="code-header">pub fn <a href="#method.is_accelerated" class="fn">is_accelerated</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Returns true if this regex has a high chance of being “accelerated.”</p>
<p>The precise meaning of “accelerated” is specifically left unspecified,
but the general meaning is that the search is a high likelihood of
running faster than than a character-at-a-time loop inside a standard
regex engine.</p>
<p>When a regex is accelerated, it is only a <em>probabilistic</em> claim. That
is, just because the regex is believed to be accelerated, that doesn’t
mean it will definitely execute searches very fast. Similarly, if a
regex is <em>not</em> accelerated, that is also a probabilistic claim. That
is, a regex for which <code>is_accelerated</code> returns <code>false</code> could still run
searches more quickly than a regex for which <code>is_accelerated</code> returns
<code>true</code>.</p>
<p>Whether a regex is marked as accelerated or not is dependent on
implementations details that may change in a semver compatible release.
That is, a regex that is accelerated in a <code>x.y.1</code> release might not be
accelerated in a <code>x.y.2</code> release.</p>
<p>Basically, the value of acceleration boils down to a hedge: a hodge
podge of internal heuristics combine to make a probabilistic guess
that this regex search may run “fast.” The value in knowing this from
a caller’s perspective is that it may act as a signal that no further
work should be done to accelerate a search. For example, a grep-like
tool might try to do some extra work extracting literals from a regex
to create its own heuristic acceleration strategies. But it might
choose to defer to this crate’s acceleration strategy if one exists.
This routine permits querying whether such a strategy is active for a
particular regex.</p>
<h5 id="example-23"><a href="#example-23">Example</a></h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>regex_automata::meta::Regex;
<span class="comment">// A simple literal is very likely to be accelerated.
</span><span class="kw">let </span>re = Regex::new(<span class="string">r"foo"</span>)<span class="question-mark">?</span>;
<span class="macro">assert!</span>(re.is_accelerated());
<span class="comment">// A regex with no literals is likely to not be accelerated.
</span><span class="kw">let </span>re = Regex::new(<span class="string">r"\w"</span>)<span class="question-mark">?</span>;
<span class="macro">assert!</span>(!re.is_accelerated());
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.memory_usage" class="method"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1894-1896">source</a><h4 class="code-header">pub fn <a href="#method.memory_usage" class="fn">memory_usage</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a></h4></section></summary><div class="docblock"><p>Return the total approximate heap memory, in bytes, used by this <code>Regex</code>.</p>
<p>Note that currently, there is no high level configuration for setting
a limit on the specific value returned by this routine. Instead, the
following routines can be used to control heap memory at a bit of a
lower level:</p>
<ul>
<li><a href="struct.Config.html#method.nfa_size_limit" title="method regex_automata::meta::Config::nfa_size_limit"><code>Config::nfa_size_limit</code></a> controls how big <em>any</em> of the NFAs are
allowed to be.</li>
<li><a href="struct.Config.html#method.onepass_size_limit" title="method regex_automata::meta::Config::onepass_size_limit"><code>Config::onepass_size_limit</code></a> controls how big the one-pass DFA is
allowed to be.</li>
<li><a href="struct.Config.html#method.hybrid_cache_capacity" title="method regex_automata::meta::Config::hybrid_cache_capacity"><code>Config::hybrid_cache_capacity</code></a> controls how much memory the lazy
DFA is permitted to allocate to store its transition table.</li>
<li><a href="struct.Config.html#method.dfa_size_limit" title="method regex_automata::meta::Config::dfa_size_limit"><code>Config::dfa_size_limit</code></a> controls how big a fully compiled DFA is
allowed to be.</li>
<li><a href="struct.Config.html#method.dfa_state_limit" title="method regex_automata::meta::Config::dfa_state_limit"><code>Config::dfa_state_limit</code></a> controls the conditions under which the
meta regex engine will even attempt to build a fully compiled DFA.</li>
</ul>
</div></details></div></details></div><h2 id="trait-implementations" class="section-header">Trait Implementations<a href="#trait-implementations" class="anchor">§</a></h2><div id="trait-implementations-list"><details class="toggle implementors-toggle" open><summary><section id="impl-Clone-for-Regex" class="impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1899-1909">source</a><a href="#impl-Clone-for-Regex" class="anchor">§</a><h3 class="code-header">impl <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/clone/trait.Clone.html" title="trait core::clone::Clone">Clone</a> for <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.clone" class="method trait-impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#1900-1908">source</a><a href="#method.clone" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/clone/trait.Clone.html#tymethod.clone" class="fn">clone</a>(&amp;self) -&gt; <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h4></section></summary><div class='docblock'>Returns a copy of the value. <a href="https://doc.rust-lang.org/1.76.0/core/clone/trait.Clone.html#tymethod.clone">Read more</a></div></details><details class="toggle method-toggle" open><summary><section id="method.clone_from" class="method trait-impl"><span class="rightside"><span class="since" title="Stable since Rust version 1.0.0">1.0.0</span> · <a class="src" href="https://doc.rust-lang.org/1.76.0/src/core/clone.rs.html#169">source</a></span><a href="#method.clone_from" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/clone/trait.Clone.html#method.clone_from" class="fn">clone_from</a>(&amp;mut self, source: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&amp;Self</a>)</h4></section></summary><div class='docblock'>Performs copy-assignment from <code>source</code>. <a href="https://doc.rust-lang.org/1.76.0/core/clone/trait.Clone.html#method.clone_from">Read more</a></div></details></div></details><details class="toggle implementors-toggle" open><summary><section id="impl-Debug-for-Regex" class="impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#234">source</a><a href="#impl-Debug-for-Regex" class="anchor">§</a><h3 class="code-header">impl <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a> for <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.fmt" class="method trait-impl"><a class="src rightside" href="../../src/regex_automata/meta/regex.rs.html#234">source</a><a href="#method.fmt" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html#tymethod.fmt" class="fn">fmt</a>(&amp;self, f: &amp;mut <a class="struct" href="https://doc.rust-lang.org/1.76.0/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>&lt;'_&gt;) -&gt; <a class="type" href="https://doc.rust-lang.org/1.76.0/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></h4></section></summary><div class='docblock'>Formats the value using the given formatter. <a href="https://doc.rust-lang.org/1.76.0/core/fmt/trait.Debug.html#tymethod.fmt">Read more</a></div></details></div></details></div><h2 id="synthetic-implementations" class="section-header">Auto Trait Implementations<a href="#synthetic-implementations" class="anchor">§</a></h2><div id="synthetic-implementations-list"><section id="impl-RefUnwindSafe-for-Regex" class="impl"><a href="#impl-RefUnwindSafe-for-Regex" class="anchor">§</a><h3 class="code-header">impl <a class
T: 'static + ?<a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.type_id" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/any.rs.html#141">source</a><a href="#method.type_id" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/any/trait.Any.html#tymethod.type_id" class="fn">type_id</a>(&amp;self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/core/any/struct.TypeId.html" title="struct core::any::TypeId">TypeId</a></h4></section></summary><div class='docblock'>Gets the <code>TypeId</code> of <code>self</code>. <a href="https://doc.rust-lang.org/1.76.0/core/any/trait.Any.html#tymethod.type_id">Read more</a></div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Borrow%3CT%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/borrow.rs.html#208">source</a><a href="#impl-Borrow%3CT%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/borrow/trait.Borrow.html" title="trait core::borrow::Borrow">Borrow</a>&lt;T&gt; for T<div class="where">where
T: ?<a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.borrow" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/borrow.rs.html#210">source</a><a href="#method.borrow" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/borrow/trait.Borrow.html#tymethod.borrow" class="fn">borrow</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&amp;T</a></h4></section></summary><div class='docblock'>Immutably borrows from an owned value. <a href="https://doc.rust-lang.org/1.76.0/core/borrow/trait.Borrow.html#tymethod.borrow">Read more</a></div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-BorrowMut%3CT%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/borrow.rs.html#216">source</a><a href="#impl-BorrowMut%3CT%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/borrow/trait.BorrowMut.html" title="trait core::borrow::BorrowMut">BorrowMut</a>&lt;T&gt; for T<div class="where">where
T: ?<a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.borrow_mut" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/borrow.rs.html#217">source</a><a href="#method.borrow_mut" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut" class="fn">borrow_mut</a>(&amp;mut self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&amp;mut T</a></h4></section></summary><div class='docblock'>Mutably borrows from an owned value. <a href="https://doc.rust-lang.org/1.76.0/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut">Read more</a></div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-From%3CT%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/convert/mod.rs.html#763">source</a><a href="#impl-From%3CT%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;T&gt; for T</h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.from" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/convert/mod.rs.html#766">source</a><a href="#method.from" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/convert/trait.From.html#tymethod.from" class="fn">from</a>(t: T) -&gt; T</h4></section></summary><div class="docblock"><p>Returns the argument unchanged.</p>
</div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Into%3CU%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/convert/mod.rs.html#747-749">source</a><a href="#impl-Into%3CU%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;U&gt; for T<div class="where">where
U: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;T&gt;,</div></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.into" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/convert/mod.rs.html#756">source</a><a href="#method.into" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html#tymethod.into" class="fn">into</a>(self) -&gt; U</h4></section></summary><div class="docblock"><p>Calls <code>U::from(self)</code>.</p>
<p>That is, this conversion is whatever the implementation of
<code><a href="https://doc.rust-lang.org/1.76.0/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;T&gt; for U</code> chooses to do.</p>
</div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-ToOwned-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/alloc/borrow.rs.html#83-85">source</a><a href="#impl-ToOwned-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.76.0/alloc/borrow/trait.ToOwned.html" title="trait alloc::borrow::ToOwned">ToOwned</a> for T<div class="where">where
T: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/clone/trait.Clone.html" title="trait core::clone::Clone">Clone</a>,</div></h3></section></summary><div class="impl-items"><details class="toggle" open><summary><section id="associatedtype.Owned" class="associatedtype trait-impl"><a href="#associatedtype.Owned" class="anchor">§</a><h4 class="code-header">type <a href="https://doc.rust-lang.org/1.76.0/alloc/borrow/trait.ToOwned.html#associatedtype.Owned" class="associatedtype">Owned</a> = T</h4></section></summary><div class='docblock'>The resulting type after obtaining ownership.</div></details><details class="toggle method-toggle" open><summary><section id="method.to_owned" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/alloc/borrow.rs.html#88">source</a><a href="#method.to_owned" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/alloc/borrow/trait.ToOwned.html#tymethod.to_owned" class="fn">to_owned</a>(&amp;self) -&gt; T</h4></section></summary><div class='docblock'>Creates owned data from borrowed data, usually by cloning. <a href="https://doc.rust-lang.org/1.76.0/alloc/borrow/trait.ToOwned.html#tymethod.to_owned">Read more</a></div></details><details class="toggle method-toggle" open><summary><section id="method.clone_into" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/alloc/borrow.rs.html#92">source</a><a href="#method.clone_into" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/alloc/borrow/trait.ToOwned.html#method.clone_into" class="fn">clone_into</a>(&amp;self, target: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&amp;mut T</a>)</h4></section></summary><div class='docblock'>Uses borrowed data to replace owned data, usually by cloning. <a href="https://doc.rust-lang.org/1.76.0/alloc/borrow/trait.ToOwned.html#method.clone_into">Read more</a></div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-TryFrom%3CU%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/convert/mod.rs.html#803-805">source</a><a href="#impl-TryFrom%3CU%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;U&gt; for T<div class="where">where
U: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;T&gt;,</div></h3></section></summary><div class="impl-items"><details class="toggle" open><summary><section id="associatedtype.Error" class="associatedtype trait-impl"><a href="#associatedtype.Error" class="anchor">§</a><h4 class="code-header">type <a href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html#associatedtype.Error" class="associatedtype">Error</a> = <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/convert/enum.Infallible.html" title="enum core::convert::Infallible">Infallible</a></h4></section></summary><div class='docblock'>The type returned in the event of a conversion error.</div></details><details class="toggle method-toggle" open><summary><section id="method.try_from" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/convert/mod.rs.html#810">source</a><a href="#method.try_from" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html#tymethod.try_from" class="fn">try_from</a>(value: U) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;T, &lt;T as <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;U&gt;&gt;::<a class="associatedtype" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>&gt;</h4></section></summary><div class='docblock'>Performs the conversion.</div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-TryInto%3CU%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/convert/mod.rs.html#788-790">source</a><a href="#impl-TryInto%3CU%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryInto.html" title="trait core::convert::TryInto">TryInto</a>&lt;U&gt; for T<div class="where">where
U: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;,</div></h3></section></summary><div class="impl-items"><details class="toggle" open><summary><section id="associatedtype.Error-1" class="associatedtype trait-impl"><a href="#associatedtype.Error-1" class="anchor">§</a><h4 class="code-header">type <a href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryInto.html#associatedtype.Error" class="associatedtype">Error</a> = &lt;U as <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;&gt;::<a class="associatedtype" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a></h4></section></summary><div class='docblock'>The type returned in the event of a conversion error.</div></details><details class="toggle method-toggle" open><summary><section id="method.try_into" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/convert/mod.rs.html#795">source</a><a href="#method.try_into" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryInto.html#tymethod.try_into" class="fn">try_into</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;U, &lt;U as <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;&gt;::<a class="associatedtype" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>&gt;</h4></section></summary><div class='docblock'>Performs the conversion.</div></details></div></details></div><script type="text/json" id="notable-traits-data">{"CapturesMatches<'r, 'h>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.CapturesMatches.html\" title=\"struct regex_automata::meta::CapturesMatches\">CapturesMatches</a>&lt;'r, 'h&gt;</code></h3><pre><code><div class=\"where\">impl&lt;'r, 'h&gt; <a class=\"trait\" href=\"https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html\" title=\"trait core::iter::traits::iterator::Iterator\">Iterator</a> for <a class=\"struct\" href=\"struct.CapturesMatches.html\" title=\"struct regex_automata::meta::CapturesMatches\">CapturesMatches</a>&lt;'r, 'h&gt;</div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item\" class=\"associatedtype\">Item</a> = <a class=\"struct\" href=\"../util/captures/struct.Captures.html\" title=\"struct regex_automata::util::captures::Captures\">Captures</a>;</div>","FindMatches<'r, 'h>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.FindMatches.html\" title=\"struct regex_automata::meta::FindMatches\">FindMatches</a>&lt;'r, 'h&gt;</code></h3><pre><code><div class=\"where\">impl&lt;'r, 'h&gt; <a class=\"trait\" href=\"https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html\" title=\"trait core::iter::traits::iterator::Iterator\">Iterator</a> for <a class=\"struct\" href=\"struct.FindMatches.html\" title=\"struct regex_automata::meta::FindMatches\">FindMatches</a>&lt;'r, 'h&gt;</div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item\" class=\"associatedtype\">Item</a> = <a class=\"struct\" href=\"../struct.Match.html\" title=\"struct regex_automata::Match\">Match</a>;</div>","Split<'r, 'h>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.Split.html\" title=\"struct regex_automata::meta::Split\">Split</a>&lt;'r, 'h&gt;</code></h3><pre><code><div class=\"where\">impl&lt;'r, 'h&gt; <a class=\"trait\" href=\"https://doc.rust-lang.org/1.76.0/core/iter/tr
Reference in a new issue Copy permalink