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