| memchr |
| ====== |
| The `memchr` crate provides heavily optimized routines for searching bytes. |
| |
| [](https://github.com/BurntSushi/rust-memchr/actions) |
| [](https://crates.io/crates/memchr) |
| |
| Dual-licensed under MIT or the [UNLICENSE](http://unlicense.org). |
| |
| |
| ### Documentation |
| |
| [https://docs.rs/memchr](https://docs.rs/memchr) |
| |
| |
| ### Overview |
| |
| The `memchr` function is traditionally provided by libc, but its |
| performance can vary significantly depending on the specific |
| implementation of libc that is used. They can range from manually tuned |
| Assembly implementations (like that found in GNU's libc) all the way to |
| non-vectorized C implementations (like that found in MUSL). |
| |
| To smooth out the differences between implementations of libc, at least |
| on `x86_64` for Rust 1.27+, this crate provides its own implementation of |
| `memchr` that should perform competitively with the one found in GNU's libc. |
| The implementation is in pure Rust and has no dependency on a C compiler or an |
| Assembler. |
| |
| Additionally, GNU libc also provides an extension, `memrchr`. This crate |
| provides its own implementation of `memrchr` as well, on top of `memchr2`, |
| `memchr3`, `memrchr2` and `memrchr3`. The difference between `memchr` and |
| `memchr2` is that `memchr2` permits finding all occurrences of two bytes |
| instead of one. Similarly for `memchr3`. |
| |
| ### Compiling without the standard library |
| |
| memchr links to the standard library by default, but you can disable the |
| `std` feature if you want to use it in a `#![no_std]` crate: |
| |
| ```toml |
| [dependencies] |
| memchr = { version = "2", default-features = false } |
| ``` |
| |
| On x86 platforms, when the `std` feature is disabled, the SSE2 |
| implementation of memchr will be used in compilers that support it. When |
| `std` is enabled, the AVX implementation of memchr will be used if the CPU |
| is determined to support it at runtime. |
| |
| ### Using libc |
| |
| `memchr` is a routine that is part of libc, although this crate does not use |
| libc by default. Instead, it uses its own routines, which are either vectorized |
| or generic fallback routines. In general, these should be competitive with |
| what's in libc, although this has not been tested for all architectures. If |
| using `memchr` from libc is desirable and a vectorized routine is not otherwise |
| available in this crate, then enabling the `libc` feature will use libc's |
| version of `memchr`. |
| |
| The rest of the functions in this crate, e.g., `memchr2` or `memrchr3`, are not |
| a standard part of libc, so they will always use the implementations in this |
| crate. One exception to this is `memrchr`, which is an extension commonly found |
| on Linux. On Linux, `memrchr` is used in precisely the same scenario as |
| `memchr`, as described above. |
| |
| |
| ### Minimum Rust version policy |
| |
| This crate's minimum supported `rustc` version is `1.28.0`. |
| |
| The current policy is that the minimum Rust version required to use this crate |
| can be increased in minor version updates. For example, if `crate 1.0` requires |
| Rust 1.20.0, then `crate 1.0.z` for all values of `z` will also require Rust |
| 1.20.0 or newer. However, `crate 1.y` for `y > 0` may require a newer minimum |
| version of Rust. |
| |
| In general, this crate will be conservative with respect to the minimum |
| supported version of Rust. |
