<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="A hybrid NFA/DFA (also called a “lazy DFA”) for regex searching."><title>DFA in regex_automata::hybrid::dfa - Rust</title><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../../../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><linkrel="stylesheet"href="../../../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../../../static.files/rustdoc-5bc39a1768837dd0.css"><metaname="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.77.0 (aedd173a2 2024-03-17)"data-channel="1.77.0"data-search-js="search-dd67cee4cfa65049.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../../../static.files/storage-4c98445ec4002617.js"></script><scriptdefersrc="sidebar-items.js"></script><scriptdefersrc="../../../static.files/main-48f368f3872407c8.js"></script><noscript><linkrel="stylesheet"href="../../../static.files/noscript-04d5337699b92874.css"></noscript><linkrel="alternate icon"type="image/png"href="../../../static.files/favicon-16x16-8b506e7a72182f1c.png"><linkrel="alternate icon"type="image/png"href="../../../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../../../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc struct"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle"title="show sidebar"></button></nav><navclass="sidebar"><divclass="sidebar-crate"><h2><ahref="../../../regex_automata/index.html">regex_automata</a><spanclass="version">0.4.6</span></h2></div><h2class="location"><ahref="#">DFA</a></h2><divclass="sidebar-elems"><section><h3><ahref="#implementations">Methods</a></h3><ulclass="block method"><li><ahref="#method.always_match">always_match</a></li><li><ahref="#method.builder">builder</a></li><li><ahref="#method.byte_classes">byte_classes</a></li><li><ahref="#method.config">config</a></li><li><ahref="#method.create_cache">create_cache</a></li><li><ahref="#method.get_config">get_config</a></li><li><ahref="#method.get_nfa">get_nfa</a></li><li><ahref="#method.match_len">match_len</a></li><li><ahref="#method.match_pattern">match_pattern</a></li><li><ahref="#method.memory_usage">memory_usage</a></li><li><ahref="#method.never_match">never_match</a></li><li><ahref="#method.new">new</a></li><li><ahref="#method.new_many">new_many</a></li><li><ahref="#method.next_eoi_state">next_eoi_state</a></li><li><ahref="#method.next_state">next_state</a></li><li><ahref="#method.next_state_untagged">next_state_untagged</a></li><li><ahref="#method.next_state_untagged_unchecked">next_state_untagged_unchecked</a></li><li><ahref="#method.pattern_len">pattern_len</a></li><li><ahref="#method.reset_cache">reset_cache</a></li><li><ahref="#method.start_state">start_state</a></li><li><ahref="#method.start_state_forward">start_state_forward</a></li><li><ahref="#method.start_state_reverse">start_state_reverse</a></li><li><ahref="#method.try_search_fwd">try_search_fwd</a></li><li><ahref="#method.try_search_overlapping_fwd">try_search_overlapping_fwd</a></li><li><ahref="#metho
<main><divclass="width-limiter"><navclass="sub"><formclass="search-form"><span></span><divid="sidebar-button"tabindex="-1"><ahref="../../../regex_automata/all.html"title="show sidebar"></a></div><inputclass="search-input"name="search"aria-label="Run search in the documentation"autocomplete="off"spellcheck="false"placeholder="Click or press ‘S’ to search, ‘?’ for more options…"type="search"><divid="help-button"tabindex="-1"><ahref="../../../help.html"title="help">?</a></div><divid="settings-menu"tabindex="-1"><ahref="../../../settings.html"title="settings"><imgwidth="22"height="22"alt="Change settings"src="../../../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><sectionid="main-content"class="content"><divclass="main-heading"><h1>Struct <ahref="../../index.html">regex_automata</a>::<wbr><ahref="../index.html">hybrid</a>::<wbr><ahref="index.html">dfa</a>::<wbr><aclass="struct"href="#">DFA</a><buttonid="copy-path"title="Copy item path to clipboard"><imgsrc="../../../static.files/clipboard-7571035ce49a181d.svg"width="19"height="18"alt="Copy item path"></button></h1><spanclass="out-of-band"><aclass="src"href="../../../src/regex_automata/hybrid/dfa.rs.html#118-126">source</a> · <buttonid="toggle-all-docs"title="collapse all docs">[<span>−</span>]</button></span></div><preclass="rust item-decl"><code>pub struct DFA { <spanclass="comment">/* private fields */</span> }</code></pre><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>A hybrid NFA/DFA (also called a “lazy DFA”) for regex searching.</p>
<p>A lazy DFA is a DFA that builds itself at search time. It otherwise has
very similar characteristics as a <ahref="crate::dfa::dense::DFA"><code>dense::DFA</code></a>.
Indeed, both support precisely the same regex features with precisely the
same semantics.</p>
<p>Where as a <code>dense::DFA</code> must be completely built to handle any input before
it may be used for search, a lazy DFA starts off effectively empty. During
a search, a lazy DFA will build itself depending on whether it has already
computed the next transition or not. If it has, then it looks a lot like
a <code>dense::DFA</code> internally: it does a very fast table based access to find
the next transition. Otherwise, if the state hasn’t been computed, then it
does determinization <em>for that specific transition</em> to compute the next DFA
state.</p>
<p>The main selling point of a lazy DFA is that, in practice, it has
the performance profile of a <code>dense::DFA</code> without the weakness of it
taking worst case exponential time to build. Indeed, for each byte of
input, the lazy DFA will construct as most one new DFA state. Thus, a
lazy DFA achieves worst case <code>O(mn)</code> time for regex search (where <code>m ~ pattern.len()</code> and <code>n ~ haystack.len()</code>).</p>
<p>The main downsides of a lazy DFA are:</p>
<ol>
<li>It requires mutable “cache” space during search. This is where the
transition table, among other things, is stored.</li>
<li>In pathological cases (e.g., if the cache is too small), it will run
out of room and either require a bigger cache capacity or will repeatedly
clear the cache and thus repeatedly regenerate DFA states. Overall, this
will tend to be slower than a typical NFA simulation.</li>
</div></details><h2id="implementations"class="section-header">Implementations<ahref="#implementations"class="anchor">§</a></h2><divid="implementations-list"><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-DFA"class="impl"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#128-455">source</a><ahref="#impl-DFA"class="anchor">§</a><h3class="code-header">impl <aclass="struct"href="struct.DFA.html"title="struct regex_automata::hybrid::dfa::DFA">DFA</a></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.new"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#151-153">source</a><h4class="code-header">pub fn <ahref="#method.new"class="fn">new</a>(pattern: &<aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.str.html">str</a>) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="struct.DFA.html"title="struct regex_automata::hybrid::dfa::DFA">DFA</a>, <aclass="struct"href="../struct.BuildError.html"title="struct regex_automata::hybrid::BuildError">BuildError</a>></h4></section></summary><divclass="docblock"><p>Parse the given regular expression using a default configuration and
<p>If you want a non-default configuration, then use the <ahref="struct.Builder.html"title="struct regex_automata::hybrid::dfa::Builder"><code>Builder</code></a> to
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.new_many"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#177-179">source</a><h4class="code-header">pub fn <ahref="#method.new_many"class="fn">new_many</a><P: <aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.AsRef.html"title="trait core::convert::AsRef">AsRef</a><<aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.str.html">str</a>>>(patterns: &<aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.slice.html">[P]</a>) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="struct.DFA.html"title="struct regex_automata::hybrid::dfa::DFA">DFA</a>, <aclass="struct"href="../struct.BuildError.html"title="struct regex_automata::hybrid::BuildError">BuildError</a>></h4></section></summary><divclass="docblock"><p>Parse the given regular expressions using a default configuration and
<p>If you want a non-default configuration, then use the <ahref="struct.Builder.html"title="struct regex_automata::hybrid::dfa::Builder"><code>Builder</code></a> to
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.always_match"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#200-203">source</a><h4class="code-header">pub fn <ahref="#method.always_match"class="fn">always_match</a>() -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="struct.DFA.html"title="struct regex_automata::hybrid::dfa::DFA">DFA</a>, <aclass="struct"href="../struct.BuildError.html"title="struct regex_automata::hybrid::BuildError">BuildError</a>></h4></section></summary><divclass="docblock"><p>Create a new lazy DFA that matches every input.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.never_match"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#219-222">source</a><h4class="code-header">pub fn <ahref="#method.never_match"class="fn">never_match</a>() -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="struct.DFA.html"title="struct regex_automata::hybrid::dfa::DFA">DFA</a>, <aclass="struct"href="../struct.BuildError.html"title="struct regex_automata::hybrid::BuildError">BuildError</a>></h4></section></summary><divclass="docblock"><p>Create a new lazy DFA that never matches any input.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.config"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#258-260">source</a><h4class="code-header">pub fn <ahref="#method.config"class="fn">config</a>() -><aclass="struct"href="struct.Config.html"title="struct regex_automata::hybrid::dfa::Config">Config</a></h4></section></summary><divclass="docblock"><p>Return a default configuration for a <code>DFA</code>.</p>
<p>This is a convenience routine to avoid needing to import the <ahref="struct.Config.html"title="struct regex_automata::hybrid::dfa::Config"><code>Config</code></a>
type when customizing the construction of a lazy DFA.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.builder"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#288-290">source</a><h4class="code-header">pub fn <ahref="#method.builder"class="fn">builder</a>() -><aclass="struct"href="struct.Builder.html"title="struct regex_automata::hybrid::dfa::Builder">Builder</a></h4></section></summary><divclass="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
<ahref="struct.Builder.html"title="struct regex_automata::hybrid::dfa::Builder"><code>Builder</code></a> type in common cases.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.create_cache"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#298-300">source</a><h4class="code-header">pub fn <ahref="#method.create_cache"class="fn">create_cache</a>(&self) -><aclass="struct"href="struct.Cache.html"title="struct regex_automata::hybrid::dfa::Cache">Cache</a></h4></section></summary><divclass="docblock"><p>Create a new cache for this lazy DFA.</p>
<p>The cache returned should only be used for searches for this
lazy DFA. If you want to reuse the cache for another DFA, then
you must call <ahref="struct.Cache.html#method.reset"title="method regex_automata::hybrid::dfa::Cache::reset"><code>Cache::reset</code></a> with that DFA (or, equivalently,
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.reset_cache"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#346-348">source</a><h4class="code-header">pub fn <ahref="#method.reset_cache"class="fn">reset_cache</a>(&self, cache: &mut <aclass="struct"href="struct.Cache.html"title="struct regex_automata::hybrid::dfa::Cache">Cache</a>)</h4></section></summary><divclass="docblock"><p>Reset the given cache such that it can be used for searching with the
this lazy DFA (and only this DFA).</p>
<p>A cache reset permits reusing memory already allocated in this cache
with a different lazy DFA.</p>
<p>Resetting a cache sets its “clear count” to 0. This is relevant if the
lazy DFA has been configured to “give up” after it has cleared the
cache a certain number of times.</p>
<p>Any lazy state ID generated by the cache prior to resetting it is
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.pattern_len"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#385-387">source</a><h4class="code-header">pub fn <ahref="#method.pattern_len"class="fn">pattern_len</a>(&self) -><aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the total number of patterns compiled into this lazy DFA.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.byte_classes"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#402-404">source</a><h4class="code-header">pub fn <ahref="#method.byte_classes"class="fn">byte_classes</a>(&self) ->&<aclass="struct"href="../../util/alphabet/struct.ByteClasses.html"title="struct regex_automata::util::alphabet::ByteClasses">ByteClasses</a></h4></section></summary><divclass="docblock"><p>Returns the equivalence classes that make up the alphabet for this DFA.</p>
<p>Unless <ahref="struct.Config.html#method.byte_classes"title="method regex_automata::hybrid::dfa::Config::byte_classes"><code>Config::byte_classes</code></a> was disabled, it is possible that
multiple distinct bytes are grouped into the same equivalence class
if it is impossible for them to discriminate between a match and a
non-match. This has the effect of reducing the overall alphabet size
and in turn potentially substantially reducing the size of the DFA’s
transition table.</p>
<p>The downside of using equivalence classes like this is that every state
transition will automatically use this map to convert an arbitrary
byte to its corresponding equivalence class. In practice this has a
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.get_nfa"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#412-414">source</a><h4class="code-header">pub fn <ahref="#method.get_nfa"class="fn">get_nfa</a>(&self) ->&<aclass="struct"href="../../nfa/thompson/struct.NFA.html"title="struct regex_automata::nfa::thompson::NFA">NFA</a></h4></section></summary><divclass="docblock"><p>Returns a reference to the underlying NFA.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.memory_usage"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#446-454">source</a><h4class="code-header">pub fn <ahref="#method.memory_usage"class="fn">memory_usage</a>(&self) -><aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the memory usage, in bytes, of this lazy DFA.</p>
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="../../struct.HalfMatch.html"title="struct regex_automata::HalfMatch">HalfMatch</a>>, <aclass="struct"href="../../struct.MatchError.html"title="struct regex_automata::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Executes a forward search and returns the end position of the leftmost
<h5id="example-specifying-the-bounds-of-a-search"><aclass="doc-anchor"href="#example-specifying-the-bounds-of-a-search">§</a>Example: specifying the bounds of a search</h5>
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="../../struct.HalfMatch.html"title="struct regex_automata::HalfMatch">HalfMatch</a>>, <aclass="struct"href="../../struct.MatchError.html"title="struct regex_automata::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Executes a reverse search and returns the start of the position of the
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.unit.html">()</a>, <aclass="struct"href="../../struct.MatchError.html"title="struct regex_automata::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Executes an overlapping forward search and returns the end position of
matches as they are found. If no match exists, then <code>None</code> is returned.</p>
<p>This routine is principally only useful when searching for multiple
patterns on inputs where multiple patterns may match the same regions
of text. In particular, callers must preserve the automaton’s search
state from prior calls so that the implementation knows where the last
match occurred.</p>
<p>When using this routine to implement an iterator of overlapping
matches, the <code>start</code> of the search should remain invariant throughout
iteration. The <code>OverlappingState</code> given to the search will keep track
of the current position of the search. (This is because multiple
matches may be reported at the same position, so only the search
implementation itself knows when to advance the position.)</p>
<p>If for some reason you want the search to forget about its previous
state and restart the search at a particular position, then setting the
state to <ahref="struct.OverlappingState.html#method.start"title="associated function regex_automata::hybrid::dfa::OverlappingState::start"><code>OverlappingState::start</code></a> will accomplish that.</p>
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.unit.html">()</a>, <aclass="struct"href="../../struct.MatchError.html"title="struct regex_automata::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Executes a reverse overlapping search and returns the start of the
position of the leftmost match that is found. If no match exists, then
<code>None</code> is returned.</p>
<p>When using this routine to implement an iterator of overlapping
matches, the <code>start</code> of the search should remain invariant throughout
iteration. The <code>OverlappingState</code> given to the search will keep track
of the current position of the search. (This is because multiple
matches may be reported at the same position, so only the search
implementation itself knows when to advance the position.)</p>
<p>If for some reason you want the search to forget about its previous
state and restart the search at a particular position, then setting the
state to <ahref="struct.OverlappingState.html#method.start"title="associated function regex_automata::hybrid::dfa::OverlappingState::start"><code>OverlappingState::start</code></a> will accomplish that.</p>
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.unit.html">()</a>, <aclass="struct"href="../../struct.MatchError.html"title="struct regex_automata::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Writes the set of patterns that match anywhere in the given search
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID">LazyStateID</a>, <aclass="struct"href="../struct.CacheError.html"title="struct regex_automata::hybrid::CacheError">CacheError</a>></h4></section></summary><divclass="docblock"><p>Transitions from the current state to the next state, given the next
) -><aclass="struct"href="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID">LazyStateID</a></h4></section></summary><divclass="docblock"><p>Transitions from the current state to the next state, given the next
byte of input and a state ID that is not tagged.</p>
<p>The only reason to use this routine is performance. In particular, the
<code>next_state</code> method needs to do some additional checks, among them is
to account for identifiers to states that are not yet computed. In
such a case, the transition is computed on the fly. However, if it is
known that the <code>current</code> state ID is untagged, then these checks can be
omitted.</p>
<p>Since this routine does not compute states on the fly, it does not
modify the cache and thus cannot return an error. Consequently, <code>cache</code>
does not need to be mutable and it is possible for this routine to
return a state ID corresponding to the special “unknown” state. In
this case, it is the caller’s responsibility to use the prior state
ID and <code>input</code> with <code>next_state</code> in order to force the computation of
the unknown transition. Otherwise, trying to use the “unknown” state
ID will just result in transitioning back to itself, and thus never
terminating. (This is technically a special exemption to the state ID
validity rules, but is permissible since this routine is guarateed to
never mutate the given <code>cache</code>, and thus the identifier is guaranteed
to remain valid.)</p>
<p>See <ahref="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID"><code>LazyStateID</code></a> for more details on what it means for a state ID
) -><aclass="struct"href="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID">LazyStateID</a></h4></section></summary><divclass="docblock"><p>Transitions from the current state to the next state, eliding bounds
checks, given the next byte of input and a state ID that is not tagged.</p>
<p>The only reason to use this routine is performance. In particular, the
<code>next_state</code> method needs to do some additional checks, among them is
to account for identifiers to states that are not yet computed. In
such a case, the transition is computed on the fly. However, if it is
known that the <code>current</code> state ID is untagged, then these checks can be
omitted.</p>
<p>Since this routine does not compute states on the fly, it does not
modify the cache and thus cannot return an error. Consequently, <code>cache</code>
does not need to be mutable and it is possible for this routine to
return a state ID corresponding to the special “unknown” state. In
this case, it is the caller’s responsibility to use the prior state
ID and <code>input</code> with <code>next_state</code> in order to force the computation of
the unknown transition. Otherwise, trying to use the “unknown” state
ID will just result in transitioning back to itself, and thus never
terminating. (This is technically a special exemption to the state ID
validity rules, but is permissible since this routine is guarateed to
never mutate the given <code>cache</code>, and thus the identifier is guaranteed
to remain valid.)</p>
<p>See <ahref="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID"><code>LazyStateID</code></a> for more details on what it means for a state ID
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID">LazyStateID</a>, <aclass="struct"href="../struct.CacheError.html"title="struct regex_automata::hybrid::CacheError">CacheError</a>></h4></section></summary><divclass="docblock"><p>Transitions from the current state to the next state for the special
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID">LazyStateID</a>, <aclass="enum"href="../enum.StartError.html"title="enum regex_automata::hybrid::StartError">StartError</a>></h4></section></summary><divclass="docblock"><p>Return the ID of the start state for this lazy DFA for the given
<p>Unlike typical DFA implementations, the start state for DFAs in this
crate is dependent on a few different factors:</p>
<ul>
<li>The <ahref="../../enum.Anchored.html"title="enum regex_automata::Anchored"><code>Anchored</code></a> mode of the search. Unanchored, anchored and
anchored searches for a specific <ahref="../../struct.PatternID.html"title="struct regex_automata::PatternID"><code>PatternID</code></a> all use different start
states.</li>
<li>Whether a “look-behind” byte exists. For example, the <code>^</code> anchor
matches if and only if there is no look-behind byte.</li>
<li>The specific value of that look-behind byte. For example, a <code>(?m:^)</code>
assertion only matches when there is either no look-behind byte, or
when the look-behind byte is a line terminator.</li>
</ul>
<p>The <ahref="../../util/start/struct.Config.html"title="struct regex_automata::util::start::Config">starting configuration</a> provides the above
information.</p>
<p>This routine can be used for either forward or reverse searches.
Although, as a convenience, if you have an <ahref="../../struct.Input.html"title="struct regex_automata::Input"><code>Input</code></a>, then it
may be more succinct to use <ahref="struct.DFA.html#method.start_state_forward"title="method regex_automata::hybrid::dfa::DFA::start_state_forward"><code>DFA::start_state_forward</code></a> or
<ahref="struct.DFA.html#method.start_state_reverse"title="method regex_automata::hybrid::dfa::DFA::start_state_reverse"><code>DFA::start_state_reverse</code></a>. Note, for example, that the convenience
routines return a <ahref="../../struct.MatchError.html"title="struct regex_automata::MatchError"><code>MatchError</code></a> on failure where as this routine
returns a <ahref="../enum.StartError.html"title="enum regex_automata::hybrid::StartError"><code>StartError</code></a>.</p>
<p>This may return a <ahref="../enum.StartError.html"title="enum regex_automata::hybrid::StartError"><code>StartError</code></a> if the search needs to give up when
determining the start state (for example, if it sees a “quit” byte
or if the cache has become inefficient). This can also return an
error if the given configuration contains an unsupported <ahref="../../enum.Anchored.html"title="enum regex_automata::Anchored"><code>Anchored</code></a>
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID">LazyStateID</a>, <aclass="struct"href="../../struct.MatchError.html"title="struct regex_automata::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Return the ID of the start state for this lazy DFA when executing a
<p>This is a convenience routine for calling <ahref="struct.DFA.html#method.start_state"title="method regex_automata::hybrid::dfa::DFA::start_state"><code>DFA::start_state</code></a> that
converts the given <ahref="../../struct.Input.html"title="struct regex_automata::Input"><code>Input</code></a> to a <ahref="../../util/start/struct.Config.html"title="struct regex_automata::util::start::Config">start configuration</a>.
Additionally, if an error occurs, it is converted from a <ahref="../enum.StartError.html"title="enum regex_automata::hybrid::StartError"><code>StartError</code></a>
to a <ahref="../../struct.MatchError.html"title="struct regex_automata::MatchError"><code>MatchError</code></a> using the offset information in the given
<p>This may return a <ahref="../../struct.MatchError.html"title="struct regex_automata::MatchError"><code>MatchError</code></a> if the search needs to give up when
determining the start state (for example, if it sees a “quit” byte or
if the cache has become inefficient). This can also return an error if
the given <code>Input</code> contains an unsupported <ahref="../../enum.Anchored.html"title="enum regex_automata::Anchored"><code>Anchored</code></a> configuration.</p>
) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID">LazyStateID</a>, <aclass="struct"href="../../struct.MatchError.html"title="struct regex_automata::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Return the ID of the start state for this lazy DFA when executing a
<p>This is a convenience routine for calling <ahref="struct.DFA.html#method.start_state"title="method regex_automata::hybrid::dfa::DFA::start_state"><code>DFA::start_state</code></a> that
converts the given <ahref="../../struct.Input.html"title="struct regex_automata::Input"><code>Input</code></a> to a <ahref="../../util/start/struct.Config.html"title="struct regex_automata::util::start::Config">start configuration</a>.
Additionally, if an error occurs, it is converted from a <ahref="../enum.StartError.html"title="enum regex_automata::hybrid::StartError"><code>StartError</code></a>
to a <ahref="../../struct.MatchError.html"title="struct regex_automata::MatchError"><code>MatchError</code></a> using the offset information in the given
<p>This may return a <ahref="../../struct.MatchError.html"title="struct regex_automata::MatchError"><code>MatchError</code></a> if the search needs to give up when
determining the start state (for example, if it sees a “quit” byte or
if the cache has become inefficient). This can also return an error if
the given <code>Input</code> contains an unsupported <ahref="../../enum.Anchored.html"title="enum regex_automata::Anchored"><code>Anchored</code></a> configuration.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.match_len"class="method"><aclass="src rightside"href="../../../src/regex_automata/hybrid/dfa.rs.html#1716-1719">source</a><h4class="code-header">pub fn <ahref="#method.match_len"class="fn">match_len</a>(&self, cache: &<aclass="struct"href="struct.Cache.html"title="struct regex_automata::hybrid::dfa::Cache">Cache</a>, id: <aclass="struct"href="../struct.LazyStateID.html"title="struct regex_automata::hybrid::LazyStateID">LazyStateID</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the total number of patterns that match in this state.</p>
<p>If the lazy DFA was compiled with one pattern, then this must
necessarily always return <code>1</code> for all match states.</p>
<p>A lazy DFA guarantees that <ahref="struct.DFA.html#method.match_pattern"title="method regex_automata::hybrid::dfa::DFA::match_pattern"><code>DFA::match_pattern</code></a> can be called with
indices up to (but not including) the length returned by this routine
<p>This example shows a simple instance of implementing overlapping
matches. In particular, it shows not only how to determine how many
patterns have matched in a particular state, but also how to access
which specific patterns have matched.</p>
<p>Notice that we must use <ahref="../../enum.MatchKind.html#variant.All"title="variant regex_automata::MatchKind::All"><code>MatchKind::All</code></a> when building the DFA. If we
used <ahref="../../enum.MatchKind.html#variant.LeftmostFirst"title="variant regex_automata::MatchKind::LeftmostFirst"><code>MatchKind::LeftmostFirst</code></a> instead, then the DFA would not be
constructed in a way that supports overlapping matches. (It would only
report a single pattern that matches at any particular point in time.)</p>
<p>Another thing to take note of is the patterns used and the order in
which the pattern IDs are reported. In the example below, pattern <code>3</code>
is yielded first. Why? Because it corresponds to the match that
appears first. Namely, the <code>@</code> symbol is part of <code>\S+</code> but not part
of any of the other patterns. Since the <code>\S+</code> pattern has a match that
starts to the left of any other pattern, its ID is returned before any
) -><aclass="struct"href="../../struct.PatternID.html"title="struct regex_automata::PatternID">PatternID</a></h4></section></summary><divclass="docblock"><p>Returns the pattern ID corresponding to the given match index in the
given state.</p>
<p>See <ahref="struct.DFA.html#method.match_len"title="method regex_automata::hybrid::dfa::DFA::match_len"><code>DFA::match_len</code></a> for an example of how to use this method
correctly. Note that if you know your lazy DFA is configured with a
single pattern, then this routine is never necessary since it will
always return a pattern ID of <code>0</code> for an index of <code>0</code> when <code>id</code>
corresponds to a match state.</p>
<p>Typically, this routine is used when implementing an overlapping
search, as the example for <code>DFA::match_len</code> does.</p>
<code><ahref="https://doc.rust-lang.org/1.77.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><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-ToOwned-for-T"class="impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.77.0/src/alloc/borrow.rs.html#83-85">source</a><ahref="#impl-ToOwned-for-T"class="anchor">§</a><h3class="code-header">impl<T><aclass="trait"href="https://doc.rust-lang.org/1.77.0/alloc/borrow/trait.ToOwned.html"title="trait alloc::borrow::ToOwned">ToOwned</a> for T<divclass="where">where
T: <aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/clone/trait.Clone.html"title="trait core::clone::Clone">Clone</a>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Owned"class="associatedtype trait-impl"><ahref="#associatedtype.Owned"class="anchor">§</a><h4class="code-header">type <ahref="https://doc.rust-lang.org/1.77.0/alloc/borrow/trait.ToOwned.html#associatedtype.Owned"class="associatedtype">Owned</a> = T</h4></section></summary><divclass='docblock'>The resulting type after obtaining ownership.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.to_owned"class="method trait-impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.77.0/src/alloc/borrow.rs.html#88">source</a><ahref="#method.to_owned"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.77.0/alloc/borrow/trait.ToOwned.html#tymethod.to_owned"class="fn">to_owned</a>(&self) -> T</h4></section></summary><divclass='docblock'>Creates owned data from borrowed data, usually by cloning. <ahref="https://doc.rust-lang.org/1.77.0/alloc/borrow/trait.ToOwned.html#tymethod.to_owned">Read more</a></div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.clone_into"class="method trait-impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.77.0/src/alloc/borrow.rs.html#92">source</a><ahref="#method.clone_into"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.77.0/alloc/borrow/trait.ToOwned.html#method.clone_into"class="fn">clone_into</a>(&self, target: <aclass="primitive"href="https://doc.rust-lang.org/1.77.0/std/primitive.reference.html">&mut T</a>)</h4></section></summary><divclass='docblock'>Uses borrowed data to replace owned data, usually by cloning. <ahref="https://doc.rust-lang.org/1.77.0/alloc/borrow/trait.ToOwned.html#method.clone_into">Read more</a></div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-TryFrom%3CU%3E-for-T"class="impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.77.0/src/core/convert/mod.rs.html#804-806">source</a><ahref="#impl-TryFrom%3CU%3E-for-T"class="anchor">§</a><h3class="code-header">impl<T, U><aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><U> for T<divclass="where">where
U: <aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.Into.html"title="trait core::convert::Into">Into</a><T>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Error-1"class="associatedtype trait-impl"><ahref="#associatedtype.Error-1"class="anchor">§</a><h4class="code-header">type <ahref="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html#associatedtype.Error"class="associatedtype">Error</a> = <aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/convert/enum.Infallible.html"title="enum core::convert::Infallible">Infallible</a></h4></section></summary><divclass='docblock'>The type returned in the event of a conversion error.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_from"class="method trait-impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.77.0/src/core/convert/mod.rs.html#811">source</a><ahref="#method.try_from"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html#tymethod.try_from"class="fn">try_from</a>(value: U) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><T, <T as <aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><U>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a>></h4></section></summary><divclass='docblock'>Performs the conversion.</div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-TryInto%3CU%3E-for-T"class="impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.77.0/src/core/convert/mod.rs.html#789-791">source</a><ahref="#impl-TryInto%3CU%3E-for-T"class="anchor">§</a><h3class="code-header">impl<T, U><aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryInto.html"title="trait core::convert::TryInto">TryInto</a><U> for T<divclass="where">where
U: <aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Error"class="associatedtype trait-impl"><ahref="#associatedtype.Error"class="anchor">§</a><h4class="code-header">type <ahref="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryInto.html#associatedtype.Error"class="associatedtype">Error</a> = <U as <aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a></h4></section></summary><divclass='docblock'>The type returned in the event of a conversion error.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_into"class="method trait-impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.77.0/src/core/convert/mod.rs.html#796">source</a><ahref="#method.try_into"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryInto.html#tymethod.try_into"class="fn">try_into</a>(self) -><aclass="enum"href="https://doc.rust-lang.org/1.77.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><U, <U as <aclass="trait"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.77.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a>></h4></section></summary><divclass='docblock'>Performs the conversion.</div></details></div></details></div></section></div></main></body></html>
