mirror of
https://github.com/edg-l/edlang.git
synced 2024-10-18 15:08:17 +00:00
1273 lines
154 KiB
HTML
1273 lines
154 KiB
HTML
<!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">☰</button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../regex_automata/index.html">regex_automata</a><span class="version">0.4.6</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.static_captures_len">static_captures_len</a></li><li><a href="#method.which_overlapping_matches">which_overlapping_matches</a></li><li><a href="#method.which_overlapping_matches_with">which_overlapping_matches_with</a></li></ul><h3><a href="#trait-implementations">Trait Implementations</a></h3><ul class="block trait-implementation"><li><a href="#impl-Clone-for-Regex">Clone</a></li><li><a href="#impl-Debug-for-Regex">Debug</a></li></ul><h3><a href="#synthetic-implementations">Auto Trait Implementations</a></h3><ul class="block synthetic-implementation"><li><a href="#impl-RefUnwindSafe-for-Regex">RefUnwindSafe</a></li><li><a href="#impl-Send-for-Regex">Send</a></li><li><a href="#impl-Sync-for-Regex">Sync</a></li><li><a href="#impl-Unpin-for-Regex">Unpin</a></li><li><a href="#impl-UnwindSafe-for-Regex">UnwindSafe</a></li></ul><h3><a href="#blanket-implementations">Blanket Implementations</a></h3><ul class="block blanket-implementation"><li><a href="#impl-Any-for-T">Any</a></li><li><a href="#impl-Borrow%3CT%3E-for-T">Borrow<T></a></li><li><a href="#impl-BorrowMut%3CT%3E-for-T">BorrowMut<T></a></li><li><a href="#impl-From%3CT%3E-for-T">From<T></a></li><li><a href="#impl-Into%3CU%3E-for-T">Into<U></a></li><li><a href="#impl-ToOwned-for-T">ToOwned</a></li><li><a href="#impl-TryFrom%3CU%3E-for-T">TryFrom<U></a></li><li><a href="#impl-TryInto%3CU%3E-for-T">TryInto<U></a></li></ul></section><h2><a href="index.html">In regex_automata::meta</a></h2></div></nav><div class="sidebar-resizer"></div>
|
||
<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>−</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="../hybrid/index.html" title="mod regex_automata::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">&</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: &<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.str.html">str</a>) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<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>></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><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><<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.str.html">str</a>>>(patterns: &<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.slice.html">[P]</a>) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<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>></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">&</span>[
|
||
<span class="string">r"[[:space:]]"</span>,
|
||
<span class="string">r"[A-Za-z0-9][A-Za-z0-9_]+"</span>,
|
||
<span class="string">r"->"</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) -> bool;"</span>;
|
||
<span class="kw">let </span>matches: Vec<Match> = 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">// '->'
|
||
</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<space>[[:space:]])|(?P<ident>[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">&</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::<<span class="kw-2">&</span>str>(<span class="kw-2">&</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>() -> <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><<<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>() -> <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><'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><<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'h>>>(&self, input: I) -> <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><'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><<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'h>>>(&self, input: I) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="../struct.Match.html" title="struct regex_automata::Match">Match</a>></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><'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><<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'h>>>(&self, input: I, caps: &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">&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><'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><<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'h>>>(
|
||
&'r self,
|
||
input: I
|
||
) -> <a class="struct" href="struct.FindMatches.html" title="struct regex_automata::meta::FindMatches">FindMatches</a><'r, 'h> <a href="#" class="tooltip" data-notable-ty="FindMatches<'r, 'h>">ⓘ</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<Match> = 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><'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><<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'h>>>(
|
||
&'r self,
|
||
input: I
|
||
) -> <a class="struct" href="struct.CapturesMatches.html" title="struct regex_automata::meta::CapturesMatches">CapturesMatches</a><'r, 'h> <a href="#" class="tooltip" data-notable-ty="CapturesMatches<'r, 'h>">ⓘ</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<numbers>[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<Span> = 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><'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><<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'h>>>(&'r self, input: I) -> <a class="struct" href="struct.Split.html" title="struct regex_automata::meta::Split">Split</a><'r, 'h> <a href="#" class="tooltip" data-notable-ty="Split<'r, 'h>">ⓘ</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<<span class="kw-2">&</span>str> = re.split(hay).map(|span| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>[u8]> = re.split(hay).map(|sp| <span class="kw-2">&</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 &[u8; 3] instead of &[u8].
|
||
</span><span class="kw-2">&</span>[][..], <span class="kw-2">&</span>[<span class="string">b'\xE2'</span>][..], <span class="kw-2">&</span>[<span class="string">b'\x98'</span>][..], <span class="kw-2">&</span>[<span class="string">b'\x83'</span>][..], <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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>["a", "b", "c"]</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<<span class="kw-2">&</span>str> = re.split(hay).map(|sp| <span class="kw-2">&</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><'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><<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'h>>>(
|
||
&'r self,
|
||
input: I,
|
||
limit: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>
|
||
) -> <a class="struct" href="struct.SplitN.html" title="struct regex_automata::meta::SplitN">SplitN</a><'r, 'h> <a href="#" class="tooltip" data-notable-ty="SplitN<'r, 'h>">ⓘ</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<<span class="kw-2">&</span>str> =
|
||
re.splitn(hay, <span class="number">3</span>).map(|span| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.splitn(hay, <span class="number">3</span>).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.splitn(hay, <span class="number">3</span>).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.splitn(hay, <span class="number">3</span>).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.splitn(hay, <span class="number">2</span>).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.splitn(hay, <span class="number">1</span>).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.splitn(hay, <span class="number">2</span>).map(|sp| <span class="kw-2">&</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<<span class="kw-2">&</span>str> = re.splitn(hay, <span class="number">0</span>).map(|sp| <span class="kw-2">&</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>(&self, input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="../struct.Match.html" title="struct regex_automata::Match">Match</a>></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>&Input</code>
|
||
instead of an <code>Into<Input></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">&</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>(&self, input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="../struct.HalfMatch.html" title="struct regex_automata::HalfMatch">HalfMatch</a>></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">&</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>(&self, input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>, caps: &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>&Input</code>
|
||
instead of an <code>Into<Input></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">&</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">&</span>Input::new(haystack), <span class="kw-2">&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">&</span>input, <span class="kw-2">&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">&</span>haystack[<span class="number">3</span>..<span class="number">6</span>]);
|
||
re.search_captures(<span class="kw-2">&</span>input, <span class="kw-2">&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">&</span>input, <span class="kw-2">&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>(
|
||
&self,
|
||
input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>,
|
||
slots: &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><<a class="struct" href="../util/primitives/struct.NonMaxUsize.html" title="struct regex_automata::util::primitives::NonMaxUsize">NonMaxUsize</a>>]
|
||
) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="../struct.PatternID.html" title="struct regex_automata::PatternID">PatternID</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 <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">&</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">&</span>input, <span class="kw-2">&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>(
|
||
&self,
|
||
input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>,
|
||
patset: &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">&</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">&</span>input, <span class="kw-2">&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<usize> = 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>(&self, cache: &mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>, input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="../struct.Match.html" title="struct regex_automata::Match">Match</a>></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">&mut </span>cache, <span class="kw-2">&</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>(
|
||
&self,
|
||
cache: &mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>,
|
||
input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>
|
||
) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="../struct.HalfMatch.html" title="struct regex_automata::HalfMatch">HalfMatch</a>></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">&mut </span>cache, <span class="kw-2">&</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>(
|
||
&self,
|
||
cache: &mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>,
|
||
input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>,
|
||
caps: &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">&</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">&mut </span>cache, <span class="kw-2">&</span>Input::new(haystack), <span class="kw-2">&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">&mut </span>cache, <span class="kw-2">&</span>input, <span class="kw-2">&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">&</span>haystack[<span class="number">3</span>..<span class="number">6</span>]);
|
||
re.search_captures_with(<span class="kw-2">&mut </span>cache, <span class="kw-2">&</span>input, <span class="kw-2">&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">&mut </span>cache, <span class="kw-2">&</span>input, <span class="kw-2">&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>(
|
||
&self,
|
||
cache: &mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>,
|
||
input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>,
|
||
slots: &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><<a class="struct" href="../util/primitives/struct.NonMaxUsize.html" title="struct regex_automata::util::primitives::NonMaxUsize">NonMaxUsize</a>>]
|
||
) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="../struct.PatternID.html" title="struct regex_automata::PatternID">PatternID</a>></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">&</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">&mut </span>cache, <span class="kw-2">&</span>input, <span class="kw-2">&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>(
|
||
&self,
|
||
cache: &mut <a class="struct" href="struct.Cache.html" title="struct regex_automata::meta::Cache">Cache</a>,
|
||
input: &<a class="struct" href="../struct.Input.html" title="struct regex_automata::Input">Input</a><'_>,
|
||
patset: &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">&</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">&mut </span>cache, <span class="kw-2">&</span>input, <span class="kw-2">&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<usize> = 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>(&self) -> <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"(?<first>[A-Z][a-z]+) (?<last>[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">&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">&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">&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>(&self) -> <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">&mut </span>cache, <span class="kw-2">&</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>(&self) -> <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::<<span class="kw-2">&</span>str>(<span class="kw-2">&</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">&</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>(&self) -> <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">&</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">&</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">&</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">&</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">&</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">&</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">&</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">&</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>(&self) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<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 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">&</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">&</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">&</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">&</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">&</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">&</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">&</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">&</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>(&self) -> &<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"(?<first>[A-Z][a-z]+) (?<last>[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">&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">&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">&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>(&self) -> &<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>(&self) -> <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>(&self) -> <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>(&self) -> <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>(&mut self, source: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&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>(&self, f: &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><'_>) -> <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="trait" href="https://doc.rust-lang.org/1.76.0/core/panic/unwind_safe/trait.RefUnwindSafe.html" title="trait core::panic::unwind_safe::RefUnwindSafe">RefUnwindSafe</a> for <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section><section id="impl-Send-for-Regex" class="impl"><a href="#impl-Send-for-Regex" class="anchor">§</a><h3 class="code-header">impl <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Send.html" title="trait core::marker::Send">Send</a> for <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section><section id="impl-Sync-for-Regex" class="impl"><a href="#impl-Sync-for-Regex" class="anchor">§</a><h3 class="code-header">impl <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sync.html" title="trait core::marker::Sync">Sync</a> for <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section><section id="impl-Unpin-for-Regex" class="impl"><a href="#impl-Unpin-for-Regex" class="anchor">§</a><h3 class="code-header">impl <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Unpin.html" title="trait core::marker::Unpin">Unpin</a> for <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section><section id="impl-UnwindSafe-for-Regex" class="impl"><a href="#impl-UnwindSafe-for-Regex" class="anchor">§</a><h3 class="code-header">impl <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/panic/unwind_safe/trait.UnwindSafe.html" title="trait core::panic::unwind_safe::UnwindSafe">UnwindSafe</a> for <a class="struct" href="struct.Regex.html" title="struct regex_automata::meta::Regex">Regex</a></h3></section></div><h2 id="blanket-implementations" class="section-header">Blanket Implementations<a href="#blanket-implementations" class="anchor">§</a></h2><div id="blanket-implementations-list"><details class="toggle implementors-toggle"><summary><section id="impl-Any-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.76.0/src/core/any.rs.html#140">source</a><a href="#impl-Any-for-T" class="anchor">§</a><h3 class="code-header">impl<T> <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/any/trait.Any.html" title="trait core::any::Any">Any</a> for T<div class="where">where
|
||
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>(&self) -> <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<T> <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/borrow/trait.Borrow.html" title="trait core::borrow::Borrow">Borrow</a><T> 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>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&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<T> <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/borrow/trait.BorrowMut.html" title="trait core::borrow::BorrowMut">BorrowMut</a><T> 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>(&mut self) -> <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&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<T> <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.From.html" title="trait core::convert::From">From</a><T> 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) -> 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<T, 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><U> 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><T>,</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) -> 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><T> 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<T> <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>(&self) -> 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>(&self, target: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.reference.html">&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<T, 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><U> 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><T>,</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) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><T, <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><U>>::<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'>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<T, U> <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.TryInto.html" title="trait core::convert::TryInto">TryInto</a><U> 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><T>,</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> = <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><T>>::<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) -> <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a><U, <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><T>>::<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'>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><'r, 'h></code></h3><pre><code><div class=\"where\">impl<'r, 'h> <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><'r, 'h></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><'r, 'h></code></h3><pre><code><div class=\"where\">impl<'r, 'h> <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><'r, 'h></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><'r, 'h></code></h3><pre><code><div class=\"where\">impl<'r, 'h> <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.Split.html\" title=\"struct regex_automata::meta::Split\">Split</a><'r, 'h></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.Span.html\" title=\"struct regex_automata::Span\">Span</a>;</div>","SplitN<'r, 'h>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.SplitN.html\" title=\"struct regex_automata::meta::SplitN\">SplitN</a><'r, 'h></code></h3><pre><code><div class=\"where\">impl<'r, 'h> <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.SplitN.html\" title=\"struct regex_automata::meta::SplitN\">SplitN</a><'r, 'h></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.Span.html\" title=\"struct regex_automata::Span\">Span</a>;</div>"}</script></section></div></main></body></html> |