You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
80 lines
3.2 KiB
80 lines
3.2 KiB
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.
|