wyhash-final4

This crate provides a pure rust implementation of wyhash_final4, the latest version of wyhash as of January 2024; wyhash which is an extremely fast hash function that can be implemented without any machine-specific instructions, while producing high quality hash result. See smhasher for hash function comparison details.

Related works

There are several other implementations of wyhash in rust, but none of them provides the latest version of wyhash (that is, the final4).

• wyhash
• wy
• wyhash2

Variants

This crate provides all the 4 variants of wyhash, namely

• WyHash64, the default variant, using 64-bit multiplication for mixing.
• WyHash64Condom, using 64-bit multiplication and an extra bit-xor for mixing
• WyHash32, using 32-bit multiplication for mixing.
• WyHash32Condom, using 32-bit multiplication and an extra bit-xor for mixing

It worth nothing to note that,

• the 32-bit variants are faster on 32-bit platform, but much slower on 64-bit platform;
• the Condom variants are slightly slower due to an extra bit-xor was used when mixing. As wyhash use multiplication for mixing, for some particular input (with a negligible probability of 2^-64 for WyHash64) the mixing becomes multiplying by zero, thus losing all the entropy. The Condom variants are resistant to this problem thanks to the extra bit-xor.

If you are not sure which variant to use, just use WyHash64.

Usage

This crate provides three ways to hash inputs:

• One-shot hashing, e.g. just call WyHash64::hash(input) to get the hash result. This is the simplest and the recommended way when default seed and secrets are used. There are also Wyhash::hash_with_seed and Wyhash::hash_with_secret for one-shot hashing with custom seed and secret, but unless the seed and secret changed over time, it's better to use the following methods.

• Create an instance ofWyHash with with_seed or with_seed_and_secret before hashing, e.g.

  let hasher = WyHash64::with_seed(fix_seed);
  hasher.hash(input1);
  hasher.hash(input2);
  

  The hasher can be reused for hashing multiple inputs, when seed and secret are fixed. It's faster than one-shot hashing in this scenario, as the initialization work will be done only once.

• Streamed hashing. When the input is too large to fit into a single buffer, or the length of input is unknown at the beginning, streamed hasher can be used.

  let mut hasher = WyHash64::with_seed(seed).streamed();
  hasher.write(chunk1);
  hasher.write(chunk2);
  hasher.write(chunk3);
  let hash = hasher.finish();
  

Also, WyHasher implements the std::hash::Hasher and std::hash::BuildHasher trait, thus can be used as a custom hasher for HashMap and HashSet.

Build Features

There are several build features that can be enabled or disabled:

• std. Disable this feature will make std::hash::Hasher and std::hash::BuildHasher not be implemented for WhHasher, while make this crate no_std compatible.

• wyhash64, wyhash64_condom, wyhash32, wyhash32_condom. Each of these features enables the corresponding variant of wyhash.

All the features are enabled by default.

License

The MIT License. See LICENSE file for details.