rapidhash

For use within a single execution (e.g., for HashMap or HashSet), use the Rust hashing traits. Note that in-memory hash outputs are not guaranteed to be stable across platforms, compiler versions, or crate versions.

Select a module based on your priority:

• rapidhash::fast: Optimized for speed. Best for standard data structures like HashMap and HashSet.
• rapidhash::quality: Optimized for statistical hash quality. Best for algorithms like HyperLogLog or MinHash.
• rapidhash::inner: Used to configure advanced parameters for specific use cases.

// Example: Using the fast module for a HashMap
use std::collections::HashMap;
use rapidhash::fast::RandomState;

let mut map: HashMap<_, _, RandomState> = HashMap::with_capacity_and_hasher(10, RandomState::new());

Rapidhash is a keyed hash function designed to be minimally resistant to Denial of Service (DoS) attacks. It aims to be immune to length extension and re-ordering attacks by randomizing the secrets array (a deviation from the original C++ implementation).

To achieve DoS resistance, you must instantiate the hasher through RandomState or RapidSecrets using a randomized secret seed.

Note: Rapidhash is not a cryptographic hash function. If the seed or secrets are known, collisions can be constructed, and an interactive attacker might attempt to learn the seed through observation.

If you need hash outputs that are stable across different platforms, compiler versions, or crate versions, use the rapidhash::v1, rapidhash::v2, or rapidhash::v3 modules. These modules provide C++ compatibility and guarantee stable outputs.

Recommendation: Use rapidhash::v3. It is the fastest, most recent version, and is the only version that supports streaming.

// Use v3 for the best performance and streaming support
// Outputs are guaranteed to be stable across versions
let hash = rapidhash::v3::hash(data);

The project provides Python scripts to generate visual charts and tables from benchmark data. These scripts use uv to manage dependencies automatically.

# generate the --bench bench charts
uv run generate_charts.py

# generate the --bench realworld table
uv run generate_table.py

Fuzzing can be performed on the raw rapidhash method or the RapidHasher struct (testing std::hash::Hasher trait implementations). This requires cargo-fuzz or cargo-afl to be installed.

# fuzz the raw rapidhash method (requires cargo-fuzz)
cargo +nightly fuzz run rapidhash

# fuzz the RapidHasher struct (requires cargo-fuzz)
cargo +nightly fuzz run rapidhasher

# use AFL fuzzing (requires cargo-afl)
cargo afl fuzz -i in -o out target/debug/afl_rapidhash

To build, test, and benchmark rapidhash (including the C implementations used for correctness verification), you need a C++ compiler, Rust, uv, and cargo-criterion for benchmarking.

Note: The benchmarks require the rapidhash-c code to be built, which necessitates a C++ compiler.

# install git and a C++ compiler
sudo yum install -y git gcc gcc-c++

# install rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

# install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# install cargo-criterion for benchmarks
cargo install cargo-criterion

# clone rapidhash
git clone https://github.com/hoxxep/rapidhash.git
cd rapidhash

Benchmarks are located in the rapidhash-bench crate. It is recommended to set RUSTFLAGS="-C target-cpu=native" to ensure the benchmarks reflect performance on your specific hardware. Most benchmark commands require the bench feature to be enabled.

# Navigate to the bench crate
cd rapidhash-bench

# Run all benchmarks
RUSTFLAGS="-C target-cpu=native" cargo criterion --plotting-backend disabled --bench bench --features bench

# Run the realworld benchmark
RUSTFLAGS="-C target-cpu=native" cargo criterion --plotting-backend disabled --bench realworld --features bench

# Run quality tests across various hash functions
RUSTFLAGS="-C target-cpu=native" cargo bench --bench quality --features bench

# Benchmark WASM targets
RUSTFLAGS="-C target-cpu=native" cargo criterion --plotting-backend disabled --bench wasm --features bench

You can run tests using standard cargo commands. Use the --all-features flag to test all capabilities, or specific flags to test no_std environments without std or unsafe features.

# Run tests
cargo +nightly test --all-features

# Run tests, for no_std with std = off and unsafe = off
cargo test --no-default-features --lib

# Check MSRV (Minimum Supported Rust Version)
cargo +1.77.0 test --features=std,rand,rng

To perform fuzz testing on rapidhash, you can use cargo fuzz or AFL. It is recommended to read the cargo fuzzing guide for general setup.

Depending on your target, you can fuzz the raw hashing method or the RapidHasher struct (which implements std::hash::Hasher). Note that these commands require the unsafe feature to be enabled.

# fuzz the raw rapidhash method.
cargo +nightly fuzz run --features unsafe rapidhash

# fuzz the RapidHasher struct with std::hash::Hasher write and finish calls.
cargo +nightly fuzz run --features unsafe rapidhasher

# use AFL fuzzing.
cargo afl fuzz -i in -o out target/debug/afl_rapidhash

The rapidhash CLI tool allows you to hash files or stdin quickly. It outputs the hash as a decimal u64. The CLI is fully compatible with C++ rapidhash V1, V2, and V3 algorithms.

To install via cargo:

cargo install rapidhash

To hash a file using the V3 algorithm:

rapidhash --v3 example.txt

To hash from stdin:

echo "example" | rapidhash --v3

# install
cargo install rapidhash

# hash a file (output: 8543579700415218186)
rapidhash --v3 example.txt

# hash stdin (output: 8543579700415218186)
echo "example" | rapidhash --v3