2 releases
new 0.2.2 | Nov 26, 2024 |
---|---|
0.2.1 | Aug 22, 2024 |
0.1.3 |
|
0.1.2 |
|
#2 in #wyhash
Used in museair
59KB
1.5K
SLoC
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
).
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 mixingWyHash32
, 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. TheCondom
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 alsoWyhash::hash_with_seed
andWyhash::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 of
WyHash
withwith_seed
orwith_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 makestd::hash::Hasher
andstd::hash::BuildHasher
not be implemented forWhHasher
, while make this crateno_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.