<!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 trait that abstracts over Aho-Corasick automata."><title>Automaton in aho_corasick::automaton - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/${f}">`).join(""))</script><linkrel="stylesheet"href="../../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../../static.files/rustdoc-dd39b87e5fcfba68.css"><metaname="rustdoc-vars"data-root-path="../../"data-static-root-path="../../static.files/"data-current-crate="aho_corasick"data-themes=""data-resource-suffix=""data-rustdoc-version="1.80.0 (051478957 2024-07-21)"data-channel="1.80.0"data-search-js="search-d52510db62a78183.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../../static.files/storage-118b08c4c78b968e.js"></script><scriptdefersrc="sidebar-items.js"></script><scriptdefersrc="../../static.files/main-20a3ad099b048cf2.js"></script><noscript><linkrel="stylesheet"href="../../static.files/noscript-df360f571f6edeae.css"></noscript><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 trait"><!--[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="../../aho_corasick/index.html">aho_corasick</a><spanclass="version">1.1.3</span></h2></div><h2class="location"><ahref="#">Automaton</a></h2><divclass="sidebar-elems"><section><h3><ahref="#required-methods">Required Methods</a></h3><ulclass="block"><li><ahref="#tymethod.is_dead">is_dead</a></li><li><ahref="#tymethod.is_match">is_match</a></li><li><ahref="#tymethod.is_special">is_special</a></li><li><ahref="#tymethod.is_start">is_start</a></li><li><ahref="#tymethod.match_kind">match_kind</a></li><li><ahref="#tymethod.match_len">match_len</a></li><li><ahref="#tymethod.match_pattern">match_pattern</a></li><li><ahref="#tymethod.max_pattern_len">max_pattern_len</a></li><li><ahref="#tymethod.memory_usage">memory_usage</a></li><li><ahref="#tymethod.min_pattern_len">min_pattern_len</a></li><li><ahref="#tymethod.next_state">next_state</a></li><li><ahref="#tymethod.pattern_len">pattern_len</a></li><li><ahref="#tymethod.patterns_len">patterns_len</a></li><li><ahref="#tymethod.prefilter">prefilter</a></li><li><ahref="#tymethod.start_state">start_state</a></li></ul><h3><ahref="#provided-methods">Provided Methods</a></h3><ulclass="block"><li><ahref="#method.try_find">try_find</a></li><li><ahref="#method.try_find_iter">try_find_iter</a></li><li><ahref="#method.try_find_overlapping">try_find_overlapping</a></li><li><ahref="#method.try_find_overlapping_iter">try_find_overlapping_iter</a></li><li><ahref="#method.try_replace_all">try_replace_all</a></li><li><ahref="#method.try_replace_all_bytes">try_replace_all_bytes</a></li><li><ahref="#method.try_replace_all_with">try_replace_all_with</a></li><li><ahref="#method.try_replace_all_with_bytes">try_replace_all_with_bytes</a></li><li><ahref="#method.try_stream_find_iter">try_stream_find_iter</a></li><li><ahref="#method.try_stream_replace_all">try_stream_replace_all</a></li><li><ahref="#method.try_stream_replace_all_with">try_stream_replace_all_with</a></li></ul><h3><ahref="#foreign-impls">Implementations on Foreign Types</a></h3
</details>}</code></pre><detailsclass="toggle top-doc"open><summaryclass="hideme"><span>Expand description</span></summary><divclass="docblock"><p>A trait that abstracts over Aho-Corasick automata.</p>
<p>This trait primarily exists for niche use cases such as:</p>
<ul>
<li>Using an NFA or DFA directly, bypassing the top-level
<ahref="../struct.AhoCorasick.html"title="struct aho_corasick::AhoCorasick"><code>AhoCorasick</code></a> searcher. Currently, these include
<li>Implementing your own custom search routine by walking the automaton
yourself. This might be useful for implementing search on non-contiguous
strings or streams.</li>
</ul>
<p>For most use cases, it is not expected that users will need
to use or even know about this trait. Indeed, the top level
<ahref="../struct.AhoCorasick.html"title="struct aho_corasick::AhoCorasick"><code>AhoCorasick</code></a> searcher does not expose any details
about this trait, nor does it implement it itself.</p>
<p>Note that this trait defines a number of default methods, such as
<ahref="trait.Automaton.html#method.try_find"title="method aho_corasick::automaton::Automaton::try_find"><code>Automaton::try_find</code></a> and <ahref="trait.Automaton.html#method.try_find_iter"title="method aho_corasick::automaton::Automaton::try_find_iter"><code>Automaton::try_find_iter</code></a>, which implement
higher level search routines in terms of the lower level automata API.</p>
<p>This trait encodes a notion of “special” states in an automaton. Namely,
a state is treated as special if it is a dead, match or start state:</p>
<ul>
<li>A dead state is a state that cannot be left once entered. All transitions
on a dead state lead back to itself. The dead state is meant to be treated
as a sentinel indicating that the search should stop and return a match if
one has been found, and nothing otherwise.</li>
<li>A match state is a state that indicates one or more patterns have
matched. Depending on the <ahref="../enum.MatchKind.html"title="enum aho_corasick::MatchKind"><code>MatchKind</code></a> of the automaton, a search may
stop once a match is seen, or it may continue looking for matches until
it enters a dead state or sees the end of the haystack.</li>
<li>A start state is a state that a search begins in. It is useful to know
when a search enters a start state because it may mean that a prefilter can
be used to skip ahead and quickly look for candidate matches. Unlike dead
and match states, it is never necessary to explicitly handle start states
for correctness. Indeed, in this crate, implementations of <code>Automaton</code>
will only treat start states as “special” when a prefilter is enabled and
active. Otherwise, treating it as special has no purpose and winds up
slowing down the overall search because it results in ping-ponging between
the main state transition and the “special” state logic.</li>
</ul>
<p>Since checking whether a state is special by doing three different
checks would be too expensive inside a fast search loop, the
<ahref="trait.Automaton.html#tymethod.is_special"title="method aho_corasick::automaton::Automaton::is_special"><code>Automaton::is_special</code></a> method is provided for quickly checking whether
the state is special. The <code>Automaton::is_dead</code>, <code>Automaton::is_match</code> and
<code>Automaton::is_start</code> predicates can then be used to determine which kind
<p>This example shows how one might implement a basic but correct search
routine. We keep things simple by not using prefilters or worrying about
anchored searches, but do make sure our search is correct for all possible
<ahref="../enum.MatchKind.html"title="enum aho_corasick::MatchKind"><code>MatchKind</code></a> semantics. (The comments in the code below note the parts
that are needed to support certain <code>MatchKind</code> semantics.)</p>
</div></details><h2id="required-methods"class="section-header">Required Methods<ahref="#required-methods"class="anchor">§</a></h2><divclass="methods"><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.start_state"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#210">source</a><h4class="code-header">fn <ahref="#tymethod.start_state"class="fn">start_state</a>(&self, anchored: <aclass="enum"href="../enum.Anchored.html"title="enum aho_corasick::Anchored">Anchored</a>) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a>, <aclass="struct"href="../struct.MatchError.html"title="struct aho_corasick::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Returns the starting state for the given anchor mode.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.next_state"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#237-242">source</a><h4class="code-header">fn <ahref="#tymethod.next_state"class="fn">next_state</a>(&self, anchored: <aclass="enum"href="../enum.Anchored.html"title="enum aho_corasick::Anchored">Anchored</a>, sid: <aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a>, byte: <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.u8.html">u8</a>) -><aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a></h4></section></summary><divclass="docblock"><p>Performs a state transition from <code>sid</code> for <code>byte</code> and returns the next
<p><code>anchored</code> should be <ahref="../enum.Anchored.html#variant.Yes"title="variant aho_corasick::Anchored::Yes"><code>Anchored::Yes</code></a> when executing an anchored
search and <ahref="../enum.Anchored.html#variant.No"title="variant aho_corasick::Anchored::No"><code>Anchored::No</code></a> otherwise. For some implementations of
<code>Automaton</code>, it is required to know whether the search is anchored
or not in order to avoid following failure transitions. Other
implementations may ignore <code>anchored</code> altogether and depend on
<code>Automaton::start_state</code> returning a state that walks a different path
through the automaton depending on whether the search is anchored or
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.is_special"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#253">source</a><h4class="code-header">fn <ahref="#tymethod.is_special"class="fn">is_special</a>(&self, sid: <aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.bool.html">bool</a></h4></section></summary><divclass="docblock"><p>Returns true if the given ID represents a “special” state. A special
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.is_dead"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#263">source</a><h4class="code-header">fn <ahref="#tymethod.is_dead"class="fn">is_dead</a>(&self, sid: <aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.bool.html">bool</a></h4></section></summary><divclass="docblock"><p>Returns true if the given ID represents a dead state.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.is_match"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#276">source</a><h4class="code-header">fn <ahref="#tymethod.is_match"class="fn">is_match</a>(&self, sid: <aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.bool.html">bool</a></h4></section></summary><divclass="docblock"><p>Returns true if the given ID represents a match state.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.is_start"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#293">source</a><h4class="code-header">fn <ahref="#tymethod.is_start"class="fn">is_start</a>(&self, sid: <aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.bool.html">bool</a></h4></section></summary><divclass="docblock"><p>Returns true if the given ID represents a start state.</p>
<p>This has unspecified behavior when given an invalid state ID.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.match_kind"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#296">source</a><h4class="code-header">fn <ahref="#tymethod.match_kind"class="fn">match_kind</a>(&self) -><aclass="enum"href="../enum.MatchKind.html"title="enum aho_corasick::MatchKind">MatchKind</a></h4></section></summary><divclass="docblock"><p>Returns the match semantics that this automaton was built with.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.match_len"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#302">source</a><h4class="code-header">fn <ahref="#tymethod.match_len"class="fn">match_len</a>(&self, sid: <aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the total number of matches for the given state ID.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.match_pattern"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#314">source</a><h4class="code-header">fn <ahref="#tymethod.match_pattern"class="fn">match_pattern</a>(&self, sid: <aclass="struct"href="struct.StateID.html"title="struct aho_corasick::automaton::StateID">StateID</a>, index: <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a>) -><aclass="struct"href="../struct.PatternID.html"title="struct aho_corasick::PatternID">PatternID</a></h4></section></summary><divclass="docblock"><p>Returns the pattern ID for the match state given by <code>sid</code> at the
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.patterns_len"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#317">source</a><h4class="code-header">fn <ahref="#tymethod.patterns_len"class="fn">patterns_len</a>(&self) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the total number of patterns compiled into this automaton.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.pattern_len"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#324">source</a><h4class="code-header">fn <ahref="#tymethod.pattern_len"class="fn">pattern_len</a>(&self, pid: <aclass="struct"href="../struct.PatternID.html"title="struct aho_corasick::PatternID">PatternID</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the length of the pattern for the given ID.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.min_pattern_len"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#328">source</a><h4class="code-header">fn <ahref="#tymethod.min_pattern_len"class="fn">min_pattern_len</a>(&self) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the length, in bytes, of the shortest pattern in this
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.max_pattern_len"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#331">source</a><h4class="code-header">fn <ahref="#tymethod.max_pattern_len"class="fn">max_pattern_len</a>(&self) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the length, in bytes, of the longest pattern in this automaton.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.memory_usage"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#334">source</a><h4class="code-header">fn <ahref="#tymethod.memory_usage"class="fn">memory_usage</a>(&self) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the heap memory usage, in bytes, used by this automaton.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="tymethod.prefilter"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#346">source</a><h4class="code-header">fn <ahref="#tymethod.prefilter"class="fn">prefilter</a>(&self) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><&<aclass="struct"href="struct.Prefilter.html"title="struct aho_corasick::automaton::Prefilter">Prefilter</a>></h4></section></summary><divclass="docblock"><p>Returns a prefilter, if available, that can be used to accelerate
</div></details></div><h2id="provided-methods"class="section-header">Provided Methods<ahref="#provided-methods"class="anchor">§</a></h2><divclass="methods"><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_find"class="method"><aclass="src rightside"href="../../src/aho_corasick/automaton.rs.html#354-359">source</a><h4class="code-header">fn <ahref="#method.try_find"class="fn">try_find</a>(&self, input: &<aclass="struct"href="../struct.Input.html"title="struct aho_corasick::Input">Input</a><'_>) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="../struct.Match.html"title="struct aho_corasick::Match">Match</a>>, <aclass="struct"href="../struct.MatchError.html"title="struct aho_corasick::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Executes a non-overlapping search with this automaton using the given
) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.unit.html">()</a>, <aclass="struct"href="../struct.MatchError.html"title="struct aho_corasick::MatchError">MatchError</a>></h4></section></summary><divclass="docblock"><p>Executes a overlapping search with this automaton using the given
Self: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/marker/trait.Sized.html"title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><divclass="docblock"><p>Returns an iterator of non-overlapping matches with this automaton
Self: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/marker/trait.Sized.html"title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><divclass="docblock"><p>Returns an iterator of overlapping matches with this automaton
B: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.AsRef.html"title="trait core::convert::AsRef">AsRef</a><<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.str.html">str</a>>,</div></h4></section></summary><divclass="docblock"><p>Replaces all non-overlapping matches in <code>haystack</code> with
B: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.AsRef.html"title="trait core::convert::AsRef">AsRef</a><[<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.u8.html">u8</a>]>,</div></h4></section></summary><divclass="docblock"><p>Replaces all non-overlapping matches in <code>haystack</code> with
F: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/ops/function/trait.FnMut.html"title="trait core::ops::function::FnMut">FnMut</a>(&<aclass="struct"href="../struct.Match.html"title="struct aho_corasick::Match">Match</a>, &<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.str.html">str</a>, &mut <aclass="struct"href="https://doc.rust-lang.org/1.80.0/alloc/string/struct.String.html"title="struct alloc::string::String">String</a>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.bool.html">bool</a>,</div></h4></section></summary><divclass="docblock"><p>Replaces all non-overlapping matches in <code>haystack</code> by calling the
F: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/ops/function/trait.FnMut.html"title="trait core::ops::function::FnMut">FnMut</a>(&<aclass="struct"href="../struct.Match.html"title="struct aho_corasick::Match">Match</a>, &[<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.u8.html">u8</a>], &mut <aclass="struct"href="https://doc.rust-lang.org/1.80.0/alloc/vec/struct.Vec.html"title="struct alloc::vec::Vec">Vec</a><<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.u8.html">u8</a>>) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.bool.html">bool</a>,</div></h4></section></summary><divclass="docblock"><p>Replaces all non-overlapping matches in <code>haystack</code> by calling the
Self: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/marker/trait.Sized.html"title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><divclass="docblock"><p>Returns an iterator of non-overlapping matches with this automaton
B: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.AsRef.html"title="trait core::convert::AsRef">AsRef</a><[<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.u8.html">u8</a>]>,</div></h4></section></summary><divclass="docblock"><p>Replaces all non-overlapping matches in <code>rdr</code> with strings from
F: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/ops/function/trait.FnMut.html"title="trait core::ops::function::FnMut">FnMut</a>(&<aclass="struct"href="../struct.Match.html"title="struct aho_corasick::Match">Match</a>, &[<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.u8.html">u8</a>], <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.reference.html">&mut W</a>) -><aclass="type"href="https://doc.rust-lang.org/1.80.0/std/io/error/type.Result.html"title="type std::io::error::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.unit.html">()</a>>,</div></h4></section></summary><divclass="docblock"><p>Replaces all non-overlapping matches in <code>rdr</code> by calling the