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//!- Neon - Enabled by default on aarch64 targets (most likely);
58//!- Wasm SIMD128 - Has to be enabled via rust flag: `-Ctarget-feature=+simd128`
59//!
60//!## Streaming vs One-shot
61//!
62//!For performance reasons one-shot version of algorithm does not re-use streaming version.
63//!Unless needed, user is advised to use one-shot version which tends to be more optimal.
64//!
65//!## `cosnt fn` version
66//!
67//!While `const fn` provides compile time implementation, it does so at performance cost.
68//!Hence you should only use it at _compile_ time.
69//!
70//!To guarantee that something is computed at compile time make sure to initialize hash output
71//!as `const` or `static` variable, otherwise it is possible function is executed at runtime, which
72//!would be worse than regular algorithm.
73//!
74//!`const fn` is implemented in best possible way while conforming to limitations of Rust `const
75//!fn`, but these limitations are quite strict making any high performance code impossible.
76
77#![no_std]
78#![warn(missing_docs)]
79#![allow(clippy::style)]
80
81#[cfg(feature = "std")]
82extern crate std;
83
84#[cfg(any(feature = "xxh32", feature = "xxh3", feature = "xxh64"))]
85mod utils;
86
87#[cfg(any(feature = "xxh32", feature = "const_xxh32", feature = "xxh3", feature = "const_xxh3"))]
88mod xxh32_common;
89#[cfg(feature = "xxh32")]
90pub mod xxh32;
91#[cfg(feature = "const_xxh32")]
92pub mod const_xxh32;
93
94#[cfg(any(feature = "xxh64", feature = "const_xxh64", feature = "xxh3", feature = "const_xxh3"))]
95mod xxh64_common;
96#[cfg(feature = "xxh64")]
97pub mod xxh64;
98#[cfg(feature = "const_xxh64")]
99pub mod const_xxh64;
100
101#[cfg(any(feature = "xxh3", feature = "const_xxh3"))]
102mod xxh3_common;
103#[cfg(feature = "xxh3")]
104pub mod xxh3;
105#[cfg(feature = "const_xxh3")]
106pub mod const_xxh3;