A Rust implementation of the xxHash algorithm.

Examples

These examples use XxHash64 but the same ideas can be used for XxHash32, XxHash3_64, or XxHash3_128.

Hashing arbitrary data

When all the data is available at once

use twox_hash::XxHash64;

let seed = 1234;
let hash = XxHash64::oneshot(seed, b"some bytes");
assert_eq!(0xeab5_5659_a496_d78b, hash);

When the data is streaming

use std::hash::Hasher as _;
use twox_hash::XxHash64;

let seed = 1234;
let mut hasher = XxHash64::with_seed(seed);
hasher.write(b"some");
hasher.write(b" ");
hasher.write(b"bytes");
let hash = hasher.finish();
assert_eq!(0xeab5_5659_a496_d78b, hash);

In a HashMap

With a default seed

use std::{collections::HashMap, hash::BuildHasherDefault};
use twox_hash::XxHash64;

let mut hash = HashMap::<_, _, BuildHasherDefault<XxHash64>>::default();
hash.insert(42, "the answer");
assert_eq!(hash.get(&42), Some(&"the answer"));

With a random seed

use std::collections::HashMap;
use twox_hash::xxhash64;

let mut hash = HashMap::<_, _, xxhash64::RandomState>::default();
hash.insert(42, "the answer");
assert_eq!(hash.get(&42), Some(&"the answer"));

With a fixed seed

use std::collections::HashMap;
use twox_hash::xxhash64;

let mut hash = HashMap::with_hasher(xxhash64::State::with_seed(0xdead_cafe));
hash.insert(42, "the answer");
assert_eq!(hash.get(&42), Some(&"the answer"));

Feature Flags

name	description
xxhash32	Include the XxHash32 algorithm
xxhash64	Include the XxHash64 algorithm
xxhash3_64	Include the XxHash3_64 algorithm
xxhash3_128	Include the XxHash3_128 algorithm
random	Create random instances of the hashers
serialize	Serialize and deserialize hasher state with Serde
std	Use the Rust standard library. Enable this if you want SIMD support in XxHash3_64 or XxHash3_128
alloc	Use the Rust allocator library. Enable this if you want to create XxHash3_64 or XxHash3_128 with dynamic secrets

Benchmarks

See benchmarks in the comparison README.

Portability

The xxHash algorithms produce consistent output given consistent input. Inputs to the algorithms include the raw bytes being hashed as well as any configured seed or secret. The output does not depend on the platform; 32- and 64-bit systems produce the same output, as do little- and big-endian systems. The Rust implementation is verified against the reference C implementation.

The types in this crate implement the Hasher trait, used in conjunction with the [Hash][] trait. The Hash trait does not guarantee that implementors feed data into the Hasher in a platform-independent way. Notably, common types like [Vec<T>][] / &[T] or BTreeMap hash their lengths in a platform-dependent manner, producing different results between 32- and 64-bit systems.

In addition, types from the standard library explicitly do not guarantee that they will stay consistent from version to version.

If you need a long-term level of consistency for hashing generic types, you may want to create your own hashing trait where you control all implementations. You can then implement this trait for all of the types you need to hash and ensure that platform differences are handled and stability is maintained over time.

In other cases, it may be enough to write a wrapper around the hasher that deals with simple platform specifics, such as by adapting Hasher::write_usize to a fixed-size integer.

Contributing

1. Fork it (https://github.com/shepmaster/twox-hash/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Add a failing test.
4. Add code to pass the test.
5. Commit your changes (git commit -am 'Add some feature')
6. Ensure tests pass.
7. Push to the branch (git push origin my-new-feature)
8. Create a new Pull Request