README.md
1memchr
2======
3The `memchr` crate provides heavily optimized routines for searching bytes.
4
5[](https://travis-ci.org/BurntSushi/rust-memchr)
6[](https://ci.appveyor.com/project/BurntSushi/rust-memchr/branch/master)
7[](https://crates.io/crates/memchr)
8
9Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org).
10
11
12### Documentation
13
14[https://docs.rs/memchr](https://docs.rs/memchr)
15
16
17### Overview
18
19The `memchr` function is traditionally provided by libc, however, the
20performance of `memchr` can vary significantly depending on the specific
21implementation of libc that is used. They can range from manually tuned
22Assembly implementations (like that found in GNU's libc) all the way to
23non-vectorized C implementations (like that found in MUSL).
24
25To smooth out the differences between implementations of libc, at least
26on `x86_64` for Rust 1.27+, this crate provides its own implementation of
27`memchr` that should perform competitively with the one found in GNU's libc.
28The implementation is in pure Rust and has no dependency on a C compiler or an
29Assembler.
30
31Additionally, GNU libc also provides an extension, `memrchr`. This crate
32provides its own implementation of `memrchr` as well, on top of `memchr2`,
33`memchr3`, `memrchr2` and `memrchr3`. The difference between `memchr` and
34`memchr2` is that that `memchr2` permits finding all occurrences of two bytes
35instead of one. Similarly for `memchr3`.
36
37### Compiling without the standard library
38
39memchr links to the standard library by default, but you can disable the
40`use_std` feature if you want to use it in a `#![no_std]` crate:
41
42```toml
43[dependencies]
44memchr = { version = "2", default-features = false }
45```
46
47On x86 platforms, when the `use_std` feature is disabled, the SSE2
48implementation of memchr will be used in compilers that support it. When
49`use_std` is enabled, the AVX implementation of memchr will be used if the CPU
50is determined to support it at runtime.
51
52### Using libc
53
54`memchr` is a routine that is part of libc, although this crate does not use
55libc by default. Instead, it uses its own routines, which are either vectorized
56or generic fallback routines. In general, these should be competitive with
57what's in libc, although this has not been tested for all architectures. If
58using `memchr` from libc is desirable and a vectorized routine is not otherwise
59available in this crate, then enabling the `libc` feature will use libc's
60version of `memchr`.
61
62The rest of the functions in this crate, e.g., `memchr2` or `memrchr3`, are not
63a standard part of libc, so they will always use the implementations in this
64crate. One exception to this is `memrchr`, which is an extension commonly found
65on Linux. On Linux, `memrchr` is used in precisely the same scenario as
66`memchr`, as described above.
67
){kind=link}