Crate twox_hash 

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

Re-exports

pub use xxhash32::Hasher as XxHash32;xxhash32

pub use xxhash64::Hasher as XxHash64;xxhash64

pub use xxhash3_64::Hasher as XxHash3_64;xxhash3_64

pub use xxhash3_128::Hasher as XxHash3_128;xxhash3_128

Modules

xxhash3_64xxhash3_64

The implementation of XXH3_64.

xxhash3_128xxhash3_128

The implementation of XXH3_128.

xxhash32xxhash32

The implementation of XXH32.

xxhash64xxhash64

The implementation of XXH64.