| <!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 builder for configuring an Aho-Corasick automaton."><meta name="keywords" content="rust, rustlang, rust-lang, AhoCorasickBuilder"><title>AhoCorasickBuilder in aho_corasick - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" href="../normalize.css"><link rel="stylesheet" href="../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" href="../ayu.css" disabled><link rel="stylesheet" href="../dark.css" disabled><link rel="stylesheet" href="../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../storage.js"></script><script defer src="sidebar-items.js"></script><script defer src="../main.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../favicon.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><a class="sidebar-logo" href="../aho_corasick/index.html"><div class="logo-container"><img class="rust-logo" src="../rust-logo.svg" alt="logo"></div></a><h2></h2></nav><nav class="sidebar"><a class="sidebar-logo" href="../aho_corasick/index.html"><div class="logo-container"><img class="rust-logo" src="../rust-logo.svg" alt="logo"></div></a><h2 class="location"><a href="#">AhoCorasickBuilder</a></h2><div class="sidebar-elems"><section><h3><a href="#implementations">Methods</a></h3><ul class="block"><li><a href="#method.ascii_case_insensitive">ascii_case_insensitive</a></li><li><a href="#method.build">build</a></li><li><a href="#method.byte_classes">byte_classes</a></li><li><a href="#method.dense_depth">dense_depth</a></li><li><a href="#method.kind">kind</a></li><li><a href="#method.match_kind">match_kind</a></li><li><a href="#method.new">new</a></li><li><a href="#method.prefilter">prefilter</a></li><li><a href="#method.start_kind">start_kind</a></li></ul><h3><a href="#trait-implementations">Trait Implementations</a></h3><ul class="block"><li><a href="#impl-Clone-for-AhoCorasickBuilder">Clone</a></li><li><a href="#impl-Debug-for-AhoCorasickBuilder">Debug</a></li><li><a href="#impl-Default-for-AhoCorasickBuilder">Default</a></li></ul><h3><a href="#synthetic-implementations">Auto Trait Implementations</a></h3><ul class="block"><li><a href="#impl-RefUnwindSafe-for-AhoCorasickBuilder">RefUnwindSafe</a></li><li><a href="#impl-Send-for-AhoCorasickBuilder">Send</a></li><li><a href="#impl-Sync-for-AhoCorasickBuilder">Sync</a></li><li><a href="#impl-Unpin-for-AhoCorasickBuilder">Unpin</a></li><li><a href="#impl-UnwindSafe-for-AhoCorasickBuilder">UnwindSafe</a></li></ul><h3><a href="#blanket-implementations">Blanket Implementations</a></h3><ul class="block"><li><a href="#impl-Any-for-AhoCorasickBuilder">Any</a></li><li><a href="#impl-Borrow%3CT%3E-for-AhoCorasickBuilder">Borrow<T></a></li><li><a href="#impl-BorrowMut%3CT%3E-for-AhoCorasickBuilder">BorrowMut<T></a></li><li><a href="#impl-From%3CT%3E-for-AhoCorasickBuilder">From<T></a></li><li><a href="#impl-Into%3CU%3E-for-AhoCorasickBuilder">Into<U></a></li><li><a href="#impl-ToOwned-for-AhoCorasickBuilder">ToOwned</a></li><li><a href="#impl-TryFrom%3CU%3E-for-AhoCorasickBuilder">TryFrom<U></a></li><li><a href="#impl-TryInto%3CU%3E-for-AhoCorasickBuilder">TryInto<U></a></li></ul></section><h2><a href="index.html">In aho_corasick</a></h2></div></nav><main><div class="width-limiter"><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><a href="../help.html">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../wheel.svg"></a></div></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn">Struct <a href="index.html">aho_corasick</a>::<wbr><a class="struct" href="#">AhoCorasickBuilder</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../clipboard.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="srclink" href="../src/aho_corasick/ahocorasick.rs.html#2135-2141">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span></div><div class="item-decl"><pre class="rust struct"><code>pub struct AhoCorasickBuilder { /* private fields */ }</code></pre></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>A builder for configuring an Aho-Corasick automaton.</p> |
| <h2 id="quick-advice"><a href="#quick-advice">Quick advice</a></h2> |
| <ul> |
| <li>Use <a href="struct.AhoCorasickBuilder.html#method.match_kind" title="AhoCorasickBuilder::match_kind"><code>AhoCorasickBuilder::match_kind</code></a> to configure your searcher |
| with <a href="enum.MatchKind.html#variant.LeftmostFirst" title="MatchKind::LeftmostFirst"><code>MatchKind::LeftmostFirst</code></a> if you want to match how backtracking |
| regex engines execute searches for <code>pat1|pat2|..|patN</code>. Use |
| <a href="enum.MatchKind.html#variant.LeftmostLongest" title="MatchKind::LeftmostLongest"><code>MatchKind::LeftmostLongest</code></a> if you want to match how POSIX regex engines |
| do it.</li> |
| <li>If you need an anchored search, use <a href="struct.AhoCorasickBuilder.html#method.start_kind" title="AhoCorasickBuilder::start_kind"><code>AhoCorasickBuilder::start_kind</code></a> to |
| set the <a href="enum.StartKind.html#variant.Anchored" title="StartKind::Anchored"><code>StartKind::Anchored</code></a> mode since <a href="enum.StartKind.html#variant.Unanchored" title="StartKind::Unanchored"><code>StartKind::Unanchored</code></a> is the |
| default. Or just use <a href="enum.StartKind.html#variant.Both" title="StartKind::Both"><code>StartKind::Both</code></a> to support both types of searches.</li> |
| <li>You might want to use <a href="struct.AhoCorasickBuilder.html#method.kind" title="AhoCorasickBuilder::kind"><code>AhoCorasickBuilder::kind</code></a> to set your searcher |
| to always use a <a href="enum.AhoCorasickKind.html#variant.DFA" title="AhoCorasickKind::DFA"><code>AhoCorasickKind::DFA</code></a> if search speed is critical and |
| memory usage isn’t a concern. Otherwise, not setting a kind will probably |
| make the right choice for you. Beware that if you use <a href="enum.StartKind.html#variant.Both" title="StartKind::Both"><code>StartKind::Both</code></a> |
| to build a searcher that supports both unanchored and anchored searches |
| <em>and</em> you set <a href="enum.AhoCorasickKind.html#variant.DFA" title="AhoCorasickKind::DFA"><code>AhoCorasickKind::DFA</code></a>, then the DFA will essentially be |
| duplicated to support both simultaneously. This results in very high memory |
| usage.</li> |
| <li>For all other options, their defaults are almost certainly what you want.</li> |
| </ul> |
| </div></details><h2 id="implementations" class="small-section-header">Implementations<a href="#implementations" class="anchor"></a></h2><div id="implementations-list"><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-AhoCorasickBuilder" class="impl has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2143-2616">source</a><a href="#impl-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.new" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2148-2150">source</a><h4 class="code-header">pub fn <a href="#method.new" class="fnname">new</a>() -> <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class="docblock"><p>Create a new builder for configuring an Aho-Corasick automaton.</p> |
| <p>The builder provides a way to configure a number of things, including |
| ASCII case insensitivity and what kind of match semantics are used.</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.build" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2171-2207">source</a><h4 class="code-header">pub fn <a href="#method.build" class="fnname">build</a><I, P>(&self, patterns: I) -> Result<<a class="struct" href="struct.AhoCorasick.html" title="struct aho_corasick::AhoCorasick">AhoCorasick</a>, <a class="struct" href="struct.BuildError.html" title="struct aho_corasick::BuildError">BuildError</a>><span class="where fmt-newline">where<br> I: IntoIterator<Item = P>,<br> P: AsRef<[u8]>,</span></h4></section></summary><div class="docblock"><p>Build an Aho-Corasick automaton using the configuration set on this |
| builder.</p> |
| <p>A builder may be reused to create more automatons.</p> |
| <h5 id="examples"><a href="#examples">Examples</a></h5> |
| <p>Basic usage:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>aho_corasick::{AhoCorasickBuilder, PatternID}; |
| |
| <span class="kw">let </span>patterns = <span class="kw-2">&</span>[<span class="string">"foo"</span>, <span class="string">"bar"</span>, <span class="string">"baz"</span>]; |
| <span class="kw">let </span>ac = AhoCorasickBuilder::new().build(patterns).unwrap(); |
| <span class="macro">assert_eq!</span>( |
| <span class="prelude-val">Some</span>(PatternID::must(<span class="number">1</span>)), |
| ac.find(<span class="string">"xxx bar xxx"</span>).map(|m| m.pattern()), |
| );</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.match_kind" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2342-2347">source</a><h4 class="code-header">pub fn <a href="#method.match_kind" class="fnname">match_kind</a>(&mut self, kind: <a class="enum" href="enum.MatchKind.html" title="enum aho_corasick::MatchKind">MatchKind</a>) -> &mut <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class="docblock"><p>Set the desired match semantics.</p> |
| <p>The default is <a href="enum.MatchKind.html#variant.Standard" title="MatchKind::Standard"><code>MatchKind::Standard</code></a>, which corresponds to the match |
| semantics supported by the standard textbook description of the |
| Aho-Corasick algorithm. Namely, matches are reported as soon as they |
| are found. Moreover, this is the only way to get overlapping matches |
| or do stream searching.</p> |
| <p>The other kinds of match semantics that are supported are |
| <a href="enum.MatchKind.html#variant.LeftmostFirst" title="MatchKind::LeftmostFirst"><code>MatchKind::LeftmostFirst</code></a> and <a href="enum.MatchKind.html#variant.LeftmostLongest" title="MatchKind::LeftmostLongest"><code>MatchKind::LeftmostLongest</code></a>. The |
| former corresponds to the match you would get if you were to try to |
| match each pattern at each position in the haystack in the same order |
| that you give to the automaton. That is, it returns the leftmost match |
| corresponding to the earliest pattern given to the automaton. The |
| latter corresponds to finding the longest possible match among all |
| leftmost matches.</p> |
| <p>For more details on match semantics, see the <a href="enum.MatchKind.html">documentation for |
| <code>MatchKind</code></a>.</p> |
| <p>Note that setting this to <a href="enum.MatchKind.html#variant.LeftmostFirst" title="MatchKind::LeftmostFirst"><code>MatchKind::LeftmostFirst</code></a> or |
| <a href="enum.MatchKind.html#variant.LeftmostLongest" title="MatchKind::LeftmostLongest"><code>MatchKind::LeftmostLongest</code></a> will cause some search routines on |
| <a href="struct.AhoCorasick.html" title="AhoCorasick"><code>AhoCorasick</code></a> to return an error (or panic if you’re using the |
| infallible API). Notably, this includes stream and overlapping |
| searches.</p> |
| <h5 id="examples-1"><a href="#examples-1">Examples</a></h5> |
| <p>In these examples, we demonstrate the differences between match |
| semantics for a particular set of patterns in a specific order: |
| <code>b</code>, <code>abc</code>, <code>abcd</code>.</p> |
| <p>Standard semantics:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>aho_corasick::{AhoCorasick, MatchKind}; |
| |
| <span class="kw">let </span>patterns = <span class="kw-2">&</span>[<span class="string">"b"</span>, <span class="string">"abc"</span>, <span class="string">"abcd"</span>]; |
| <span class="kw">let </span>haystack = <span class="string">"abcd"</span>; |
| |
| <span class="kw">let </span>ac = AhoCorasick::builder() |
| .match_kind(MatchKind::Standard) <span class="comment">// default, not necessary |
| </span>.build(patterns) |
| .unwrap(); |
| <span class="kw">let </span>mat = ac.find(haystack).expect(<span class="string">"should have a match"</span>); |
| <span class="macro">assert_eq!</span>(<span class="string">"b"</span>, <span class="kw-2">&</span>haystack[mat.start()..mat.end()]);</code></pre></div> |
| <p>Leftmost-first semantics:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>aho_corasick::{AhoCorasick, MatchKind}; |
| |
| <span class="kw">let </span>patterns = <span class="kw-2">&</span>[<span class="string">"b"</span>, <span class="string">"abc"</span>, <span class="string">"abcd"</span>]; |
| <span class="kw">let </span>haystack = <span class="string">"abcd"</span>; |
| |
| <span class="kw">let </span>ac = AhoCorasick::builder() |
| .match_kind(MatchKind::LeftmostFirst) |
| .build(patterns) |
| .unwrap(); |
| <span class="kw">let </span>mat = ac.find(haystack).expect(<span class="string">"should have a match"</span>); |
| <span class="macro">assert_eq!</span>(<span class="string">"abc"</span>, <span class="kw-2">&</span>haystack[mat.start()..mat.end()]);</code></pre></div> |
| <p>Leftmost-longest semantics:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>aho_corasick::{AhoCorasick, MatchKind}; |
| |
| <span class="kw">let </span>patterns = <span class="kw-2">&</span>[<span class="string">"b"</span>, <span class="string">"abc"</span>, <span class="string">"abcd"</span>]; |
| <span class="kw">let </span>haystack = <span class="string">"abcd"</span>; |
| |
| <span class="kw">let </span>ac = AhoCorasick::builder() |
| .match_kind(MatchKind::LeftmostLongest) |
| .build(patterns) |
| .unwrap(); |
| <span class="kw">let </span>mat = ac.find(haystack).expect(<span class="string">"should have a match"</span>); |
| <span class="macro">assert_eq!</span>(<span class="string">"abcd"</span>, <span class="kw-2">&</span>haystack[mat.start()..mat.end()]);</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.start_kind" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2437-2441">source</a><h4 class="code-header">pub fn <a href="#method.start_kind" class="fnname">start_kind</a>(&mut self, kind: <a class="enum" href="enum.StartKind.html" title="enum aho_corasick::StartKind">StartKind</a>) -> &mut <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class="docblock"><p>Sets the starting state configuration for the automaton.</p> |
| <p>Every Aho-Corasick automaton is capable of having two start states: one |
| that is used for unanchored searches and one that is used for anchored |
| searches. Some automatons, like the NFAs, support this with almost zero |
| additional cost. Other automatons, like the DFA, require two copies of |
| the underlying transition table to support both simultaneously.</p> |
| <p>Because there may be an added non-trivial cost to supporting both, it |
| is possible to configure which starting state configuration is needed.</p> |
| <p>Indeed, since anchored searches tend to be somewhat more rare, |
| <em>only</em> unanchored searches are supported by default. Thus, |
| <a href="enum.StartKind.html#variant.Unanchored" title="StartKind::Unanchored"><code>StartKind::Unanchored</code></a> is the default.</p> |
| <p>Note that when this is set to <a href="enum.StartKind.html#variant.Unanchored" title="StartKind::Unanchored"><code>StartKind::Unanchored</code></a>, then |
| running an anchored search will result in an error (or a panic |
| if using the infallible APIs). Similarly, when this is set to |
| <a href="enum.StartKind.html#variant.Anchored" title="StartKind::Anchored"><code>StartKind::Anchored</code></a>, then running an unanchored search will |
| result in an error (or a panic if using the infallible APIs). When |
| <a href="enum.StartKind.html#variant.Both" title="StartKind::Both"><code>StartKind::Both</code></a> is used, then both unanchored and anchored searches |
| are always supported.</p> |
| <p>Also note that even if an <code>AhoCorasick</code> searcher is using an NFA |
| internally (which always supports both unanchored and anchored |
| searches), an error will still be reported for a search that isn’t |
| supported by the configuration set via this method. This means, |
| for example, that an error is never dependent on which internal |
| implementation of Aho-Corasick is used.</p> |
| <h5 id="example-anchored-search"><a href="#example-anchored-search">Example: anchored search</a></h5> |
| <p>This shows how to build a searcher that only supports anchored |
| searches:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>aho_corasick::{ |
| AhoCorasick, Anchored, Input, Match, MatchKind, StartKind, |
| }; |
| |
| <span class="kw">let </span>ac = AhoCorasick::builder() |
| .match_kind(MatchKind::LeftmostFirst) |
| .start_kind(StartKind::Anchored) |
| .build(<span class="kw-2">&</span>[<span class="string">"b"</span>, <span class="string">"abc"</span>, <span class="string">"abcd"</span>]) |
| .unwrap(); |
| |
| <span class="comment">// An unanchored search is not supported! An error here is guaranteed |
| // given the configuration above regardless of which kind of |
| // Aho-Corasick implementation ends up being used internally. |
| </span><span class="kw">let </span>input = Input::new(<span class="string">"foo abcd"</span>).anchored(Anchored::No); |
| <span class="macro">assert!</span>(ac.try_find(input).is_err()); |
| |
| <span class="kw">let </span>input = Input::new(<span class="string">"foo abcd"</span>).anchored(Anchored::Yes); |
| <span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, ac.try_find(input)<span class="question-mark">?</span>); |
| |
| <span class="kw">let </span>input = Input::new(<span class="string">"abcd"</span>).anchored(Anchored::Yes); |
| <span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">1</span>, <span class="number">0</span>..<span class="number">3</span>)), ac.try_find(input)<span class="question-mark">?</span>); |
| </code></pre></div> |
| <h5 id="example-unanchored-and-anchored-searches"><a href="#example-unanchored-and-anchored-searches">Example: unanchored and anchored searches</a></h5> |
| <p>This shows how to build a searcher that supports both unanchored and |
| anchored searches:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>aho_corasick::{ |
| AhoCorasick, Anchored, Input, Match, MatchKind, StartKind, |
| }; |
| |
| <span class="kw">let </span>ac = AhoCorasick::builder() |
| .match_kind(MatchKind::LeftmostFirst) |
| .start_kind(StartKind::Both) |
| .build(<span class="kw-2">&</span>[<span class="string">"b"</span>, <span class="string">"abc"</span>, <span class="string">"abcd"</span>]) |
| .unwrap(); |
| |
| <span class="kw">let </span>input = Input::new(<span class="string">"foo abcd"</span>).anchored(Anchored::No); |
| <span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">1</span>, <span class="number">4</span>..<span class="number">7</span>)), ac.try_find(input)<span class="question-mark">?</span>); |
| |
| <span class="kw">let </span>input = Input::new(<span class="string">"foo abcd"</span>).anchored(Anchored::Yes); |
| <span class="macro">assert_eq!</span>(<span class="prelude-val">None</span>, ac.try_find(input)<span class="question-mark">?</span>); |
| |
| <span class="kw">let </span>input = Input::new(<span class="string">"abcd"</span>).anchored(Anchored::Yes); |
| <span class="macro">assert_eq!</span>(<span class="prelude-val">Some</span>(Match::must(<span class="number">1</span>, <span class="number">0</span>..<span class="number">3</span>)), ac.try_find(input)<span class="question-mark">?</span>); |
| </code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.ascii_case_insensitive" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2474-2482">source</a><h4 class="code-header">pub fn <a href="#method.ascii_case_insensitive" class="fnname">ascii_case_insensitive</a>(&mut self, yes: bool) -> &mut <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class="docblock"><p>Enable ASCII-aware case insensitive matching.</p> |
| <p>When this option is enabled, searching will be performed without |
| respect to case for ASCII letters (<code>a-z</code> and <code>A-Z</code>) only.</p> |
| <p>Enabling this option does not change the search algorithm, but it may |
| increase the size of the automaton.</p> |
| <p><strong>NOTE:</strong> It is unlikely that support for Unicode case folding will |
| be added in the future. The ASCII case works via a simple hack to the |
| underlying automaton, but full Unicode handling requires a fair bit of |
| sophistication. If you do need Unicode handling, you might consider |
| using the <a href="https://docs.rs/regex"><code>regex</code> crate</a> or the lower level |
| <a href="https://docs.rs/regex-automata"><code>regex-automata</code> crate</a>.</p> |
| <h5 id="examples-2"><a href="#examples-2">Examples</a></h5> |
| <p>Basic usage:</p> |
| |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>aho_corasick::AhoCorasick; |
| |
| <span class="kw">let </span>patterns = <span class="kw-2">&</span>[<span class="string">"FOO"</span>, <span class="string">"bAr"</span>, <span class="string">"BaZ"</span>]; |
| <span class="kw">let </span>haystack = <span class="string">"foo bar baz"</span>; |
| |
| <span class="kw">let </span>ac = AhoCorasick::builder() |
| .ascii_case_insensitive(<span class="bool-val">true</span>) |
| .build(patterns) |
| .unwrap(); |
| <span class="macro">assert_eq!</span>(<span class="number">3</span>, ac.find_iter(haystack).count());</code></pre></div> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.kind" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2527-2533">source</a><h4 class="code-header">pub fn <a href="#method.kind" class="fnname">kind</a>(&mut self, kind: Option<<a class="enum" href="enum.AhoCorasickKind.html" title="enum aho_corasick::AhoCorasickKind">AhoCorasickKind</a>>) -> &mut <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class="docblock"><p>Choose the type of underlying automaton to use.</p> |
| <p>Currently, there are four choices:</p> |
| <ul> |
| <li><a href="enum.AhoCorasickKind.html#variant.NoncontiguousNFA" title="AhoCorasickKind::NoncontiguousNFA"><code>AhoCorasickKind::NoncontiguousNFA</code></a> instructs the searcher to |
| use a <a href="nfa/noncontiguous/struct.NFA.html" title="noncontiguous::NFA"><code>noncontiguous::NFA</code></a>. A noncontiguous NFA is the fastest to |
| be built, has moderate memory usage and is typically the slowest to |
| execute a search.</li> |
| <li><a href="enum.AhoCorasickKind.html#variant.ContiguousNFA" title="AhoCorasickKind::ContiguousNFA"><code>AhoCorasickKind::ContiguousNFA</code></a> instructs the searcher to use a |
| <a href="nfa/contiguous/struct.NFA.html" title="contiguous::NFA"><code>contiguous::NFA</code></a>. A contiguous NFA is a little slower to build than |
| a noncontiguous NFA, has excellent memory usage and is typically a |
| little slower than a DFA for a search.</li> |
| <li><a href="enum.AhoCorasickKind.html#variant.DFA" title="AhoCorasickKind::DFA"><code>AhoCorasickKind::DFA</code></a> instructs the searcher to use a |
| <a href="dfa/struct.DFA.html" title="dfa::DFA"><code>dfa::DFA</code></a>. A DFA is very slow to build, uses exorbitant amounts of |
| memory, but will typically execute searches the fastest.</li> |
| <li><code>None</code> (the default) instructs the searcher to choose the “best” |
| Aho-Corasick implementation. This choice is typically based primarily |
| on the number of patterns.</li> |
| </ul> |
| <p>Setting this configuration does not change the time complexity for |
| constructing the Aho-Corasick automaton (which is <code>O(p)</code> where <code>p</code> |
| is the total number of patterns being compiled). Setting this to |
| <a href="enum.AhoCorasickKind.html#variant.DFA" title="AhoCorasickKind::DFA"><code>AhoCorasickKind::DFA</code></a> does however reduce the time complexity of |
| non-overlapping searches from <code>O(n + p)</code> to <code>O(n)</code>, where <code>n</code> is the |
| length of the haystack.</p> |
| <p>In general, you should probably stick to the default unless you have |
| some kind of reason to use a specific Aho-Corasick implementation. For |
| example, you might choose <code>AhoCorasickKind::DFA</code> if you don’t care |
| about memory usage and want the fastest possible search times.</p> |
| <p>Setting this guarantees that the searcher returned uses the chosen |
| implementation. If that implementation could not be constructed, then |
| an error will be returned. In contrast, when <code>None</code> is used, it is |
| possible for it to attempt to construct, for example, a contiguous |
| NFA and have it fail. In which case, it will fall back to using a |
| noncontiguous NFA.</p> |
| <p>If <code>None</code> is given, then one may use <a href="struct.AhoCorasick.html#method.kind" title="AhoCorasick::kind"><code>AhoCorasick::kind</code></a> to determine |
| which Aho-Corasick implementation was chosen.</p> |
| <p>Note that the heuristics used for choosing which <code>AhoCorasickKind</code> |
| may be changed in a semver compatible release.</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.prefilter" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2547-2552">source</a><h4 class="code-header">pub fn <a href="#method.prefilter" class="fnname">prefilter</a>(&mut self, yes: bool) -> &mut <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class="docblock"><p>Enable heuristic prefilter optimizations.</p> |
| <p>When enabled, searching will attempt to quickly skip to match |
| candidates using specialized literal search routines. A prefilter |
| cannot always be used, and is generally treated as a heuristic. It |
| can be useful to disable this if the prefilter is observed to be |
| sub-optimal for a particular workload.</p> |
| <p>Currently, prefilters are typically only active when building searchers |
| with a small (less than 100) number of patterns.</p> |
| <p>This is enabled by default.</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.dense_depth" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2581-2584">source</a><h4 class="code-header">pub fn <a href="#method.dense_depth" class="fnname">dense_depth</a>(&mut self, depth: usize) -> &mut <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class="docblock"><p>Set the limit on how many states use a dense representation for their |
| transitions. Other states will generally use a sparse representation.</p> |
| <p>A dense representation uses more memory but is generally faster, since |
| the next transition in a dense representation can be computed in a |
| constant number of instructions. A sparse representation uses less |
| memory but is generally slower, since the next transition in a sparse |
| representation requires executing a variable number of instructions.</p> |
| <p>This setting is only used when an Aho-Corasick implementation is used |
| that supports the dense versus sparse representation trade off. Not all |
| do.</p> |
| <p>This limit is expressed in terms of the depth of a state, i.e., the |
| number of transitions from the starting state of the automaton. The |
| idea is that most of the time searching will be spent near the starting |
| state of the automaton, so states near the start state should use a |
| dense representation. States further away from the start state would |
| then use a sparse representation.</p> |
| <p>By default, this is set to a low but non-zero number. Setting this to |
| <code>0</code> is almost never what you want, since it is likely to make searches |
| very slow due to the start state itself being forced to use a sparse |
| representation. However, it is unlikely that increasing this number |
| will help things much, since the most active states have a small depth. |
| More to the point, the memory usage increases superlinearly as this |
| number increases.</p> |
| </div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.byte_classes" class="method has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2611-2615">source</a><h4 class="code-header">pub fn <a href="#method.byte_classes" class="fnname">byte_classes</a>(&mut self, yes: bool) -> &mut <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class="docblock"><p>A debug settting for whether to attempt to shrink the size of the |
| automaton’s alphabet or not.</p> |
| <p>This option is enabled by default and should never be disabled unless |
| one is debugging the underlying automaton.</p> |
| <p>When enabled, some (but not all) Aho-Corasick automatons will use a map |
| from all possible bytes to their corresponding equivalence class. Each |
| equivalence class represents a set of bytes that does not discriminate |
| between a match and a non-match in the automaton.</p> |
| <p>The advantage of this map is that the size of the transition table can |
| be reduced drastically from <code>#states * 256 * sizeof(u32)</code> to |
| <code>#states * k * sizeof(u32)</code> where <code>k</code> is the number of equivalence |
| classes (rounded up to the nearest power of 2). As a result, total |
| space usage can decrease substantially. Moreover, since a smaller |
| alphabet is used, automaton compilation becomes faster as well.</p> |
| <p><strong>WARNING:</strong> This is only useful for debugging automatons. Disabling |
| this does not yield any speed advantages. Namely, even when this is |
| disabled, a byte class map is still used while searching. The only |
| difference is that every byte will be forced into its own distinct |
| equivalence class. This is useful for debugging the actual generated |
| transitions because it lets one see the transitions defined on actual |
| bytes instead of the equivalence classes.</p> |
| </div></details></div></details></div><h2 id="trait-implementations" class="small-section-header">Trait Implementations<a href="#trait-implementations" class="anchor"></a></h2><div id="trait-implementations-list"><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-Clone-for-AhoCorasickBuilder" class="impl has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2134">source</a><a href="#impl-Clone-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl Clone for <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.clone" class="method trait-impl has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2134">source</a><a href="#method.clone" class="anchor"></a><h4 class="code-header">fn <a class="fnname">clone</a>(&self) -> <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class='docblock'>Returns a copy of the value. <a>Read more</a></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.clone_from" class="method trait-impl has-srclink"><span class="since rightside" title="Stable since Rust version 1.0.0">1.0.0</span><a href="#method.clone_from" class="anchor"></a><h4 class="code-header">const fn <a class="fnname">clone_from</a>(&mut self, source: &Self)</h4></section></summary><div class='docblock'>Performs copy-assignment from <code>source</code>. <a>Read more</a></div></details></div></details><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-Debug-for-AhoCorasickBuilder" class="impl has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2134">source</a><a href="#impl-Debug-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl Debug for <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.fmt" class="method trait-impl has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2134">source</a><a href="#method.fmt" class="anchor"></a><h4 class="code-header">fn <a class="fnname">fmt</a>(&self, f: &mut Formatter<'_>) -> Result</h4></section></summary><div class='docblock'>Formats the value using the given formatter. <a>Read more</a></div></details></div></details><details class="rustdoc-toggle implementors-toggle" open><summary><section id="impl-Default-for-AhoCorasickBuilder" class="impl has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2134">source</a><a href="#impl-Default-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl Default for <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.default" class="method trait-impl has-srclink"><a class="srclink rightside" href="../src/aho_corasick/ahocorasick.rs.html#2134">source</a><a href="#method.default" class="anchor"></a><h4 class="code-header">fn <a class="fnname">default</a>() -> <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h4></section></summary><div class='docblock'>Returns the “default value” for a type. <a>Read more</a></div></details></div></details></div><h2 id="synthetic-implementations" class="small-section-header">Auto Trait Implementations<a href="#synthetic-implementations" class="anchor"></a></h2><div id="synthetic-implementations-list"><section id="impl-RefUnwindSafe-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-RefUnwindSafe-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl RefUnwindSafe for <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section><section id="impl-Send-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-Send-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl Send for <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section><section id="impl-Sync-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-Sync-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl Sync for <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section><section id="impl-Unpin-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-Unpin-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl Unpin for <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section><section id="impl-UnwindSafe-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-UnwindSafe-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl UnwindSafe for <a class="struct" href="struct.AhoCorasickBuilder.html" title="struct aho_corasick::AhoCorasickBuilder">AhoCorasickBuilder</a></h3></section></div><h2 id="blanket-implementations" class="small-section-header">Blanket Implementations<a href="#blanket-implementations" class="anchor"></a></h2><div id="blanket-implementations-list"><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-Any-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-Any-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl<T> Any for T<span class="where fmt-newline">where<br> T: 'static + ?Sized,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.type_id" class="method trait-impl has-srclink"><a href="#method.type_id" class="anchor"></a><h4 class="code-header">fn <a class="fnname">type_id</a>(&self) -> TypeId</h4></section></summary><div class='docblock'>Gets the <code>TypeId</code> of <code>self</code>. <a>Read more</a></div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-Borrow%3CT%3E-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-Borrow%3CT%3E-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl<T> Borrow<T> for T<span class="where fmt-newline">where<br> T: ?Sized,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.borrow" class="method trait-impl has-srclink"><span class="since rightside" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/91522" title="Tracking issue for const_borrow">unstable</a></span><a href="#method.borrow" class="anchor"></a><h4 class="code-header">fn <a class="fnname">borrow</a>(&self) -> &T</h4></section></summary><div class='docblock'>Immutably borrows from an owned value. <a>Read more</a></div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-BorrowMut%3CT%3E-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-BorrowMut%3CT%3E-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl<T> BorrowMut<T> for T<span class="where fmt-newline">where<br> T: ?Sized,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.borrow_mut" class="method trait-impl has-srclink"><span class="since rightside" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/91522" title="Tracking issue for const_borrow">unstable</a></span><a href="#method.borrow_mut" class="anchor"></a><h4 class="code-header">fn <a class="fnname">borrow_mut</a>(&mut self) -> &mut T</h4></section></summary><div class='docblock'>Mutably borrows from an owned value. <a>Read more</a></div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-From%3CT%3E-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-From%3CT%3E-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl<T> From<T> for T</h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.from" class="method trait-impl has-srclink"><span class="since rightside" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/88674" title="Tracking issue for const_convert">unstable</a></span><a href="#method.from" class="anchor"></a><h4 class="code-header">fn <a class="fnname">from</a>(t: T) -> T</h4></section></summary><div class="docblock"><p>Returns the argument unchanged.</p> |
| </div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-Into%3CU%3E-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-Into%3CU%3E-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl<T, U> Into<U> for T<span class="where fmt-newline">where<br> U: From<T>,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle method-toggle" open><summary><section id="method.into" class="method trait-impl has-srclink"><span class="since rightside" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/88674" title="Tracking issue for const_convert">unstable</a></span><a href="#method.into" class="anchor"></a><h4 class="code-header">fn <a class="fnname">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>[From]<T> for U</code> chooses to do.</p> |
| </div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-ToOwned-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-ToOwned-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl<T> ToOwned for T<span class="where fmt-newline">where<br> T: Clone,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle" open><summary><section id="associatedtype.Owned" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Owned" class="anchor"></a><h4 class="code-header">type <a class="associatedtype">Owned</a> = T</h4></section></summary><div class='docblock'>The resulting type after obtaining ownership.</div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.to_owned" class="method trait-impl has-srclink"><a href="#method.to_owned" class="anchor"></a><h4 class="code-header">fn <a class="fnname">to_owned</a>(&self) -> T</h4></section></summary><div class='docblock'>Creates owned data from borrowed data, usually by cloning. <a>Read more</a></div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.clone_into" class="method trait-impl has-srclink"><a href="#method.clone_into" class="anchor"></a><h4 class="code-header">fn <a class="fnname">clone_into</a>(&self, target: &mut T)</h4></section></summary><div class='docblock'>Uses borrowed data to replace owned data, usually by cloning. <a>Read more</a></div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-TryFrom%3CU%3E-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-TryFrom%3CU%3E-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl<T, U> TryFrom<U> for T<span class="where fmt-newline">where<br> U: Into<T>,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle" open><summary><section id="associatedtype.Error-1" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Error-1" class="anchor"></a><h4 class="code-header">type <a class="associatedtype">Error</a> = Infallible</h4></section></summary><div class='docblock'>The type returned in the event of a conversion error.</div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.try_from" class="method trait-impl has-srclink"><span class="since rightside" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/88674" title="Tracking issue for const_convert">unstable</a></span><a href="#method.try_from" class="anchor"></a><h4 class="code-header">fn <a class="fnname">try_from</a>(value: U) -> Result<T, <T as TryFrom<U>>::Error></h4></section></summary><div class='docblock'>Performs the conversion.</div></details></div></details><details class="rustdoc-toggle implementors-toggle"><summary><section id="impl-TryInto%3CU%3E-for-AhoCorasickBuilder" class="impl has-srclink"><a href="#impl-TryInto%3CU%3E-for-AhoCorasickBuilder" class="anchor"></a><h3 class="code-header">impl<T, U> TryInto<U> for T<span class="where fmt-newline">where<br> U: TryFrom<T>,</span></h3></section></summary><div class="impl-items"><details class="rustdoc-toggle" open><summary><section id="associatedtype.Error" class="associatedtype trait-impl has-srclink"><a href="#associatedtype.Error" class="anchor"></a><h4 class="code-header">type <a class="associatedtype">Error</a> = <U as TryFrom<T>>::Error</h4></section></summary><div class='docblock'>The type returned in the event of a conversion error.</div></details><details class="rustdoc-toggle method-toggle" open><summary><section id="method.try_into" class="method trait-impl has-srclink"><span class="since rightside" title="const unstable">const: <a href="https://github.com/rust-lang/rust/issues/88674" title="Tracking issue for const_convert">unstable</a></span><a href="#method.try_into" class="anchor"></a><h4 class="code-header">fn <a class="fnname">try_into</a>(self) -> Result<U, <U as TryFrom<T>>::Error></h4></section></summary><div class='docblock'>Performs the conversion.</div></details></div></details></div></section></div></main><div id="rustdoc-vars" data-root-path="../" data-current-crate="aho_corasick" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (5c8bff74b 2022-10-21)" ></div></body></html> |
