Module memchr::memmem

This module provides forward and reverse substring search routines.

Unlike the standard library’s substring search routines, these work on arbitrary bytes. For all non-empty needles, these routines will report exactly the same values as the corresponding routines in the standard library. For the empty needle, the standard library reports matches only at valid UTF-8 boundaries, where as these routines will report matches at every position.

Other than being able to work on arbitrary bytes, the primary reason to prefer these routines over the standard library routines is that these will generally be faster. In some cases, significantly so.

Example: iterating over substring matches

This example shows how to use find_iter to find occurrences of a substring in a haystack.

use memchr::memmem;

let haystack = b"foo bar foo baz foo";

let mut it = memmem::find_iter(haystack, "foo");
assert_eq!(Some(0), it.next());
assert_eq!(Some(8), it.next());
assert_eq!(Some(16), it.next());
assert_eq!(None, it.next());

Example: iterating over substring matches in reverse

This example shows how to use rfind_iter to find occurrences of a substring in a haystack starting from the end of the haystack.

NOTE: This module does not implement double ended iterators, so reverse searches aren’t done by calling rev on a forward iterator.

use memchr::memmem;

let haystack = b"foo bar foo baz foo";

let mut it = memmem::rfind_iter(haystack, "foo");
assert_eq!(Some(16), it.next());
assert_eq!(Some(8), it.next());
assert_eq!(Some(0), it.next());
assert_eq!(None, it.next());

Example: repeating a search for the same needle

It may be possible for the overhead of constructing a substring searcher to be measurable in some workloads. In cases where the same needle is used to search many haystacks, it is possible to do construction once and thus to avoid it for subsequent searches. This can be done with a Finder (or a FinderRev for reverse searches).

use memchr::memmem;

let finder = memmem::Finder::new("foo");

assert_eq!(Some(4), finder.find(b"baz foo quux"));
assert_eq!(None, finder.find(b"quux baz bar"));

Structs

FindIter	An iterator over non-overlapping substring matches.
FindRevIter	An iterator over non-overlapping substring matches in reverse.
Finder	A single substring searcher fixed to a particular needle.
FinderBuilder	A builder for constructing non-default forward or reverse memmem finders.
FinderRev	A single substring reverse searcher fixed to a particular needle.

Enums

Prefilter

Prefilter controls whether heuristics are used to accelerate searching.

Functions

find	Returns the index of the first occurrence of the given needle.
find_iter	Returns an iterator over all occurrences of a substring in a haystack.
rfind	Returns the index of the last occurrence of the given needle.
rfind_iter	Returns a reverse iterator over all occurrences of a substring in a haystack.