core\str/
pattern.rs

1//! The string Pattern API.
2//!
3//! The Pattern API provides a generic mechanism for using different pattern
4//! types when searching through a string.
5//!
6//! For more details, see the traits [`Pattern`], [`Searcher`],
7//! [`ReverseSearcher`], and [`DoubleEndedSearcher`].
8//!
9//! Although this API is unstable, it is exposed via stable APIs on the
10//! [`str`] type.
11//!
12//! # Examples
13//!
14//! [`Pattern`] is [implemented][pattern-impls] in the stable API for
15//! [`&str`][`str`], [`char`], slices of [`char`], and functions and closures
16//! implementing `FnMut(char) -> bool`.
17//!
18//! ```
19//! let s = "Can you find a needle in a haystack?";
20//!
21//! // &str pattern
22//! assert_eq!(s.find("you"), Some(4));
23//! // char pattern
24//! assert_eq!(s.find('n'), Some(2));
25//! // array of chars pattern
26//! assert_eq!(s.find(&['a', 'e', 'i', 'o', 'u']), Some(1));
27//! // slice of chars pattern
28//! assert_eq!(s.find(&['a', 'e', 'i', 'o', 'u'][..]), Some(1));
29//! // closure pattern
30//! assert_eq!(s.find(|c: char| c.is_ascii_punctuation()), Some(35));
31//! ```
32//!
33//! [pattern-impls]: Pattern#implementors
34
35#![unstable(
36    feature = "pattern",
37    reason = "API not fully fleshed out and ready to be stabilized",
38    issue = "27721"
39)]
40
41use crate::char::MAX_LEN_UTF8;
42use crate::cmp::Ordering;
43use crate::convert::TryInto as _;
44use crate::slice::memchr;
45use crate::{cmp, fmt};
46
47// Pattern
48
49/// A string pattern.
50///
51/// A `Pattern` expresses that the implementing type
52/// can be used as a string pattern for searching in a [`&str`][str].
53///
54/// For example, both `'a'` and `"aa"` are patterns that
55/// would match at index `1` in the string `"baaaab"`.
56///
57/// The trait itself acts as a builder for an associated
58/// [`Searcher`] type, which does the actual work of finding
59/// occurrences of the pattern in a string.
60///
61/// Depending on the type of the pattern, the behavior of methods like
62/// [`str::find`] and [`str::contains`] can change. The table below describes
63/// some of those behaviors.
64///
65/// | Pattern type             | Match condition                           |
66/// |--------------------------|-------------------------------------------|
67/// | `&str`                   | is substring                              |
68/// | `char`                   | is contained in string                    |
69/// | `&[char]`                | any char in slice is contained in string  |
70/// | `F: FnMut(char) -> bool` | `F` returns `true` for a char in string   |
71/// | `&&str`                  | is substring                              |
72/// | `&String`                | is substring                              |
73///
74/// # Examples
75///
76/// ```
77/// // &str
78/// assert_eq!("abaaa".find("ba"), Some(1));
79/// assert_eq!("abaaa".find("bac"), None);
80///
81/// // char
82/// assert_eq!("abaaa".find('a'), Some(0));
83/// assert_eq!("abaaa".find('b'), Some(1));
84/// assert_eq!("abaaa".find('c'), None);
85///
86/// // &[char; N]
87/// assert_eq!("ab".find(&['b', 'a']), Some(0));
88/// assert_eq!("abaaa".find(&['a', 'z']), Some(0));
89/// assert_eq!("abaaa".find(&['c', 'd']), None);
90///
91/// // &[char]
92/// assert_eq!("ab".find(&['b', 'a'][..]), Some(0));
93/// assert_eq!("abaaa".find(&['a', 'z'][..]), Some(0));
94/// assert_eq!("abaaa".find(&['c', 'd'][..]), None);
95///
96/// // FnMut(char) -> bool
97/// assert_eq!("abcdef_z".find(|ch| ch > 'd' && ch < 'y'), Some(4));
98/// assert_eq!("abcddd_z".find(|ch| ch > 'd' && ch < 'y'), None);
99/// ```
100pub trait Pattern: Sized {
101    /// Associated searcher for this pattern
102    type Searcher<'a>: Searcher<'a>;
103
104    /// Constructs the associated searcher from
105    /// `self` and the `haystack` to search in.
106    fn into_searcher(self, haystack: &str) -> Self::Searcher<'_>;
107
108    /// Checks whether the pattern matches anywhere in the haystack
109    #[inline]
110    fn is_contained_in(self, haystack: &str) -> bool {
111        self.into_searcher(haystack).next_match().is_some()
112    }
113
114    /// Checks whether the pattern matches at the front of the haystack
115    #[inline]
116    fn is_prefix_of(self, haystack: &str) -> bool {
117        matches!(self.into_searcher(haystack).next(), SearchStep::Match(0, _))
118    }
119
120    /// Checks whether the pattern matches at the back of the haystack
121    #[inline]
122    fn is_suffix_of<'a>(self, haystack: &'a str) -> bool
123    where
124        Self::Searcher<'a>: ReverseSearcher<'a>,
125    {
126        matches!(self.into_searcher(haystack).next_back(), SearchStep::Match(_, j) if haystack.len() == j)
127    }
128
129    /// Removes the pattern from the front of haystack, if it matches.
130    #[inline]
131    fn strip_prefix_of(self, haystack: &str) -> Option<&str> {
132        if let SearchStep::Match(start, len) = self.into_searcher(haystack).next() {
133            debug_assert_eq!(
134                start, 0,
135                "The first search step from Searcher \
136                 must include the first character"
137            );
138            // SAFETY: `Searcher` is known to return valid indices.
139            unsafe { Some(haystack.get_unchecked(len..)) }
140        } else {
141            None
142        }
143    }
144
145    /// Removes the pattern from the back of haystack, if it matches.
146    #[inline]
147    fn strip_suffix_of<'a>(self, haystack: &'a str) -> Option<&'a str>
148    where
149        Self::Searcher<'a>: ReverseSearcher<'a>,
150    {
151        if let SearchStep::Match(start, end) = self.into_searcher(haystack).next_back() {
152            debug_assert_eq!(
153                end,
154                haystack.len(),
155                "The first search step from ReverseSearcher \
156                 must include the last character"
157            );
158            // SAFETY: `Searcher` is known to return valid indices.
159            unsafe { Some(haystack.get_unchecked(..start)) }
160        } else {
161            None
162        }
163    }
164
165    /// Returns the pattern as utf-8 bytes if possible.
166    fn as_utf8_pattern(&self) -> Option<Utf8Pattern<'_>> {
167        None
168    }
169}
170/// Result of calling [`Pattern::as_utf8_pattern()`].
171/// Can be used for inspecting the contents of a [`Pattern`] in cases
172/// where the underlying representation can be represented as UTF-8.
173#[derive(Copy, Clone, Eq, PartialEq, Debug)]
174pub enum Utf8Pattern<'a> {
175    /// Type returned by String and str types.
176    StringPattern(&'a [u8]),
177    /// Type returned by char types.
178    CharPattern(char),
179}
180
181// Searcher
182
183/// Result of calling [`Searcher::next()`] or [`ReverseSearcher::next_back()`].
184#[derive(Copy, Clone, Eq, PartialEq, Debug)]
185pub enum SearchStep {
186    /// Expresses that a match of the pattern has been found at
187    /// `haystack[a..b]`.
188    Match(usize, usize),
189    /// Expresses that `haystack[a..b]` has been rejected as a possible match
190    /// of the pattern.
191    ///
192    /// Note that there might be more than one `Reject` between two `Match`es,
193    /// there is no requirement for them to be combined into one.
194    Reject(usize, usize),
195    /// Expresses that every byte of the haystack has been visited, ending
196    /// the iteration.
197    Done,
198}
199
200/// A searcher for a string pattern.
201///
202/// This trait provides methods for searching for non-overlapping
203/// matches of a pattern starting from the front (left) of a string.
204///
205/// It will be implemented by associated `Searcher`
206/// types of the [`Pattern`] trait.
207///
208/// The trait is marked unsafe because the indices returned by the
209/// [`next()`][Searcher::next] methods are required to lie on valid utf8
210/// boundaries in the haystack. This enables consumers of this trait to
211/// slice the haystack without additional runtime checks.
212pub unsafe trait Searcher<'a> {
213    /// Getter for the underlying string to be searched in
214    ///
215    /// Will always return the same [`&str`][str].
216    fn haystack(&self) -> &'a str;
217
218    /// Performs the next search step starting from the front.
219    ///
220    /// - Returns [`Match(a, b)`][SearchStep::Match] if `haystack[a..b]` matches
221    ///   the pattern.
222    /// - Returns [`Reject(a, b)`][SearchStep::Reject] if `haystack[a..b]` can
223    ///   not match the pattern, even partially.
224    /// - Returns [`Done`][SearchStep::Done] if every byte of the haystack has
225    ///   been visited.
226    ///
227    /// The stream of [`Match`][SearchStep::Match] and
228    /// [`Reject`][SearchStep::Reject] values up to a [`Done`][SearchStep::Done]
229    /// will contain index ranges that are adjacent, non-overlapping,
230    /// covering the whole haystack, and laying on utf8 boundaries.
231    ///
232    /// A [`Match`][SearchStep::Match] result needs to contain the whole matched
233    /// pattern, however [`Reject`][SearchStep::Reject] results may be split up
234    /// into arbitrary many adjacent fragments. Both ranges may have zero length.
235    ///
236    /// As an example, the pattern `"aaa"` and the haystack `"cbaaaaab"`
237    /// might produce the stream
238    /// `[Reject(0, 1), Reject(1, 2), Match(2, 5), Reject(5, 8)]`
239    fn next(&mut self) -> SearchStep;
240
241    /// Finds the next [`Match`][SearchStep::Match] result. See [`next()`][Searcher::next].
242    ///
243    /// Unlike [`next()`][Searcher::next], there is no guarantee that the returned ranges
244    /// of this and [`next_reject`][Searcher::next_reject] will overlap. This will return
245    /// `(start_match, end_match)`, where start_match is the index of where
246    /// the match begins, and end_match is the index after the end of the match.
247    #[inline]
248    fn next_match(&mut self) -> Option<(usize, usize)> {
249        loop {
250            match self.next() {
251                SearchStep::Match(a, b) => return Some((a, b)),
252                SearchStep::Done => return None,
253                _ => continue,
254            }
255        }
256    }
257
258    /// Finds the next [`Reject`][SearchStep::Reject] result. See [`next()`][Searcher::next]
259    /// and [`next_match()`][Searcher::next_match].
260    ///
261    /// Unlike [`next()`][Searcher::next], there is no guarantee that the returned ranges
262    /// of this and [`next_match`][Searcher::next_match] will overlap.
263    #[inline]
264    fn next_reject(&mut self) -> Option<(usize, usize)> {
265        loop {
266            match self.next() {
267                SearchStep::Reject(a, b) => return Some((a, b)),
268                SearchStep::Done => return None,
269                _ => continue,
270            }
271        }
272    }
273}
274
275/// A reverse searcher for a string pattern.
276///
277/// This trait provides methods for searching for non-overlapping
278/// matches of a pattern starting from the back (right) of a string.
279///
280/// It will be implemented by associated [`Searcher`]
281/// types of the [`Pattern`] trait if the pattern supports searching
282/// for it from the back.
283///
284/// The index ranges returned by this trait are not required
285/// to exactly match those of the forward search in reverse.
286///
287/// For the reason why this trait is marked unsafe, see the
288/// parent trait [`Searcher`].
289pub unsafe trait ReverseSearcher<'a>: Searcher<'a> {
290    /// Performs the next search step starting from the back.
291    ///
292    /// - Returns [`Match(a, b)`][SearchStep::Match] if `haystack[a..b]`
293    ///   matches the pattern.
294    /// - Returns [`Reject(a, b)`][SearchStep::Reject] if `haystack[a..b]`
295    ///   can not match the pattern, even partially.
296    /// - Returns [`Done`][SearchStep::Done] if every byte of the haystack
297    ///   has been visited
298    ///
299    /// The stream of [`Match`][SearchStep::Match] and
300    /// [`Reject`][SearchStep::Reject] values up to a [`Done`][SearchStep::Done]
301    /// will contain index ranges that are adjacent, non-overlapping,
302    /// covering the whole haystack, and laying on utf8 boundaries.
303    ///
304    /// A [`Match`][SearchStep::Match] result needs to contain the whole matched
305    /// pattern, however [`Reject`][SearchStep::Reject] results may be split up
306    /// into arbitrary many adjacent fragments. Both ranges may have zero length.
307    ///
308    /// As an example, the pattern `"aaa"` and the haystack `"cbaaaaab"`
309    /// might produce the stream
310    /// `[Reject(7, 8), Match(4, 7), Reject(1, 4), Reject(0, 1)]`.
311    fn next_back(&mut self) -> SearchStep;
312
313    /// Finds the next [`Match`][SearchStep::Match] result.
314    /// See [`next_back()`][ReverseSearcher::next_back].
315    #[inline]
316    fn next_match_back(&mut self) -> Option<(usize, usize)> {
317        loop {
318            match self.next_back() {
319                SearchStep::Match(a, b) => return Some((a, b)),
320                SearchStep::Done => return None,
321                _ => continue,
322            }
323        }
324    }
325
326    /// Finds the next [`Reject`][SearchStep::Reject] result.
327    /// See [`next_back()`][ReverseSearcher::next_back].
328    #[inline]
329    fn next_reject_back(&mut self) -> Option<(usize, usize)> {
330        loop {
331            match self.next_back() {
332                SearchStep::Reject(a, b) => return Some((a, b)),
333                SearchStep::Done => return None,
334                _ => continue,
335            }
336        }
337    }
338}
339
340/// A marker trait to express that a [`ReverseSearcher`]
341/// can be used for a [`DoubleEndedIterator`] implementation.
342///
343/// For this, the impl of [`Searcher`] and [`ReverseSearcher`] need
344/// to follow these conditions:
345///
346/// - All results of `next()` need to be identical
347///   to the results of `next_back()` in reverse order.
348/// - `next()` and `next_back()` need to behave as
349///   the two ends of a range of values, that is they
350///   can not "walk past each other".
351///
352/// # Examples
353///
354/// `char::Searcher` is a `DoubleEndedSearcher` because searching for a
355/// [`char`] only requires looking at one at a time, which behaves the same
356/// from both ends.
357///
358/// `(&str)::Searcher` is not a `DoubleEndedSearcher` because
359/// the pattern `"aa"` in the haystack `"aaa"` matches as either
360/// `"[aa]a"` or `"a[aa]"`, depending on which side it is searched.
361pub trait DoubleEndedSearcher<'a>: ReverseSearcher<'a> {}
362
363/////////////////////////////////////////////////////////////////////////////
364// Impl for char
365/////////////////////////////////////////////////////////////////////////////
366
367/// Associated type for `<char as Pattern>::Searcher<'a>`.
368#[derive(Clone, Debug)]
369pub struct CharSearcher<'a> {
370    haystack: &'a str,
371    // safety invariant: `finger`/`finger_back` must be a valid utf8 byte index of `haystack`
372    // This invariant can be broken *within* next_match and next_match_back, however
373    // they must exit with fingers on valid code point boundaries.
374    /// `finger` is the current byte index of the forward search.
375    /// Imagine that it exists before the byte at its index, i.e.
376    /// `haystack[finger]` is the first byte of the slice we must inspect during
377    /// forward searching
378    finger: usize,
379    /// `finger_back` is the current byte index of the reverse search.
380    /// Imagine that it exists after the byte at its index, i.e.
381    /// haystack[finger_back - 1] is the last byte of the slice we must inspect during
382    /// forward searching (and thus the first byte to be inspected when calling next_back()).
383    finger_back: usize,
384    /// The character being searched for
385    needle: char,
386
387    // safety invariant: `utf8_size` must be less than 5
388    /// The number of bytes `needle` takes up when encoded in utf8.
389    utf8_size: u8,
390    /// A utf8 encoded copy of the `needle`
391    utf8_encoded: [u8; 4],
392}
393
394impl CharSearcher<'_> {
395    fn utf8_size(&self) -> usize {
396        self.utf8_size.into()
397    }
398}
399
400unsafe impl<'a> Searcher<'a> for CharSearcher<'a> {
401    #[inline]
402    fn haystack(&self) -> &'a str {
403        self.haystack
404    }
405    #[inline]
406    fn next(&mut self) -> SearchStep {
407        let old_finger = self.finger;
408        // SAFETY: 1-4 guarantee safety of `get_unchecked`
409        // 1. `self.finger` and `self.finger_back` are kept on unicode boundaries
410        //    (this is invariant)
411        // 2. `self.finger >= 0` since it starts at 0 and only increases
412        // 3. `self.finger < self.finger_back` because otherwise the char `iter`
413        //    would return `SearchStep::Done`
414        // 4. `self.finger` comes before the end of the haystack because `self.finger_back`
415        //    starts at the end and only decreases
416        let slice = unsafe { self.haystack.get_unchecked(old_finger..self.finger_back) };
417        let mut iter = slice.chars();
418        let old_len = iter.iter.len();
419        if let Some(ch) = iter.next() {
420            // add byte offset of current character
421            // without re-encoding as utf-8
422            self.finger += old_len - iter.iter.len();
423            if ch == self.needle {
424                SearchStep::Match(old_finger, self.finger)
425            } else {
426                SearchStep::Reject(old_finger, self.finger)
427            }
428        } else {
429            SearchStep::Done
430        }
431    }
432    #[inline(always)]
433    fn next_match(&mut self) -> Option<(usize, usize)> {
434        if self.utf8_size == 1 {
435            return match self
436                .haystack
437                .as_bytes()
438                .get(self.finger..self.finger_back)?
439                .iter()
440                .position(|x| *x == self.utf8_encoded[0])
441            {
442                Some(x) => {
443                    self.finger += x + 1;
444                    Some((self.finger - 1, self.finger))
445                }
446                None => None,
447            };
448        }
449        loop {
450            // get the haystack after the last character found
451            let bytes = self.haystack.as_bytes().get(self.finger..self.finger_back)?;
452            // the last byte of the utf8 encoded needle
453            // SAFETY: we have an invariant that `utf8_size < 5`
454            let last_byte = unsafe { *self.utf8_encoded.get_unchecked(self.utf8_size() - 1) };
455            if let Some(index) = memchr::memchr(last_byte, bytes) {
456                // The new finger is the index of the byte we found,
457                // plus one, since we memchr'd for the last byte of the character.
458                //
459                // Note that this doesn't always give us a finger on a UTF8 boundary.
460                // If we *didn't* find our character
461                // we may have indexed to the non-last byte of a 3-byte or 4-byte character.
462                // We can't just skip to the next valid starting byte because a character like
463                // ꁁ (U+A041 YI SYLLABLE PA), utf-8 `EA 81 81` will have us always find
464                // the second byte when searching for the third.
465                //
466                // However, this is totally okay. While we have the invariant that
467                // self.finger is on a UTF8 boundary, this invariant is not relied upon
468                // within this method (it is relied upon in CharSearcher::next()).
469                //
470                // We only exit this method when we reach the end of the string, or if we
471                // find something. When we find something the `finger` will be set
472                // to a UTF8 boundary.
473                self.finger += index + 1;
474                if self.finger >= self.utf8_size() {
475                    let found_char = self.finger - self.utf8_size();
476                    if let Some(slice) = self.haystack.as_bytes().get(found_char..self.finger) {
477                        if slice == &self.utf8_encoded[0..self.utf8_size()] {
478                            return Some((found_char, self.finger));
479                        }
480                    }
481                }
482            } else {
483                // found nothing, exit
484                self.finger = self.finger_back;
485                return None;
486            }
487        }
488    }
489
490    // let next_reject use the default implementation from the Searcher trait
491}
492
493unsafe impl<'a> ReverseSearcher<'a> for CharSearcher<'a> {
494    #[inline]
495    fn next_back(&mut self) -> SearchStep {
496        let old_finger = self.finger_back;
497        // SAFETY: see the comment for next() above
498        let slice = unsafe { self.haystack.get_unchecked(self.finger..old_finger) };
499        let mut iter = slice.chars();
500        let old_len = iter.iter.len();
501        if let Some(ch) = iter.next_back() {
502            // subtract byte offset of current character
503            // without re-encoding as utf-8
504            self.finger_back -= old_len - iter.iter.len();
505            if ch == self.needle {
506                SearchStep::Match(self.finger_back, old_finger)
507            } else {
508                SearchStep::Reject(self.finger_back, old_finger)
509            }
510        } else {
511            SearchStep::Done
512        }
513    }
514    #[inline]
515    fn next_match_back(&mut self) -> Option<(usize, usize)> {
516        if self.utf8_size == 1 {
517            return match self
518                .haystack
519                .get(self.finger..self.finger_back)?
520                .as_bytes()
521                .iter()
522                .rposition(|&x| x == self.utf8_encoded[0])
523            {
524                Some(x) => {
525                    self.finger_back = self.finger + x;
526                    Some((self.finger_back, self.finger_back + 1))
527                }
528                None => None,
529            };
530        }
531        let haystack = self.haystack.as_bytes();
532        loop {
533            // get the haystack up to but not including the last character searched
534            let bytes = haystack.get(self.finger..self.finger_back)?;
535            // the last byte of the utf8 encoded needle
536            // SAFETY: we have an invariant that `utf8_size < 5`
537            let last_byte = unsafe { *self.utf8_encoded.get_unchecked(self.utf8_size() - 1) };
538            if let Some(index) = memchr::memrchr(last_byte, bytes) {
539                // we searched a slice that was offset by self.finger,
540                // add self.finger to recoup the original index
541                let index = self.finger + index;
542                // memrchr will return the index of the byte we wish to
543                // find. In case of an ASCII character, this is indeed
544                // were we wish our new finger to be ("after" the found
545                // char in the paradigm of reverse iteration). For
546                // multibyte chars we need to skip down by the number of more
547                // bytes they have than ASCII
548                let shift = self.utf8_size() - 1;
549                if index >= shift {
550                    let found_char = index - shift;
551                    if let Some(slice) = haystack.get(found_char..(found_char + self.utf8_size())) {
552                        if slice == &self.utf8_encoded[0..self.utf8_size()] {
553                            // move finger to before the character found (i.e., at its start index)
554                            self.finger_back = found_char;
555                            return Some((self.finger_back, self.finger_back + self.utf8_size()));
556                        }
557                    }
558                }
559                // We can't use finger_back = index - size + 1 here. If we found the last char
560                // of a different-sized character (or the middle byte of a different character)
561                // we need to bump the finger_back down to `index`. This similarly makes
562                // `finger_back` have the potential to no longer be on a boundary,
563                // but this is OK since we only exit this function on a boundary
564                // or when the haystack has been searched completely.
565                //
566                // Unlike next_match this does not
567                // have the problem of repeated bytes in utf-8 because
568                // we're searching for the last byte, and we can only have
569                // found the last byte when searching in reverse.
570                self.finger_back = index;
571            } else {
572                self.finger_back = self.finger;
573                // found nothing, exit
574                return None;
575            }
576        }
577    }
578
579    // let next_reject_back use the default implementation from the Searcher trait
580}
581
582impl<'a> DoubleEndedSearcher<'a> for CharSearcher<'a> {}
583
584/// Searches for chars that are equal to a given [`char`].
585///
586/// # Examples
587///
588/// ```
589/// assert_eq!("Hello world".find('o'), Some(4));
590/// ```
591impl Pattern for char {
592    type Searcher<'a> = CharSearcher<'a>;
593
594    #[inline]
595    fn into_searcher<'a>(self, haystack: &'a str) -> Self::Searcher<'a> {
596        let mut utf8_encoded = [0; MAX_LEN_UTF8];
597        let utf8_size = self
598            .encode_utf8(&mut utf8_encoded)
599            .len()
600            .try_into()
601            .expect("char len should be less than 255");
602
603        CharSearcher {
604            haystack,
605            finger: 0,
606            finger_back: haystack.len(),
607            needle: self,
608            utf8_size,
609            utf8_encoded,
610        }
611    }
612
613    #[inline]
614    fn is_contained_in(self, haystack: &str) -> bool {
615        if (self as u32) < 128 {
616            haystack.as_bytes().contains(&(self as u8))
617        } else {
618            let mut buffer = [0u8; 4];
619            self.encode_utf8(&mut buffer).is_contained_in(haystack)
620        }
621    }
622
623    #[inline]
624    fn is_prefix_of(self, haystack: &str) -> bool {
625        self.encode_utf8(&mut [0u8; 4]).is_prefix_of(haystack)
626    }
627
628    #[inline]
629    fn strip_prefix_of(self, haystack: &str) -> Option<&str> {
630        self.encode_utf8(&mut [0u8; 4]).strip_prefix_of(haystack)
631    }
632
633    #[inline]
634    fn is_suffix_of<'a>(self, haystack: &'a str) -> bool
635    where
636        Self::Searcher<'a>: ReverseSearcher<'a>,
637    {
638        self.encode_utf8(&mut [0u8; 4]).is_suffix_of(haystack)
639    }
640
641    #[inline]
642    fn strip_suffix_of<'a>(self, haystack: &'a str) -> Option<&'a str>
643    where
644        Self::Searcher<'a>: ReverseSearcher<'a>,
645    {
646        self.encode_utf8(&mut [0u8; 4]).strip_suffix_of(haystack)
647    }
648
649    #[inline]
650    fn as_utf8_pattern(&self) -> Option<Utf8Pattern<'_>> {
651        Some(Utf8Pattern::CharPattern(*self))
652    }
653}
654
655/////////////////////////////////////////////////////////////////////////////
656// Impl for a MultiCharEq wrapper
657/////////////////////////////////////////////////////////////////////////////
658
659#[doc(hidden)]
660trait MultiCharEq {
661    fn matches(&mut self, c: char) -> bool;
662}
663
664impl<F> MultiCharEq for F
665where
666    F: FnMut(char) -> bool,
667{
668    #[inline]
669    fn matches(&mut self, c: char) -> bool {
670        (*self)(c)
671    }
672}
673
674impl<const N: usize> MultiCharEq for [char; N] {
675    #[inline]
676    fn matches(&mut self, c: char) -> bool {
677        self.contains(&c)
678    }
679}
680
681impl<const N: usize> MultiCharEq for &[char; N] {
682    #[inline]
683    fn matches(&mut self, c: char) -> bool {
684        self.contains(&c)
685    }
686}
687
688impl MultiCharEq for &[char] {
689    #[inline]
690    fn matches(&mut self, c: char) -> bool {
691        self.contains(&c)
692    }
693}
694
695struct MultiCharEqPattern<C: MultiCharEq>(C);
696
697#[derive(Clone, Debug)]
698struct MultiCharEqSearcher<'a, C: MultiCharEq> {
699    char_eq: C,
700    haystack: &'a str,
701    char_indices: super::CharIndices<'a>,
702}
703
704impl<C: MultiCharEq> Pattern for MultiCharEqPattern<C> {
705    type Searcher<'a> = MultiCharEqSearcher<'a, C>;
706
707    #[inline]
708    fn into_searcher(self, haystack: &str) -> MultiCharEqSearcher<'_, C> {
709        MultiCharEqSearcher { haystack, char_eq: self.0, char_indices: haystack.char_indices() }
710    }
711}
712
713unsafe impl<'a, C: MultiCharEq> Searcher<'a> for MultiCharEqSearcher<'a, C> {
714    #[inline]
715    fn haystack(&self) -> &'a str {
716        self.haystack
717    }
718
719    #[inline]
720    fn next(&mut self) -> SearchStep {
721        let s = &mut self.char_indices;
722        // Compare lengths of the internal byte slice iterator
723        // to find length of current char
724        let pre_len = s.iter.iter.len();
725        if let Some((i, c)) = s.next() {
726            let len = s.iter.iter.len();
727            let char_len = pre_len - len;
728            if self.char_eq.matches(c) {
729                return SearchStep::Match(i, i + char_len);
730            } else {
731                return SearchStep::Reject(i, i + char_len);
732            }
733        }
734        SearchStep::Done
735    }
736}
737
738unsafe impl<'a, C: MultiCharEq> ReverseSearcher<'a> for MultiCharEqSearcher<'a, C> {
739    #[inline]
740    fn next_back(&mut self) -> SearchStep {
741        let s = &mut self.char_indices;
742        // Compare lengths of the internal byte slice iterator
743        // to find length of current char
744        let pre_len = s.iter.iter.len();
745        if let Some((i, c)) = s.next_back() {
746            let len = s.iter.iter.len();
747            let char_len = pre_len - len;
748            if self.char_eq.matches(c) {
749                return SearchStep::Match(i, i + char_len);
750            } else {
751                return SearchStep::Reject(i, i + char_len);
752            }
753        }
754        SearchStep::Done
755    }
756}
757
758impl<'a, C: MultiCharEq> DoubleEndedSearcher<'a> for MultiCharEqSearcher<'a, C> {}
759
760/////////////////////////////////////////////////////////////////////////////
761
762macro_rules! pattern_methods {
763    ($a:lifetime, $t:ty, $pmap:expr, $smap:expr) => {
764        type Searcher<$a> = $t;
765
766        #[inline]
767        fn into_searcher<$a>(self, haystack: &$a str) -> $t {
768            ($smap)(($pmap)(self).into_searcher(haystack))
769        }
770
771        #[inline]
772        fn is_contained_in<$a>(self, haystack: &$a str) -> bool {
773            ($pmap)(self).is_contained_in(haystack)
774        }
775
776        #[inline]
777        fn is_prefix_of<$a>(self, haystack: &$a str) -> bool {
778            ($pmap)(self).is_prefix_of(haystack)
779        }
780
781        #[inline]
782        fn strip_prefix_of<$a>(self, haystack: &$a str) -> Option<&$a str> {
783            ($pmap)(self).strip_prefix_of(haystack)
784        }
785
786        #[inline]
787        fn is_suffix_of<$a>(self, haystack: &$a str) -> bool
788        where
789            $t: ReverseSearcher<$a>,
790        {
791            ($pmap)(self).is_suffix_of(haystack)
792        }
793
794        #[inline]
795        fn strip_suffix_of<$a>(self, haystack: &$a str) -> Option<&$a str>
796        where
797            $t: ReverseSearcher<$a>,
798        {
799            ($pmap)(self).strip_suffix_of(haystack)
800        }
801    };
802}
803
804macro_rules! searcher_methods {
805    (forward) => {
806        #[inline]
807        fn haystack(&self) -> &'a str {
808            self.0.haystack()
809        }
810        #[inline]
811        fn next(&mut self) -> SearchStep {
812            self.0.next()
813        }
814        #[inline]
815        fn next_match(&mut self) -> Option<(usize, usize)> {
816            self.0.next_match()
817        }
818        #[inline]
819        fn next_reject(&mut self) -> Option<(usize, usize)> {
820            self.0.next_reject()
821        }
822    };
823    (reverse) => {
824        #[inline]
825        fn next_back(&mut self) -> SearchStep {
826            self.0.next_back()
827        }
828        #[inline]
829        fn next_match_back(&mut self) -> Option<(usize, usize)> {
830            self.0.next_match_back()
831        }
832        #[inline]
833        fn next_reject_back(&mut self) -> Option<(usize, usize)> {
834            self.0.next_reject_back()
835        }
836    };
837}
838
839/// Associated type for `<[char; N] as Pattern>::Searcher<'a>`.
840#[derive(Clone, Debug)]
841pub struct CharArraySearcher<'a, const N: usize>(
842    <MultiCharEqPattern<[char; N]> as Pattern>::Searcher<'a>,
843);
844
845/// Associated type for `<&[char; N] as Pattern>::Searcher<'a>`.
846#[derive(Clone, Debug)]
847pub struct CharArrayRefSearcher<'a, 'b, const N: usize>(
848    <MultiCharEqPattern<&'b [char; N]> as Pattern>::Searcher<'a>,
849);
850
851/// Searches for chars that are equal to any of the [`char`]s in the array.
852///
853/// # Examples
854///
855/// ```
856/// assert_eq!("Hello world".find(['o', 'l']), Some(2));
857/// assert_eq!("Hello world".find(['h', 'w']), Some(6));
858/// ```
859impl<const N: usize> Pattern for [char; N] {
860    pattern_methods!('a, CharArraySearcher<'a, N>, MultiCharEqPattern, CharArraySearcher);
861}
862
863unsafe impl<'a, const N: usize> Searcher<'a> for CharArraySearcher<'a, N> {
864    searcher_methods!(forward);
865}
866
867unsafe impl<'a, const N: usize> ReverseSearcher<'a> for CharArraySearcher<'a, N> {
868    searcher_methods!(reverse);
869}
870
871impl<'a, const N: usize> DoubleEndedSearcher<'a> for CharArraySearcher<'a, N> {}
872
873/// Searches for chars that are equal to any of the [`char`]s in the array.
874///
875/// # Examples
876///
877/// ```
878/// assert_eq!("Hello world".find(&['o', 'l']), Some(2));
879/// assert_eq!("Hello world".find(&['h', 'w']), Some(6));
880/// ```
881impl<'b, const N: usize> Pattern for &'b [char; N] {
882    pattern_methods!('a, CharArrayRefSearcher<'a, 'b, N>, MultiCharEqPattern, CharArrayRefSearcher);
883}
884
885unsafe impl<'a, 'b, const N: usize> Searcher<'a> for CharArrayRefSearcher<'a, 'b, N> {
886    searcher_methods!(forward);
887}
888
889unsafe impl<'a, 'b, const N: usize> ReverseSearcher<'a> for CharArrayRefSearcher<'a, 'b, N> {
890    searcher_methods!(reverse);
891}
892
893impl<'a, 'b, const N: usize> DoubleEndedSearcher<'a> for CharArrayRefSearcher<'a, 'b, N> {}
894
895/////////////////////////////////////////////////////////////////////////////
896// Impl for &[char]
897/////////////////////////////////////////////////////////////////////////////
898
899// Todo: Change / Remove due to ambiguity in meaning.
900
901/// Associated type for `<&[char] as Pattern>::Searcher<'a>`.
902#[derive(Clone, Debug)]
903pub struct CharSliceSearcher<'a, 'b>(<MultiCharEqPattern<&'b [char]> as Pattern>::Searcher<'a>);
904
905unsafe impl<'a, 'b> Searcher<'a> for CharSliceSearcher<'a, 'b> {
906    searcher_methods!(forward);
907}
908
909unsafe impl<'a, 'b> ReverseSearcher<'a> for CharSliceSearcher<'a, 'b> {
910    searcher_methods!(reverse);
911}
912
913impl<'a, 'b> DoubleEndedSearcher<'a> for CharSliceSearcher<'a, 'b> {}
914
915/// Searches for chars that are equal to any of the [`char`]s in the slice.
916///
917/// # Examples
918///
919/// ```
920/// assert_eq!("Hello world".find(&['o', 'l'][..]), Some(2));
921/// assert_eq!("Hello world".find(&['h', 'w'][..]), Some(6));
922/// ```
923impl<'b> Pattern for &'b [char] {
924    pattern_methods!('a, CharSliceSearcher<'a, 'b>, MultiCharEqPattern, CharSliceSearcher);
925}
926
927/////////////////////////////////////////////////////////////////////////////
928// Impl for F: FnMut(char) -> bool
929/////////////////////////////////////////////////////////////////////////////
930
931/// Associated type for `<F as Pattern>::Searcher<'a>`.
932#[derive(Clone)]
933pub struct CharPredicateSearcher<'a, F>(<MultiCharEqPattern<F> as Pattern>::Searcher<'a>)
934where
935    F: FnMut(char) -> bool;
936
937impl<F> fmt::Debug for CharPredicateSearcher<'_, F>
938where
939    F: FnMut(char) -> bool,
940{
941    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
942        f.debug_struct("CharPredicateSearcher")
943            .field("haystack", &self.0.haystack)
944            .field("char_indices", &self.0.char_indices)
945            .finish()
946    }
947}
948unsafe impl<'a, F> Searcher<'a> for CharPredicateSearcher<'a, F>
949where
950    F: FnMut(char) -> bool,
951{
952    searcher_methods!(forward);
953}
954
955unsafe impl<'a, F> ReverseSearcher<'a> for CharPredicateSearcher<'a, F>
956where
957    F: FnMut(char) -> bool,
958{
959    searcher_methods!(reverse);
960}
961
962impl<'a, F> DoubleEndedSearcher<'a> for CharPredicateSearcher<'a, F> where F: FnMut(char) -> bool {}
963
964/// Searches for [`char`]s that match the given predicate.
965///
966/// # Examples
967///
968/// ```
969/// assert_eq!("Hello world".find(char::is_uppercase), Some(0));
970/// assert_eq!("Hello world".find(|c| "aeiou".contains(c)), Some(1));
971/// ```
972impl<F> Pattern for F
973where
974    F: FnMut(char) -> bool,
975{
976    pattern_methods!('a, CharPredicateSearcher<'a, F>, MultiCharEqPattern, CharPredicateSearcher);
977}
978
979/////////////////////////////////////////////////////////////////////////////
980// Impl for &&str
981/////////////////////////////////////////////////////////////////////////////
982
983/// Delegates to the `&str` impl.
984impl<'b, 'c> Pattern for &'c &'b str {
985    pattern_methods!('a, StrSearcher<'a, 'b>, |&s| s, |s| s);
986}
987
988/////////////////////////////////////////////////////////////////////////////
989// Impl for &str
990/////////////////////////////////////////////////////////////////////////////
991
992/// Non-allocating substring search.
993///
994/// Will handle the pattern `""` as returning empty matches at each character
995/// boundary.
996///
997/// # Examples
998///
999/// ```
1000/// assert_eq!("Hello world".find("world"), Some(6));
1001/// ```
1002impl<'b> Pattern for &'b str {
1003    type Searcher<'a> = StrSearcher<'a, 'b>;
1004
1005    #[inline]
1006    fn into_searcher(self, haystack: &str) -> StrSearcher<'_, 'b> {
1007        StrSearcher::new(haystack, self)
1008    }
1009
1010    /// Checks whether the pattern matches at the front of the haystack.
1011    #[inline]
1012    fn is_prefix_of(self, haystack: &str) -> bool {
1013        haystack.as_bytes().starts_with(self.as_bytes())
1014    }
1015
1016    /// Checks whether the pattern matches anywhere in the haystack
1017    #[inline]
1018    fn is_contained_in(self, haystack: &str) -> bool {
1019        if self.len() == 0 {
1020            return true;
1021        }
1022
1023        match self.len().cmp(&haystack.len()) {
1024            Ordering::Less => {
1025                if self.len() == 1 {
1026                    return haystack.as_bytes().contains(&self.as_bytes()[0]);
1027                }
1028
1029                #[cfg(all(target_arch = "x86_64", target_feature = "sse2"))]
1030                if self.len() <= 32 {
1031                    if let Some(result) = simd_contains(self, haystack) {
1032                        return result;
1033                    }
1034                }
1035
1036                self.into_searcher(haystack).next_match().is_some()
1037            }
1038            _ => self == haystack,
1039        }
1040    }
1041
1042    /// Removes the pattern from the front of haystack, if it matches.
1043    #[inline]
1044    fn strip_prefix_of(self, haystack: &str) -> Option<&str> {
1045        if self.is_prefix_of(haystack) {
1046            // SAFETY: prefix was just verified to exist.
1047            unsafe { Some(haystack.get_unchecked(self.as_bytes().len()..)) }
1048        } else {
1049            None
1050        }
1051    }
1052
1053    /// Checks whether the pattern matches at the back of the haystack.
1054    #[inline]
1055    fn is_suffix_of<'a>(self, haystack: &'a str) -> bool
1056    where
1057        Self::Searcher<'a>: ReverseSearcher<'a>,
1058    {
1059        haystack.as_bytes().ends_with(self.as_bytes())
1060    }
1061
1062    /// Removes the pattern from the back of haystack, if it matches.
1063    #[inline]
1064    fn strip_suffix_of<'a>(self, haystack: &'a str) -> Option<&'a str>
1065    where
1066        Self::Searcher<'a>: ReverseSearcher<'a>,
1067    {
1068        if self.is_suffix_of(haystack) {
1069            let i = haystack.len() - self.as_bytes().len();
1070            // SAFETY: suffix was just verified to exist.
1071            unsafe { Some(haystack.get_unchecked(..i)) }
1072        } else {
1073            None
1074        }
1075    }
1076
1077    #[inline]
1078    fn as_utf8_pattern(&self) -> Option<Utf8Pattern<'_>> {
1079        Some(Utf8Pattern::StringPattern(self.as_bytes()))
1080    }
1081}
1082
1083/////////////////////////////////////////////////////////////////////////////
1084// Two Way substring searcher
1085/////////////////////////////////////////////////////////////////////////////
1086
1087#[derive(Clone, Debug)]
1088/// Associated type for `<&str as Pattern>::Searcher<'a>`.
1089pub struct StrSearcher<'a, 'b> {
1090    haystack: &'a str,
1091    needle: &'b str,
1092
1093    searcher: StrSearcherImpl,
1094}
1095
1096#[derive(Clone, Debug)]
1097enum StrSearcherImpl {
1098    Empty(EmptyNeedle),
1099    TwoWay(TwoWaySearcher),
1100}
1101
1102#[derive(Clone, Debug)]
1103struct EmptyNeedle {
1104    position: usize,
1105    end: usize,
1106    is_match_fw: bool,
1107    is_match_bw: bool,
1108    // Needed in case of an empty haystack, see #85462
1109    is_finished: bool,
1110}
1111
1112impl<'a, 'b> StrSearcher<'a, 'b> {
1113    fn new(haystack: &'a str, needle: &'b str) -> StrSearcher<'a, 'b> {
1114        if needle.is_empty() {
1115            StrSearcher {
1116                haystack,
1117                needle,
1118                searcher: StrSearcherImpl::Empty(EmptyNeedle {
1119                    position: 0,
1120                    end: haystack.len(),
1121                    is_match_fw: true,
1122                    is_match_bw: true,
1123                    is_finished: false,
1124                }),
1125            }
1126        } else {
1127            StrSearcher {
1128                haystack,
1129                needle,
1130                searcher: StrSearcherImpl::TwoWay(TwoWaySearcher::new(
1131                    needle.as_bytes(),
1132                    haystack.len(),
1133                )),
1134            }
1135        }
1136    }
1137}
1138
1139unsafe impl<'a, 'b> Searcher<'a> for StrSearcher<'a, 'b> {
1140    #[inline]
1141    fn haystack(&self) -> &'a str {
1142        self.haystack
1143    }
1144
1145    #[inline]
1146    fn next(&mut self) -> SearchStep {
1147        match self.searcher {
1148            StrSearcherImpl::Empty(ref mut searcher) => {
1149                if searcher.is_finished {
1150                    return SearchStep::Done;
1151                }
1152                // empty needle rejects every char and matches every empty string between them
1153                let is_match = searcher.is_match_fw;
1154                searcher.is_match_fw = !searcher.is_match_fw;
1155                let pos = searcher.position;
1156                match self.haystack[pos..].chars().next() {
1157                    _ if is_match => SearchStep::Match(pos, pos),
1158                    None => {
1159                        searcher.is_finished = true;
1160                        SearchStep::Done
1161                    }
1162                    Some(ch) => {
1163                        searcher.position += ch.len_utf8();
1164                        SearchStep::Reject(pos, searcher.position)
1165                    }
1166                }
1167            }
1168            StrSearcherImpl::TwoWay(ref mut searcher) => {
1169                // TwoWaySearcher produces valid *Match* indices that split at char boundaries
1170                // as long as it does correct matching and that haystack and needle are
1171                // valid UTF-8
1172                // *Rejects* from the algorithm can fall on any indices, but we will walk them
1173                // manually to the next character boundary, so that they are utf-8 safe.
1174                if searcher.position == self.haystack.len() {
1175                    return SearchStep::Done;
1176                }
1177                let is_long = searcher.memory == usize::MAX;
1178                match searcher.next::<RejectAndMatch>(
1179                    self.haystack.as_bytes(),
1180                    self.needle.as_bytes(),
1181                    is_long,
1182                ) {
1183                    SearchStep::Reject(a, mut b) => {
1184                        // skip to next char boundary
1185                        while !self.haystack.is_char_boundary(b) {
1186                            b += 1;
1187                        }
1188                        searcher.position = cmp::max(b, searcher.position);
1189                        SearchStep::Reject(a, b)
1190                    }
1191                    otherwise => otherwise,
1192                }
1193            }
1194        }
1195    }
1196
1197    #[inline]
1198    fn next_match(&mut self) -> Option<(usize, usize)> {
1199        match self.searcher {
1200            StrSearcherImpl::Empty(..) => loop {
1201                match self.next() {
1202                    SearchStep::Match(a, b) => return Some((a, b)),
1203                    SearchStep::Done => return None,
1204                    SearchStep::Reject(..) => {}
1205                }
1206            },
1207            StrSearcherImpl::TwoWay(ref mut searcher) => {
1208                let is_long = searcher.memory == usize::MAX;
1209                // write out `true` and `false` cases to encourage the compiler
1210                // to specialize the two cases separately.
1211                if is_long {
1212                    searcher.next::<MatchOnly>(
1213                        self.haystack.as_bytes(),
1214                        self.needle.as_bytes(),
1215                        true,
1216                    )
1217                } else {
1218                    searcher.next::<MatchOnly>(
1219                        self.haystack.as_bytes(),
1220                        self.needle.as_bytes(),
1221                        false,
1222                    )
1223                }
1224            }
1225        }
1226    }
1227}
1228
1229unsafe impl<'a, 'b> ReverseSearcher<'a> for StrSearcher<'a, 'b> {
1230    #[inline]
1231    fn next_back(&mut self) -> SearchStep {
1232        match self.searcher {
1233            StrSearcherImpl::Empty(ref mut searcher) => {
1234                if searcher.is_finished {
1235                    return SearchStep::Done;
1236                }
1237                let is_match = searcher.is_match_bw;
1238                searcher.is_match_bw = !searcher.is_match_bw;
1239                let end = searcher.end;
1240                match self.haystack[..end].chars().next_back() {
1241                    _ if is_match => SearchStep::Match(end, end),
1242                    None => {
1243                        searcher.is_finished = true;
1244                        SearchStep::Done
1245                    }
1246                    Some(ch) => {
1247                        searcher.end -= ch.len_utf8();
1248                        SearchStep::Reject(searcher.end, end)
1249                    }
1250                }
1251            }
1252            StrSearcherImpl::TwoWay(ref mut searcher) => {
1253                if searcher.end == 0 {
1254                    return SearchStep::Done;
1255                }
1256                let is_long = searcher.memory == usize::MAX;
1257                match searcher.next_back::<RejectAndMatch>(
1258                    self.haystack.as_bytes(),
1259                    self.needle.as_bytes(),
1260                    is_long,
1261                ) {
1262                    SearchStep::Reject(mut a, b) => {
1263                        // skip to next char boundary
1264                        while !self.haystack.is_char_boundary(a) {
1265                            a -= 1;
1266                        }
1267                        searcher.end = cmp::min(a, searcher.end);
1268                        SearchStep::Reject(a, b)
1269                    }
1270                    otherwise => otherwise,
1271                }
1272            }
1273        }
1274    }
1275
1276    #[inline]
1277    fn next_match_back(&mut self) -> Option<(usize, usize)> {
1278        match self.searcher {
1279            StrSearcherImpl::Empty(..) => loop {
1280                match self.next_back() {
1281                    SearchStep::Match(a, b) => return Some((a, b)),
1282                    SearchStep::Done => return None,
1283                    SearchStep::Reject(..) => {}
1284                }
1285            },
1286            StrSearcherImpl::TwoWay(ref mut searcher) => {
1287                let is_long = searcher.memory == usize::MAX;
1288                // write out `true` and `false`, like `next_match`
1289                if is_long {
1290                    searcher.next_back::<MatchOnly>(
1291                        self.haystack.as_bytes(),
1292                        self.needle.as_bytes(),
1293                        true,
1294                    )
1295                } else {
1296                    searcher.next_back::<MatchOnly>(
1297                        self.haystack.as_bytes(),
1298                        self.needle.as_bytes(),
1299                        false,
1300                    )
1301                }
1302            }
1303        }
1304    }
1305}
1306
1307/// The internal state of the two-way substring search algorithm.
1308#[derive(Clone, Debug)]
1309struct TwoWaySearcher {
1310    // constants
1311    /// critical factorization index
1312    crit_pos: usize,
1313    /// critical factorization index for reversed needle
1314    crit_pos_back: usize,
1315    period: usize,
1316    /// `byteset` is an extension (not part of the two way algorithm);
1317    /// it's a 64-bit "fingerprint" where each set bit `j` corresponds
1318    /// to a (byte & 63) == j present in the needle.
1319    byteset: u64,
1320
1321    // variables
1322    position: usize,
1323    end: usize,
1324    /// index into needle before which we have already matched
1325    memory: usize,
1326    /// index into needle after which we have already matched
1327    memory_back: usize,
1328}
1329
1330/*
1331    This is the Two-Way search algorithm, which was introduced in the paper:
1332    Crochemore, M., Perrin, D., 1991, Two-way string-matching, Journal of the ACM 38(3):651-675.
1333
1334    Here's some background information.
1335
1336    A *word* is a string of symbols. The *length* of a word should be a familiar
1337    notion, and here we denote it for any word x by |x|.
1338    (We also allow for the possibility of the *empty word*, a word of length zero).
1339
1340    If x is any non-empty word, then an integer p with 0 < p <= |x| is said to be a
1341    *period* for x iff for all i with 0 <= i <= |x| - p - 1, we have x[i] == x[i+p].
1342    For example, both 1 and 2 are periods for the string "aa". As another example,
1343    the only period of the string "abcd" is 4.
1344
1345    We denote by period(x) the *smallest* period of x (provided that x is non-empty).
1346    This is always well-defined since every non-empty word x has at least one period,
1347    |x|. We sometimes call this *the period* of x.
1348
1349    If u, v and x are words such that x = uv, where uv is the concatenation of u and
1350    v, then we say that (u, v) is a *factorization* of x.
1351
1352    Let (u, v) be a factorization for a word x. Then if w is a non-empty word such
1353    that both of the following hold
1354
1355      - either w is a suffix of u or u is a suffix of w
1356      - either w is a prefix of v or v is a prefix of w
1357
1358    then w is said to be a *repetition* for the factorization (u, v).
1359
1360    Just to unpack this, there are four possibilities here. Let w = "abc". Then we
1361    might have:
1362
1363      - w is a suffix of u and w is a prefix of v. ex: ("lolabc", "abcde")
1364      - w is a suffix of u and v is a prefix of w. ex: ("lolabc", "ab")
1365      - u is a suffix of w and w is a prefix of v. ex: ("bc", "abchi")
1366      - u is a suffix of w and v is a prefix of w. ex: ("bc", "a")
1367
1368    Note that the word vu is a repetition for any factorization (u,v) of x = uv,
1369    so every factorization has at least one repetition.
1370
1371    If x is a string and (u, v) is a factorization for x, then a *local period* for
1372    (u, v) is an integer r such that there is some word w such that |w| = r and w is
1373    a repetition for (u, v).
1374
1375    We denote by local_period(u, v) the smallest local period of (u, v). We sometimes
1376    call this *the local period* of (u, v). Provided that x = uv is non-empty, this
1377    is well-defined (because each non-empty word has at least one factorization, as
1378    noted above).
1379
1380    It can be proven that the following is an equivalent definition of a local period
1381    for a factorization (u, v): any positive integer r such that x[i] == x[i+r] for
1382    all i such that |u| - r <= i <= |u| - 1 and such that both x[i] and x[i+r] are
1383    defined. (i.e., i > 0 and i + r < |x|).
1384
1385    Using the above reformulation, it is easy to prove that
1386
1387        1 <= local_period(u, v) <= period(uv)
1388
1389    A factorization (u, v) of x such that local_period(u,v) = period(x) is called a
1390    *critical factorization*.
1391
1392    The algorithm hinges on the following theorem, which is stated without proof:
1393
1394    **Critical Factorization Theorem** Any word x has at least one critical
1395    factorization (u, v) such that |u| < period(x).
1396
1397    The purpose of maximal_suffix is to find such a critical factorization.
1398
1399    If the period is short, compute another factorization x = u' v' to use
1400    for reverse search, chosen instead so that |v'| < period(x).
1401
1402*/
1403impl TwoWaySearcher {
1404    fn new(needle: &[u8], end: usize) -> TwoWaySearcher {
1405        let (crit_pos_false, period_false) = TwoWaySearcher::maximal_suffix(needle, false);
1406        let (crit_pos_true, period_true) = TwoWaySearcher::maximal_suffix(needle, true);
1407
1408        let (crit_pos, period) = if crit_pos_false > crit_pos_true {
1409            (crit_pos_false, period_false)
1410        } else {
1411            (crit_pos_true, period_true)
1412        };
1413
1414        // A particularly readable explanation of what's going on here can be found
1415        // in Crochemore and Rytter's book "Text Algorithms", ch 13. Specifically
1416        // see the code for "Algorithm CP" on p. 323.
1417        //
1418        // What's going on is we have some critical factorization (u, v) of the
1419        // needle, and we want to determine whether u is a suffix of
1420        // &v[..period]. If it is, we use "Algorithm CP1". Otherwise we use
1421        // "Algorithm CP2", which is optimized for when the period of the needle
1422        // is large.
1423        if needle[..crit_pos] == needle[period..period + crit_pos] {
1424            // short period case -- the period is exact
1425            // compute a separate critical factorization for the reversed needle
1426            // x = u' v' where |v'| < period(x).
1427            //
1428            // This is sped up by the period being known already.
1429            // Note that a case like x = "acba" may be factored exactly forwards
1430            // (crit_pos = 1, period = 3) while being factored with approximate
1431            // period in reverse (crit_pos = 2, period = 2). We use the given
1432            // reverse factorization but keep the exact period.
1433            let crit_pos_back = needle.len()
1434                - cmp::max(
1435                    TwoWaySearcher::reverse_maximal_suffix(needle, period, false),
1436                    TwoWaySearcher::reverse_maximal_suffix(needle, period, true),
1437                );
1438
1439            TwoWaySearcher {
1440                crit_pos,
1441                crit_pos_back,
1442                period,
1443                byteset: Self::byteset_create(&needle[..period]),
1444
1445                position: 0,
1446                end,
1447                memory: 0,
1448                memory_back: needle.len(),
1449            }
1450        } else {
1451            // long period case -- we have an approximation to the actual period,
1452            // and don't use memorization.
1453            //
1454            // Approximate the period by lower bound max(|u|, |v|) + 1.
1455            // The critical factorization is efficient to use for both forward and
1456            // reverse search.
1457
1458            TwoWaySearcher {
1459                crit_pos,
1460                crit_pos_back: crit_pos,
1461                period: cmp::max(crit_pos, needle.len() - crit_pos) + 1,
1462                byteset: Self::byteset_create(needle),
1463
1464                position: 0,
1465                end,
1466                memory: usize::MAX, // Dummy value to signify that the period is long
1467                memory_back: usize::MAX,
1468            }
1469        }
1470    }
1471
1472    #[inline]
1473    fn byteset_create(bytes: &[u8]) -> u64 {
1474        bytes.iter().fold(0, |a, &b| (1 << (b & 0x3f)) | a)
1475    }
1476
1477    #[inline]
1478    fn byteset_contains(&self, byte: u8) -> bool {
1479        (self.byteset >> ((byte & 0x3f) as usize)) & 1 != 0
1480    }
1481
1482    // One of the main ideas of Two-Way is that we factorize the needle into
1483    // two halves, (u, v), and begin trying to find v in the haystack by scanning
1484    // left to right. If v matches, we try to match u by scanning right to left.
1485    // How far we can jump when we encounter a mismatch is all based on the fact
1486    // that (u, v) is a critical factorization for the needle.
1487    #[inline]
1488    fn next<S>(&mut self, haystack: &[u8], needle: &[u8], long_period: bool) -> S::Output
1489    where
1490        S: TwoWayStrategy,
1491    {
1492        // `next()` uses `self.position` as its cursor
1493        let old_pos = self.position;
1494        let needle_last = needle.len() - 1;
1495        'search: loop {
1496            // Check that we have room to search in
1497            // position + needle_last can not overflow if we assume slices
1498            // are bounded by isize's range.
1499            let tail_byte = match haystack.get(self.position + needle_last) {
1500                Some(&b) => b,
1501                None => {
1502                    self.position = haystack.len();
1503                    return S::rejecting(old_pos, self.position);
1504                }
1505            };
1506
1507            if S::use_early_reject() && old_pos != self.position {
1508                return S::rejecting(old_pos, self.position);
1509            }
1510
1511            // Quickly skip by large portions unrelated to our substring
1512            if !self.byteset_contains(tail_byte) {
1513                self.position += needle.len();
1514                if !long_period {
1515                    self.memory = 0;
1516                }
1517                continue 'search;
1518            }
1519
1520            // See if the right part of the needle matches
1521            let start =
1522                if long_period { self.crit_pos } else { cmp::max(self.crit_pos, self.memory) };
1523            for i in start..needle.len() {
1524                if needle[i] != haystack[self.position + i] {
1525                    self.position += i - self.crit_pos + 1;
1526                    if !long_period {
1527                        self.memory = 0;
1528                    }
1529                    continue 'search;
1530                }
1531            }
1532
1533            // See if the left part of the needle matches
1534            let start = if long_period { 0 } else { self.memory };
1535            for i in (start..self.crit_pos).rev() {
1536                if needle[i] != haystack[self.position + i] {
1537                    self.position += self.period;
1538                    if !long_period {
1539                        self.memory = needle.len() - self.period;
1540                    }
1541                    continue 'search;
1542                }
1543            }
1544
1545            // We have found a match!
1546            let match_pos = self.position;
1547
1548            // Note: add self.period instead of needle.len() to have overlapping matches
1549            self.position += needle.len();
1550            if !long_period {
1551                self.memory = 0; // set to needle.len() - self.period for overlapping matches
1552            }
1553
1554            return S::matching(match_pos, match_pos + needle.len());
1555        }
1556    }
1557
1558    // Follows the ideas in `next()`.
1559    //
1560    // The definitions are symmetrical, with period(x) = period(reverse(x))
1561    // and local_period(u, v) = local_period(reverse(v), reverse(u)), so if (u, v)
1562    // is a critical factorization, so is (reverse(v), reverse(u)).
1563    //
1564    // For the reverse case we have computed a critical factorization x = u' v'
1565    // (field `crit_pos_back`). We need |u| < period(x) for the forward case and
1566    // thus |v'| < period(x) for the reverse.
1567    //
1568    // To search in reverse through the haystack, we search forward through
1569    // a reversed haystack with a reversed needle, matching first u' and then v'.
1570    #[inline]
1571    fn next_back<S>(&mut self, haystack: &[u8], needle: &[u8], long_period: bool) -> S::Output
1572    where
1573        S: TwoWayStrategy,
1574    {
1575        // `next_back()` uses `self.end` as its cursor -- so that `next()` and `next_back()`
1576        // are independent.
1577        let old_end = self.end;
1578        'search: loop {
1579            // Check that we have room to search in
1580            // end - needle.len() will wrap around when there is no more room,
1581            // but due to slice length limits it can never wrap all the way back
1582            // into the length of haystack.
1583            let front_byte = match haystack.get(self.end.wrapping_sub(needle.len())) {
1584                Some(&b) => b,
1585                None => {
1586                    self.end = 0;
1587                    return S::rejecting(0, old_end);
1588                }
1589            };
1590
1591            if S::use_early_reject() && old_end != self.end {
1592                return S::rejecting(self.end, old_end);
1593            }
1594
1595            // Quickly skip by large portions unrelated to our substring
1596            if !self.byteset_contains(front_byte) {
1597                self.end -= needle.len();
1598                if !long_period {
1599                    self.memory_back = needle.len();
1600                }
1601                continue 'search;
1602            }
1603
1604            // See if the left part of the needle matches
1605            let crit = if long_period {
1606                self.crit_pos_back
1607            } else {
1608                cmp::min(self.crit_pos_back, self.memory_back)
1609            };
1610            for i in (0..crit).rev() {
1611                if needle[i] != haystack[self.end - needle.len() + i] {
1612                    self.end -= self.crit_pos_back - i;
1613                    if !long_period {
1614                        self.memory_back = needle.len();
1615                    }
1616                    continue 'search;
1617                }
1618            }
1619
1620            // See if the right part of the needle matches
1621            let needle_end = if long_period { needle.len() } else { self.memory_back };
1622            for i in self.crit_pos_back..needle_end {
1623                if needle[i] != haystack[self.end - needle.len() + i] {
1624                    self.end -= self.period;
1625                    if !long_period {
1626                        self.memory_back = self.period;
1627                    }
1628                    continue 'search;
1629                }
1630            }
1631
1632            // We have found a match!
1633            let match_pos = self.end - needle.len();
1634            // Note: sub self.period instead of needle.len() to have overlapping matches
1635            self.end -= needle.len();
1636            if !long_period {
1637                self.memory_back = needle.len();
1638            }
1639
1640            return S::matching(match_pos, match_pos + needle.len());
1641        }
1642    }
1643
1644    // Compute the maximal suffix of `arr`.
1645    //
1646    // The maximal suffix is a possible critical factorization (u, v) of `arr`.
1647    //
1648    // Returns (`i`, `p`) where `i` is the starting index of v and `p` is the
1649    // period of v.
1650    //
1651    // `order_greater` determines if lexical order is `<` or `>`. Both
1652    // orders must be computed -- the ordering with the largest `i` gives
1653    // a critical factorization.
1654    //
1655    // For long period cases, the resulting period is not exact (it is too short).
1656    #[inline]
1657    fn maximal_suffix(arr: &[u8], order_greater: bool) -> (usize, usize) {
1658        let mut left = 0; // Corresponds to i in the paper
1659        let mut right = 1; // Corresponds to j in the paper
1660        let mut offset = 0; // Corresponds to k in the paper, but starting at 0
1661        // to match 0-based indexing.
1662        let mut period = 1; // Corresponds to p in the paper
1663
1664        while let Some(&a) = arr.get(right + offset) {
1665            // `left` will be inbounds when `right` is.
1666            let b = arr[left + offset];
1667            if (a < b && !order_greater) || (a > b && order_greater) {
1668                // Suffix is smaller, period is entire prefix so far.
1669                right += offset + 1;
1670                offset = 0;
1671                period = right - left;
1672            } else if a == b {
1673                // Advance through repetition of the current period.
1674                if offset + 1 == period {
1675                    right += offset + 1;
1676                    offset = 0;
1677                } else {
1678                    offset += 1;
1679                }
1680            } else {
1681                // Suffix is larger, start over from current location.
1682                left = right;
1683                right += 1;
1684                offset = 0;
1685                period = 1;
1686            }
1687        }
1688        (left, period)
1689    }
1690
1691    // Compute the maximal suffix of the reverse of `arr`.
1692    //
1693    // The maximal suffix is a possible critical factorization (u', v') of `arr`.
1694    //
1695    // Returns `i` where `i` is the starting index of v', from the back;
1696    // returns immediately when a period of `known_period` is reached.
1697    //
1698    // `order_greater` determines if lexical order is `<` or `>`. Both
1699    // orders must be computed -- the ordering with the largest `i` gives
1700    // a critical factorization.
1701    //
1702    // For long period cases, the resulting period is not exact (it is too short).
1703    fn reverse_maximal_suffix(arr: &[u8], known_period: usize, order_greater: bool) -> usize {
1704        let mut left = 0; // Corresponds to i in the paper
1705        let mut right = 1; // Corresponds to j in the paper
1706        let mut offset = 0; // Corresponds to k in the paper, but starting at 0
1707        // to match 0-based indexing.
1708        let mut period = 1; // Corresponds to p in the paper
1709        let n = arr.len();
1710
1711        while right + offset < n {
1712            let a = arr[n - (1 + right + offset)];
1713            let b = arr[n - (1 + left + offset)];
1714            if (a < b && !order_greater) || (a > b && order_greater) {
1715                // Suffix is smaller, period is entire prefix so far.
1716                right += offset + 1;
1717                offset = 0;
1718                period = right - left;
1719            } else if a == b {
1720                // Advance through repetition of the current period.
1721                if offset + 1 == period {
1722                    right += offset + 1;
1723                    offset = 0;
1724                } else {
1725                    offset += 1;
1726                }
1727            } else {
1728                // Suffix is larger, start over from current location.
1729                left = right;
1730                right += 1;
1731                offset = 0;
1732                period = 1;
1733            }
1734            if period == known_period {
1735                break;
1736            }
1737        }
1738        debug_assert!(period <= known_period);
1739        left
1740    }
1741}
1742
1743// TwoWayStrategy allows the algorithm to either skip non-matches as quickly
1744// as possible, or to work in a mode where it emits Rejects relatively quickly.
1745trait TwoWayStrategy {
1746    type Output;
1747    fn use_early_reject() -> bool;
1748    fn rejecting(a: usize, b: usize) -> Self::Output;
1749    fn matching(a: usize, b: usize) -> Self::Output;
1750}
1751
1752/// Skip to match intervals as quickly as possible
1753enum MatchOnly {}
1754
1755impl TwoWayStrategy for MatchOnly {
1756    type Output = Option<(usize, usize)>;
1757
1758    #[inline]
1759    fn use_early_reject() -> bool {
1760        false
1761    }
1762    #[inline]
1763    fn rejecting(_a: usize, _b: usize) -> Self::Output {
1764        None
1765    }
1766    #[inline]
1767    fn matching(a: usize, b: usize) -> Self::Output {
1768        Some((a, b))
1769    }
1770}
1771
1772/// Emit Rejects regularly
1773enum RejectAndMatch {}
1774
1775impl TwoWayStrategy for RejectAndMatch {
1776    type Output = SearchStep;
1777
1778    #[inline]
1779    fn use_early_reject() -> bool {
1780        true
1781    }
1782    #[inline]
1783    fn rejecting(a: usize, b: usize) -> Self::Output {
1784        SearchStep::Reject(a, b)
1785    }
1786    #[inline]
1787    fn matching(a: usize, b: usize) -> Self::Output {
1788        SearchStep::Match(a, b)
1789    }
1790}
1791
1792/// SIMD search for short needles based on
1793/// Wojciech Muła's "SIMD-friendly algorithms for substring searching"[0]
1794///
1795/// It skips ahead by the vector width on each iteration (rather than the needle length as two-way
1796/// does) by probing the first and last byte of the needle for the whole vector width
1797/// and only doing full needle comparisons when the vectorized probe indicated potential matches.
1798///
1799/// Since the x86_64 baseline only offers SSE2 we only use u8x16 here.
1800/// If we ever ship std with for x86-64-v3 or adapt this for other platforms then wider vectors
1801/// should be evaluated.
1802///
1803/// For haystacks smaller than vector-size + needle length it falls back to
1804/// a naive O(n*m) search so this implementation should not be called on larger needles.
1805///
1806/// [0]: http://0x80.pl/articles/simd-strfind.html#sse-avx2
1807#[cfg(all(target_arch = "x86_64", target_feature = "sse2"))]
1808#[inline]
1809fn simd_contains(needle: &str, haystack: &str) -> Option<bool> {
1810    let needle = needle.as_bytes();
1811    let haystack = haystack.as_bytes();
1812
1813    debug_assert!(needle.len() > 1);
1814
1815    use crate::ops::BitAnd;
1816    use crate::simd::cmp::SimdPartialEq;
1817    use crate::simd::{mask8x16 as Mask, u8x16 as Block};
1818
1819    let first_probe = needle[0];
1820    let last_byte_offset = needle.len() - 1;
1821
1822    // the offset used for the 2nd vector
1823    let second_probe_offset = if needle.len() == 2 {
1824        // never bail out on len=2 needles because the probes will fully cover them and have
1825        // no degenerate cases.
1826        1
1827    } else {
1828        // try a few bytes in case first and last byte of the needle are the same
1829        let Some(second_probe_offset) =
1830            (needle.len().saturating_sub(4)..needle.len()).rfind(|&idx| needle[idx] != first_probe)
1831        else {
1832            // fall back to other search methods if we can't find any different bytes
1833            // since we could otherwise hit some degenerate cases
1834            return None;
1835        };
1836        second_probe_offset
1837    };
1838
1839    // do a naive search if the haystack is too small to fit
1840    if haystack.len() < Block::LEN + last_byte_offset {
1841        return Some(haystack.windows(needle.len()).any(|c| c == needle));
1842    }
1843
1844    let first_probe: Block = Block::splat(first_probe);
1845    let second_probe: Block = Block::splat(needle[second_probe_offset]);
1846    // first byte are already checked by the outer loop. to verify a match only the
1847    // remainder has to be compared.
1848    let trimmed_needle = &needle[1..];
1849
1850    // this #[cold] is load-bearing, benchmark before removing it...
1851    let check_mask = #[cold]
1852    |idx, mask: u16, skip: bool| -> bool {
1853        if skip {
1854            return false;
1855        }
1856
1857        // and so is this. optimizations are weird.
1858        let mut mask = mask;
1859
1860        while mask != 0 {
1861            let trailing = mask.trailing_zeros();
1862            let offset = idx + trailing as usize + 1;
1863            // SAFETY: mask is between 0 and 15 trailing zeroes, we skip one additional byte that was already compared
1864            // and then take trimmed_needle.len() bytes. This is within the bounds defined by the outer loop
1865            unsafe {
1866                let sub = haystack.get_unchecked(offset..).get_unchecked(..trimmed_needle.len());
1867                if small_slice_eq(sub, trimmed_needle) {
1868                    return true;
1869                }
1870            }
1871            mask &= !(1 << trailing);
1872        }
1873        false
1874    };
1875
1876    let test_chunk = |idx| -> u16 {
1877        // SAFETY: this requires at least LANES bytes being readable at idx
1878        // that is ensured by the loop ranges (see comments below)
1879        let a: Block = unsafe { haystack.as_ptr().add(idx).cast::<Block>().read_unaligned() };
1880        // SAFETY: this requires LANES + block_offset bytes being readable at idx
1881        let b: Block = unsafe {
1882            haystack.as_ptr().add(idx).add(second_probe_offset).cast::<Block>().read_unaligned()
1883        };
1884        let eq_first: Mask = a.simd_eq(first_probe);
1885        let eq_last: Mask = b.simd_eq(second_probe);
1886        let both = eq_first.bitand(eq_last);
1887        let mask = both.to_bitmask() as u16;
1888
1889        mask
1890    };
1891
1892    let mut i = 0;
1893    let mut result = false;
1894    // The loop condition must ensure that there's enough headroom to read LANE bytes,
1895    // and not only at the current index but also at the index shifted by block_offset
1896    const UNROLL: usize = 4;
1897    while i + last_byte_offset + UNROLL * Block::LEN < haystack.len() && !result {
1898        let mut masks = [0u16; UNROLL];
1899        for j in 0..UNROLL {
1900            masks[j] = test_chunk(i + j * Block::LEN);
1901        }
1902        for j in 0..UNROLL {
1903            let mask = masks[j];
1904            if mask != 0 {
1905                result |= check_mask(i + j * Block::LEN, mask, result);
1906            }
1907        }
1908        i += UNROLL * Block::LEN;
1909    }
1910    while i + last_byte_offset + Block::LEN < haystack.len() && !result {
1911        let mask = test_chunk(i);
1912        if mask != 0 {
1913            result |= check_mask(i, mask, result);
1914        }
1915        i += Block::LEN;
1916    }
1917
1918    // Process the tail that didn't fit into LANES-sized steps.
1919    // This simply repeats the same procedure but as right-aligned chunk instead
1920    // of a left-aligned one. The last byte must be exactly flush with the string end so
1921    // we don't miss a single byte or read out of bounds.
1922    let i = haystack.len() - last_byte_offset - Block::LEN;
1923    let mask = test_chunk(i);
1924    if mask != 0 {
1925        result |= check_mask(i, mask, result);
1926    }
1927
1928    Some(result)
1929}
1930
1931/// Compares short slices for equality.
1932///
1933/// It avoids a call to libc's memcmp which is faster on long slices
1934/// due to SIMD optimizations but it incurs a function call overhead.
1935///
1936/// # Safety
1937///
1938/// Both slices must have the same length.
1939#[cfg(all(target_arch = "x86_64", target_feature = "sse2"))] // only called on x86
1940#[inline]
1941unsafe fn small_slice_eq(x: &[u8], y: &[u8]) -> bool {
1942    debug_assert_eq!(x.len(), y.len());
1943    // This function is adapted from
1944    // https://github.com/BurntSushi/memchr/blob/8037d11b4357b0f07be2bb66dc2659d9cf28ad32/src/memmem/util.rs#L32
1945
1946    // If we don't have enough bytes to do 4-byte at a time loads, then
1947    // fall back to the naive slow version.
1948    //
1949    // Potential alternative: We could do a copy_nonoverlapping combined with a mask instead
1950    // of a loop. Benchmark it.
1951    if x.len() < 4 {
1952        for (&b1, &b2) in x.iter().zip(y) {
1953            if b1 != b2 {
1954                return false;
1955            }
1956        }
1957        return true;
1958    }
1959    // When we have 4 or more bytes to compare, then proceed in chunks of 4 at
1960    // a time using unaligned loads.
1961    //
1962    // Also, why do 4 byte loads instead of, say, 8 byte loads? The reason is
1963    // that this particular version of memcmp is likely to be called with tiny
1964    // needles. That means that if we do 8 byte loads, then a higher proportion
1965    // of memcmp calls will use the slower variant above. With that said, this
1966    // is a hypothesis and is only loosely supported by benchmarks. There's
1967    // likely some improvement that could be made here. The main thing here
1968    // though is to optimize for latency, not throughput.
1969
1970    // SAFETY: Via the conditional above, we know that both `px` and `py`
1971    // have the same length, so `px < pxend` implies that `py < pyend`.
1972    // Thus, dereferencing both `px` and `py` in the loop below is safe.
1973    //
1974    // Moreover, we set `pxend` and `pyend` to be 4 bytes before the actual
1975    // end of `px` and `py`. Thus, the final dereference outside of the
1976    // loop is guaranteed to be valid. (The final comparison will overlap with
1977    // the last comparison done in the loop for lengths that aren't multiples
1978    // of four.)
1979    //
1980    // Finally, we needn't worry about alignment here, since we do unaligned
1981    // loads.
1982    unsafe {
1983        let (mut px, mut py) = (x.as_ptr(), y.as_ptr());
1984        let (pxend, pyend) = (px.add(x.len() - 4), py.add(y.len() - 4));
1985        while px < pxend {
1986            let vx = (px as *const u32).read_unaligned();
1987            let vy = (py as *const u32).read_unaligned();
1988            if vx != vy {
1989                return false;
1990            }
1991            px = px.add(4);
1992            py = py.add(4);
1993        }
1994        let vx = (pxend as *const u32).read_unaligned();
1995        let vy = (pyend as *const u32).read_unaligned();
1996        vx == vy
1997    }
1998}