xxhash_rust/lib.rs
1//!Implementation of [xxHash](https://github.com/Cyan4973/xxHash) in Rust
2//!
3//!Version corresponds to xxHash [releases](https://github.com/Cyan4973/xxHash/releases)
4//!
5//!Each algorithm is implemented via feature, allowing precise control over code size.
6//!
7//!## Example
8//!
9//!- Cargo.toml
10//!
11//!```toml
12//![dependencies.xxhash-rust]
13//!version = "0.8.5"
14//!features = ["xxh3", "const_xxh3"]
15//!```
16//!
17//!- main.rs
18//!
19//!```rust
20//!use xxhash_rust::const_xxh3::xxh3_64 as const_xxh3;
21//!use xxhash_rust::xxh3::xxh3_64;
22//!
23//!const TEST: u64 = const_xxh3(b"TEST");
24//!
25//!fn test_input(text: &str) -> bool {
26//! match xxh3_64(text.as_bytes()) {
27//! TEST => true,
28//! _ => false
29//! }
30//!}
31//!
32//!assert!(!test_input("tEST"));
33//!assert!(test_input("TEST"));
34//!```
35//!
36//!## Features:
37//!
38//!By default all features are off.
39//!
40//!- `std` - Enables `std::io::Write` trait implementation
41//!- `xxh32` - Enables 32bit algorithm. Suitable for x86 targets
42//!- `const_xxh32` - `const fn` version of `xxh32` algorithm
43//!- `xxh64` - Enables 64 algorithm. Suitable for x86_64 targets
44//!- `const_xxh64` - `const fn` version of `xxh64` algorithm
45//!- `xxh3` - Enables `xxh3` family of algorithms, superior to `xxh32` and `xxh64` in terms of performance.
46//!- `const_xxh3` - `const fn` version of `xxh3` algorithm
47//!
48//!## HW acceleration
49//!
50//!Similar to reference implementation, crate implements various SIMDs in `xxh3` depending on provided flags.
51//!All checks are performed only at compile time, hence user is encouraged to enable these accelerations (for example via `-C target_cpu=native`)
52//!
53//!Used SIMD acceleration:
54//!
55//!- SSE2 - widely available, can be safely enabled in 99% of cases. Enabled by default in `x86_64` targets.
56//!- AVX2;
57//!- AVX512;
58//!- Neon - Enabled by default on aarch64 targets (most likely);
59//!- Wasm SIMD128 - Has to be enabled via rust flag: `-Ctarget-feature=+simd128`
60//!
61//!## Streaming vs One-shot
62//!
63//!For performance reasons one-shot version of algorithm does not re-use streaming version.
64//!Unless needed, user is advised to use one-shot version which tends to be more optimal.
65//!
66//!## `cosnt fn` version
67//!
68//!While `const fn` provides compile time implementation, it does so at performance cost.
69//!Hence you should only use it at _compile_ time.
70//!
71//!To guarantee that something is computed at compile time make sure to initialize hash output
72//!as `const` or `static` variable, otherwise it is possible function is executed at runtime, which
73//!would be worse than regular algorithm.
74//!
75//!`const fn` is implemented in best possible way while conforming to limitations of Rust `const
76//!fn`, but these limitations are quite strict making any high performance code impossible.
77
78#![no_std]
79#![warn(missing_docs)]
80#![allow(clippy::style)]
81
82#[cfg(feature = "std")]
83extern crate std;
84
85#[cfg(any(feature = "xxh32", feature = "xxh3", feature = "xxh64"))]
86mod utils;
87
88#[cfg(any(feature = "xxh32", feature = "const_xxh32", feature = "xxh3", feature = "const_xxh3"))]
89mod xxh32_common;
90#[cfg(feature = "xxh32")]
91pub mod xxh32;
92#[cfg(feature = "const_xxh32")]
93pub mod const_xxh32;
94
95#[cfg(any(feature = "xxh64", feature = "const_xxh64", feature = "xxh3", feature = "const_xxh3"))]
96mod xxh64_common;
97#[cfg(feature = "xxh64")]
98pub mod xxh64;
99#[cfg(feature = "const_xxh64")]
100pub mod const_xxh64;
101
102#[cfg(any(feature = "xxh3", feature = "const_xxh3"))]
103mod xxh3_common;
104#[cfg(feature = "xxh3")]
105pub mod xxh3;
106#[cfg(feature = "const_xxh3")]
107pub mod const_xxh3;