blob: fdc527c00907b43fc1359c90d01cdaeaefb4cb4e [file] [log] [blame]
<!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="Source of the Rust file `/root/.cargo/registry/src/github.com-1ecc6299db9ec823/memchr-2.5.0/src/memmem/rabinkarp.rs`."><meta name="keywords" content="rust, rustlang, rust-lang"><title>rabinkarp.rs - source</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="../../../source-script.js"></script><script defer src="../../../source-files.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 source"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><a class="sidebar-logo" href="../../../memchr/index.html"><div class="logo-container"><img class="rust-logo" src="../../../rust-logo.svg" alt="logo"></div></a></nav><main><div class="width-limiter"><nav class="sub"><a class="sub-logo-container" href="../../../memchr/index.html"><img class="rust-logo" src="../../../rust-logo.svg" alt="logo"></a><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="example-wrap"><pre class="src-line-numbers"><span id="1">1</span>
<span id="2">2</span>
<span id="3">3</span>
<span id="4">4</span>
<span id="5">5</span>
<span id="6">6</span>
<span id="7">7</span>
<span id="8">8</span>
<span id="9">9</span>
<span id="10">10</span>
<span id="11">11</span>
<span id="12">12</span>
<span id="13">13</span>
<span id="14">14</span>
<span id="15">15</span>
<span id="16">16</span>
<span id="17">17</span>
<span id="18">18</span>
<span id="19">19</span>
<span id="20">20</span>
<span id="21">21</span>
<span id="22">22</span>
<span id="23">23</span>
<span id="24">24</span>
<span id="25">25</span>
<span id="26">26</span>
<span id="27">27</span>
<span id="28">28</span>
<span id="29">29</span>
<span id="30">30</span>
<span id="31">31</span>
<span id="32">32</span>
<span id="33">33</span>
<span id="34">34</span>
<span id="35">35</span>
<span id="36">36</span>
<span id="37">37</span>
<span id="38">38</span>
<span id="39">39</span>
<span id="40">40</span>
<span id="41">41</span>
<span id="42">42</span>
<span id="43">43</span>
<span id="44">44</span>
<span id="45">45</span>
<span id="46">46</span>
<span id="47">47</span>
<span id="48">48</span>
<span id="49">49</span>
<span id="50">50</span>
<span id="51">51</span>
<span id="52">52</span>
<span id="53">53</span>
<span id="54">54</span>
<span id="55">55</span>
<span id="56">56</span>
<span id="57">57</span>
<span id="58">58</span>
<span id="59">59</span>
<span id="60">60</span>
<span id="61">61</span>
<span id="62">62</span>
<span id="63">63</span>
<span id="64">64</span>
<span id="65">65</span>
<span id="66">66</span>
<span id="67">67</span>
<span id="68">68</span>
<span id="69">69</span>
<span id="70">70</span>
<span id="71">71</span>
<span id="72">72</span>
<span id="73">73</span>
<span id="74">74</span>
<span id="75">75</span>
<span id="76">76</span>
<span id="77">77</span>
<span id="78">78</span>
<span id="79">79</span>
<span id="80">80</span>
<span id="81">81</span>
<span id="82">82</span>
<span id="83">83</span>
<span id="84">84</span>
<span id="85">85</span>
<span id="86">86</span>
<span id="87">87</span>
<span id="88">88</span>
<span id="89">89</span>
<span id="90">90</span>
<span id="91">91</span>
<span id="92">92</span>
<span id="93">93</span>
<span id="94">94</span>
<span id="95">95</span>
<span id="96">96</span>
<span id="97">97</span>
<span id="98">98</span>
<span id="99">99</span>
<span id="100">100</span>
<span id="101">101</span>
<span id="102">102</span>
<span id="103">103</span>
<span id="104">104</span>
<span id="105">105</span>
<span id="106">106</span>
<span id="107">107</span>
<span id="108">108</span>
<span id="109">109</span>
<span id="110">110</span>
<span id="111">111</span>
<span id="112">112</span>
<span id="113">113</span>
<span id="114">114</span>
<span id="115">115</span>
<span id="116">116</span>
<span id="117">117</span>
<span id="118">118</span>
<span id="119">119</span>
<span id="120">120</span>
<span id="121">121</span>
<span id="122">122</span>
<span id="123">123</span>
<span id="124">124</span>
<span id="125">125</span>
<span id="126">126</span>
<span id="127">127</span>
<span id="128">128</span>
<span id="129">129</span>
<span id="130">130</span>
<span id="131">131</span>
<span id="132">132</span>
<span id="133">133</span>
<span id="134">134</span>
<span id="135">135</span>
<span id="136">136</span>
<span id="137">137</span>
<span id="138">138</span>
<span id="139">139</span>
<span id="140">140</span>
<span id="141">141</span>
<span id="142">142</span>
<span id="143">143</span>
<span id="144">144</span>
<span id="145">145</span>
<span id="146">146</span>
<span id="147">147</span>
<span id="148">148</span>
<span id="149">149</span>
<span id="150">150</span>
<span id="151">151</span>
<span id="152">152</span>
<span id="153">153</span>
<span id="154">154</span>
<span id="155">155</span>
<span id="156">156</span>
<span id="157">157</span>
<span id="158">158</span>
<span id="159">159</span>
<span id="160">160</span>
<span id="161">161</span>
<span id="162">162</span>
<span id="163">163</span>
<span id="164">164</span>
<span id="165">165</span>
<span id="166">166</span>
<span id="167">167</span>
<span id="168">168</span>
<span id="169">169</span>
<span id="170">170</span>
<span id="171">171</span>
<span id="172">172</span>
<span id="173">173</span>
<span id="174">174</span>
<span id="175">175</span>
<span id="176">176</span>
<span id="177">177</span>
<span id="178">178</span>
<span id="179">179</span>
<span id="180">180</span>
<span id="181">181</span>
<span id="182">182</span>
<span id="183">183</span>
<span id="184">184</span>
<span id="185">185</span>
<span id="186">186</span>
<span id="187">187</span>
<span id="188">188</span>
<span id="189">189</span>
<span id="190">190</span>
<span id="191">191</span>
<span id="192">192</span>
<span id="193">193</span>
<span id="194">194</span>
<span id="195">195</span>
<span id="196">196</span>
<span id="197">197</span>
<span id="198">198</span>
<span id="199">199</span>
<span id="200">200</span>
<span id="201">201</span>
<span id="202">202</span>
<span id="203">203</span>
<span id="204">204</span>
<span id="205">205</span>
<span id="206">206</span>
<span id="207">207</span>
<span id="208">208</span>
<span id="209">209</span>
<span id="210">210</span>
<span id="211">211</span>
<span id="212">212</span>
<span id="213">213</span>
<span id="214">214</span>
<span id="215">215</span>
<span id="216">216</span>
<span id="217">217</span>
<span id="218">218</span>
<span id="219">219</span>
<span id="220">220</span>
<span id="221">221</span>
<span id="222">222</span>
<span id="223">223</span>
<span id="224">224</span>
<span id="225">225</span>
<span id="226">226</span>
<span id="227">227</span>
<span id="228">228</span>
<span id="229">229</span>
<span id="230">230</span>
<span id="231">231</span>
<span id="232">232</span>
<span id="233">233</span>
</pre><pre class="rust"><code><span class="comment">/*
This module implements the classical Rabin-Karp substring search algorithm,
with no extra frills. While its use would seem to break our time complexity
guarantee of O(m+n) (RK&#39;s time complexity is O(mn)), we are careful to only
ever use RK on a constant subset of haystacks. The main point here is that
RK has good latency properties for small needles/haystacks. It&#39;s very quick
to compute a needle hash and zip through the haystack when compared to
initializing Two-Way, for example. And this is especially useful for cases
where the haystack is just too short for vector instructions to do much good.
The hashing function used here is the same one recommended by ESMAJ.
Another choice instead of Rabin-Karp would be Shift-Or. But its latency
isn&#39;t quite as good since its preprocessing time is a bit more expensive
(both in practice and in theory). However, perhaps Shift-Or has a place
somewhere else for short patterns. I think the main problem is that it
requires space proportional to the alphabet and the needle. If we, for
example, supported needles up to length 16, then the total table size would be
len(alphabet)*size_of::&lt;u16&gt;()==512 bytes. Which isn&#39;t exactly small, and it&#39;s
probably bad to put that on the stack. So ideally, we&#39;d throw it on the heap,
but we&#39;d really like to write as much code without using alloc/std as possible.
But maybe it&#39;s worth the special casing. It&#39;s a TODO to benchmark.
Wikipedia has a decent explanation, if a bit heavy on the theory:
https://en.wikipedia.org/wiki/Rabin%E2%80%93Karp_algorithm
But ESMAJ provides something a bit more concrete:
http://www-igm.univ-mlv.fr/~lecroq/string/node5.html
Finally, aho-corasick uses Rabin-Karp for multiple pattern match in some cases:
https://github.com/BurntSushi/aho-corasick/blob/3852632f10587db0ff72ef29e88d58bf305a0946/src/packed/rabinkarp.rs
*/
</span><span class="doccomment">/// Whether RK is believed to be very fast for the given needle/haystack.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>is_fast(haystack: <span class="kw-2">&amp;</span>[u8], _needle: <span class="kw-2">&amp;</span>[u8]) -&gt; bool {
haystack.len() &lt; <span class="number">16
</span>}
<span class="doccomment">/// Search for the first occurrence of needle in haystack using Rabin-Karp.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>find(haystack: <span class="kw-2">&amp;</span>[u8], needle: <span class="kw-2">&amp;</span>[u8]) -&gt; <span class="prelude-ty">Option</span>&lt;usize&gt; {
find_with(<span class="kw-2">&amp;</span>NeedleHash::forward(needle), haystack, needle)
}
<span class="doccomment">/// Search for the first occurrence of needle in haystack using Rabin-Karp with
/// a pre-computed needle hash.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>find_with(
nhash: <span class="kw-2">&amp;</span>NeedleHash,
<span class="kw-2">mut </span>haystack: <span class="kw-2">&amp;</span>[u8],
needle: <span class="kw-2">&amp;</span>[u8],
) -&gt; <span class="prelude-ty">Option</span>&lt;usize&gt; {
<span class="kw">if </span>haystack.len() &lt; needle.len() {
<span class="kw">return </span><span class="prelude-val">None</span>;
}
<span class="kw">let </span>start = haystack.as_ptr() <span class="kw">as </span>usize;
<span class="kw">let </span><span class="kw-2">mut </span>hash = Hash::from_bytes_fwd(<span class="kw-2">&amp;</span>haystack[..needle.len()]);
<span class="comment">// N.B. I&#39;ve experimented with unrolling this loop, but couldn&#39;t realize
// any obvious gains.
</span><span class="kw">loop </span>{
<span class="kw">if </span>nhash.eq(hash) &amp;&amp; is_prefix(haystack, needle) {
<span class="kw">return </span><span class="prelude-val">Some</span>(haystack.as_ptr() <span class="kw">as </span>usize - start);
}
<span class="kw">if </span>needle.len() &gt;= haystack.len() {
<span class="kw">return </span><span class="prelude-val">None</span>;
}
hash.roll(<span class="kw-2">&amp;</span>nhash, haystack[<span class="number">0</span>], haystack[needle.len()]);
haystack = <span class="kw-2">&amp;</span>haystack[<span class="number">1</span>..];
}
}
<span class="doccomment">/// Search for the last occurrence of needle in haystack using Rabin-Karp.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>rfind(haystack: <span class="kw-2">&amp;</span>[u8], needle: <span class="kw-2">&amp;</span>[u8]) -&gt; <span class="prelude-ty">Option</span>&lt;usize&gt; {
rfind_with(<span class="kw-2">&amp;</span>NeedleHash::reverse(needle), haystack, needle)
}
<span class="doccomment">/// Search for the last occurrence of needle in haystack using Rabin-Karp with
/// a pre-computed needle hash.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>rfind_with(
nhash: <span class="kw-2">&amp;</span>NeedleHash,
<span class="kw-2">mut </span>haystack: <span class="kw-2">&amp;</span>[u8],
needle: <span class="kw-2">&amp;</span>[u8],
) -&gt; <span class="prelude-ty">Option</span>&lt;usize&gt; {
<span class="kw">if </span>haystack.len() &lt; needle.len() {
<span class="kw">return </span><span class="prelude-val">None</span>;
}
<span class="kw">let </span><span class="kw-2">mut </span>hash =
Hash::from_bytes_rev(<span class="kw-2">&amp;</span>haystack[haystack.len() - needle.len()..]);
<span class="kw">loop </span>{
<span class="kw">if </span>nhash.eq(hash) &amp;&amp; is_suffix(haystack, needle) {
<span class="kw">return </span><span class="prelude-val">Some</span>(haystack.len() - needle.len());
}
<span class="kw">if </span>needle.len() &gt;= haystack.len() {
<span class="kw">return </span><span class="prelude-val">None</span>;
}
hash.roll(
<span class="kw-2">&amp;</span>nhash,
haystack[haystack.len() - <span class="number">1</span>],
haystack[haystack.len() - needle.len() - <span class="number">1</span>],
);
haystack = <span class="kw-2">&amp;</span>haystack[..haystack.len() - <span class="number">1</span>];
}
}
<span class="doccomment">/// A hash derived from a needle.
</span><span class="attribute">#[derive(Clone, Copy, Debug, Default)]
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">struct </span>NeedleHash {
<span class="doccomment">/// The actual hash.
</span>hash: Hash,
<span class="doccomment">/// The factor needed to multiply a byte by in order to subtract it from
/// the hash. It is defined to be 2^(n-1) (using wrapping exponentiation),
/// where n is the length of the needle. This is how we &quot;remove&quot; a byte
/// from the hash once the hash window rolls past it.
</span>hash_2pow: u32,
}
<span class="kw">impl </span>NeedleHash {
<span class="doccomment">/// Create a new Rabin-Karp hash for the given needle for use in forward
/// searching.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>forward(needle: <span class="kw-2">&amp;</span>[u8]) -&gt; NeedleHash {
<span class="kw">let </span><span class="kw-2">mut </span>nh = NeedleHash { hash: Hash::new(), hash_2pow: <span class="number">1 </span>};
<span class="kw">if </span>needle.is_empty() {
<span class="kw">return </span>nh;
}
nh.hash.add(needle[<span class="number">0</span>]);
<span class="kw">for </span><span class="kw-2">&amp;</span>b <span class="kw">in </span>needle.iter().skip(<span class="number">1</span>) {
nh.hash.add(b);
nh.hash_2pow = nh.hash_2pow.wrapping_shl(<span class="number">1</span>);
}
nh
}
<span class="doccomment">/// Create a new Rabin-Karp hash for the given needle for use in reverse
/// searching.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>reverse(needle: <span class="kw-2">&amp;</span>[u8]) -&gt; NeedleHash {
<span class="kw">let </span><span class="kw-2">mut </span>nh = NeedleHash { hash: Hash::new(), hash_2pow: <span class="number">1 </span>};
<span class="kw">if </span>needle.is_empty() {
<span class="kw">return </span>nh;
}
nh.hash.add(needle[needle.len() - <span class="number">1</span>]);
<span class="kw">for </span><span class="kw-2">&amp;</span>b <span class="kw">in </span>needle.iter().rev().skip(<span class="number">1</span>) {
nh.hash.add(b);
nh.hash_2pow = nh.hash_2pow.wrapping_shl(<span class="number">1</span>);
}
nh
}
<span class="doccomment">/// Return true if the hashes are equivalent.
</span><span class="kw">fn </span>eq(<span class="kw-2">&amp;</span><span class="self">self</span>, hash: Hash) -&gt; bool {
<span class="self">self</span>.hash == hash
}
}
<span class="doccomment">/// A Rabin-Karp hash. This might represent the hash of a needle, or the hash
/// of a rolling window in the haystack.
</span><span class="attribute">#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">struct </span>Hash(u32);
<span class="kw">impl </span>Hash {
<span class="doccomment">/// Create a new hash that represents the empty string.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>new() -&gt; Hash {
Hash(<span class="number">0</span>)
}
<span class="doccomment">/// Create a new hash from the bytes given for use in forward searches.
</span><span class="kw">pub</span>(<span class="kw">crate</span>) <span class="kw">fn </span>from_bytes_fwd(bytes: <span class="kw-2">&amp;</span>[u8]) -&gt; Hash {
<span class="kw">let </span><span class="kw-2">mut </span>hash = Hash::new();
<span class="kw">for </span><span class="kw-2">&amp;</span>b <span class="kw">in </span>bytes {
hash.add(b);
}
hash
}
<span class="doccomment">/// Create a new hash from the bytes given for use in reverse searches.
</span><span class="kw">fn </span>from_bytes_rev(bytes: <span class="kw-2">&amp;</span>[u8]) -&gt; Hash {
<span class="kw">let </span><span class="kw-2">mut </span>hash = Hash::new();
<span class="kw">for </span><span class="kw-2">&amp;</span>b <span class="kw">in </span>bytes.iter().rev() {
hash.add(b);
}
hash
}
<span class="doccomment">/// Add &#39;new&#39; and remove &#39;old&#39; from this hash. The given needle hash should
/// correspond to the hash computed for the needle being searched for.
///
/// This is meant to be used when the rolling window of the haystack is
/// advanced.
</span><span class="kw">fn </span>roll(<span class="kw-2">&amp;mut </span><span class="self">self</span>, nhash: <span class="kw-2">&amp;</span>NeedleHash, old: u8, new: u8) {
<span class="self">self</span>.del(nhash, old);
<span class="self">self</span>.add(new);
}
<span class="doccomment">/// Add a byte to this hash.
</span><span class="kw">fn </span>add(<span class="kw-2">&amp;mut </span><span class="self">self</span>, byte: u8) {
<span class="self">self</span>.<span class="number">0 </span>= <span class="self">self</span>.<span class="number">0</span>.wrapping_shl(<span class="number">1</span>).wrapping_add(byte <span class="kw">as </span>u32);
}
<span class="doccomment">/// Remove a byte from this hash. The given needle hash should correspond
/// to the hash computed for the needle being searched for.
</span><span class="kw">fn </span>del(<span class="kw-2">&amp;mut </span><span class="self">self</span>, nhash: <span class="kw-2">&amp;</span>NeedleHash, byte: u8) {
<span class="kw">let </span>factor = nhash.hash_2pow;
<span class="self">self</span>.<span class="number">0 </span>= <span class="self">self</span>.<span class="number">0</span>.wrapping_sub((byte <span class="kw">as </span>u32).wrapping_mul(factor));
}
}
<span class="doccomment">/// Returns true if the given needle is a prefix of the given haystack.
///
/// We forcefully don&#39;t inline the is_prefix call and hint at the compiler that
/// it is unlikely to be called. This causes the inner rabinkarp loop above
/// to be a bit tighter and leads to some performance improvement. See the
/// memmem/krate/prebuilt/sliceslice-words/words benchmark.
</span><span class="attribute">#[cold]
#[inline(never)]
</span><span class="kw">fn </span>is_prefix(haystack: <span class="kw-2">&amp;</span>[u8], needle: <span class="kw-2">&amp;</span>[u8]) -&gt; bool {
<span class="kw">crate</span>::memmem::util::is_prefix(haystack, needle)
}
<span class="doccomment">/// Returns true if the given needle is a suffix of the given haystack.
///
/// See is_prefix for why this is forcefully not inlined.
</span><span class="attribute">#[cold]
#[inline(never)]
</span><span class="kw">fn </span>is_suffix(haystack: <span class="kw-2">&amp;</span>[u8], needle: <span class="kw-2">&amp;</span>[u8]) -&gt; bool {
<span class="kw">crate</span>::memmem::util::is_suffix(haystack, needle)
}
<span class="attribute">#[cfg(test)]
</span><span class="kw">mod </span>simpletests {
<span class="macro">define_memmem_simple_tests!</span>(<span class="kw">super</span>::find, <span class="kw">super</span>::rfind);
}
<span class="attribute">#[cfg(all(test, feature = <span class="string">&quot;std&quot;</span>, not(miri)))]
</span><span class="kw">mod </span>proptests {
<span class="macro">define_memmem_quickcheck_tests!</span>(<span class="kw">super</span>::find, <span class="kw">super</span>::rfind);
}
</code></pre></div>
</section></div></main><div id="rustdoc-vars" data-root-path="../../../" data-current-crate="memchr" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (5c8bff74b 2022-10-21)" ></div></body></html>