View Source xxh3 (xxh3 v0.3.6)

NIF bindings for XXH3 hash functions implemented in Rust

XXH3 is a new speed-optimized hash algorithm of the xxHash family of non-cryptographic hash functions, featuring:

  • Improved speed for both small and large inputs
  • True 64-bit and 128-bit outputs
  • SIMD acceleration
  • Improved 32-bit viability

Speed analysis methodology is explained here:

https://fastcompression.blogspot.com/2019/03/presenting-xxh3.html

Summary

Functions

Computes hash for streamed data.

Returns 64-bit hash for the given Data.

Returns 64-bit hash for the given Data with Seed value.

Returns 64-bit hash for the given Data with a custom Secret.

Returns 128-bit hash for the given Data.

Returns 128-bit hash for the given Data with Seed value.

Returns 128-bit hash for the given Data with a custom Secret.

Creates a new 64-bit hasher with default secret.

Creates a new 64-bit hasher with the given Seed.

Creates a new 64-bit hasher with the given Secret.

Resets hasher state.

Updates hasher state with the given chunk of data.

Types

-opaque xxh3_ref()

Functions

-spec digest(xxh3_ref()) -> non_neg_integer().

Computes hash for streamed data.

-spec hash64(binary()) -> non_neg_integer().

Returns 64-bit hash for the given Data.

This is default 64-bit variant, using default secret and default seed of 0. It's the fastest variant.

-spec hash64(binary(), non_neg_integer()) -> non_neg_integer().

Returns 64-bit hash for the given Data with Seed value.

This variant generates a custom secret on the fly based on default secret altered using the Seed value. While this operation is decently fast, note that it's not completely free.

Link to this function

hash64_with_secret(Data, Secret)

View Source
-spec hash64_with_secret(binary(), binary()) -> non_neg_integer().

Returns 64-bit hash for the given Data with a custom Secret.

It's possible to provide any binary as a "secret" to generate the hash. This makes it more difficult for an external actor to prepare an intentional collision. The main condition is that Secret size *must* be large enough (>= 136 bytes). However, the quality of produced hash values depends on secret's entropy. Technically, the secret must look like a bunch of random bytes. Avoid "trivial" or structured data such as repeated sequences or a text document.

-spec hash128(binary()) -> non_neg_integer().

Returns 128-bit hash for the given Data.

This is default 128-bit variant, using default secret and default seed of 0.

-spec hash128(binary(), non_neg_integer()) -> non_neg_integer().

Returns 128-bit hash for the given Data with Seed value.

See hash64/2 for more details.

Link to this function

hash128_with_secret(Data, Secret)

View Source
-spec hash128_with_secret(binary(), binary()) -> non_neg_integer().

Returns 128-bit hash for the given Data with a custom Secret.

See hash64_with_secret/2 for more details.

-spec new() -> xxh3_ref().

Creates a new 64-bit hasher with default secret.

You can stream data to the returned object using update/2, and calculate intermediate hash values using digest/1.

-spec new(non_neg_integer()) -> xxh3_ref().

Creates a new 64-bit hasher with the given Seed.

-spec new_with_secret(binary()) -> xxh3_ref().

Creates a new 64-bit hasher with the given Secret.

Secret must be a binary of size 192 bytes.

-spec reset(xxh3_ref()) -> ok.

Resets hasher state.

-spec update(xxh3_ref(), binary()) -> ok.

Updates hasher state with the given chunk of data.