Unravel Engine C++ Reference
Loading...
Searching...
No Matches
XXH3 family

Classes

struct  XXH128_hash_t
 The return value from 128-bit hashes. More...
 
struct  XXH128_canonical_t
 

Macros

#define XXH_SCALAR   0
 Possible values for XXH_VECTOR.
 
#define XXH_SSE2   1
 
#define XXH_AVX2   2
 
#define XXH_AVX512   3
 
#define XXH_NEON   4
 
#define XXH_VSX   5
 
#define XXH_SVE   6
 
#define XXH_LSX   7
 
#define XXH_LASX   8
 
#define XXH_RVV   9
 
#define XXH3_SECRET_SIZE_MIN   136
 

Typedefs

typedef struct XXH3_state_s XXH3_state_t
 The opaque state struct for the XXH3 streaming API.
 

Functions

XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits (XXH_NOESCAPE const void *input, size_t length)
 Calculates 64-bit unseeded variant of XXH3 hash of input.
 
XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_withSeed (XXH_NOESCAPE const void *input, size_t length, XXH64_hash_t seed)
 Calculates 64-bit seeded variant of XXH3 hash of input.
 
XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_withSecret (XXH_NOESCAPE const void *data, size_t len, XXH_NOESCAPE const void *secret, size_t secretSize)
 Calculates 64-bit variant of XXH3 with a custom "secret".
 
XXH_PUBLIC_API XXH_MALLOCF XXH3_state_tXXH3_createState (void)
 
XXH_PUBLIC_API XXH_errorcode XXH3_freeState (XXH3_state_t *statePtr)
 
XXH_PUBLIC_API void XXH3_copyState (XXH_NOESCAPE XXH3_state_t *dst_state, XXH_NOESCAPE const XXH3_state_t *src_state)
 Copies one XXH3_state_t to another.
 
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset (XXH_NOESCAPE XXH3_state_t *statePtr)
 Resets an XXH3_state_t to begin a new hash.
 
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSeed (XXH_NOESCAPE XXH3_state_t *statePtr, XXH64_hash_t seed)
 Resets an XXH3_state_t with 64-bit seed to begin a new hash.
 
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSecret (XXH_NOESCAPE XXH3_state_t *statePtr, XXH_NOESCAPE const void *secret, size_t secretSize)
 Resets an XXH3_state_t with secret data to begin a new hash.
 
XXH_PUBLIC_API XXH_errorcode XXH3_64bits_update (XXH_NOESCAPE XXH3_state_t *statePtr, XXH_NOESCAPE const void *input, size_t length)
 Consumes a block of input to an XXH3_state_t.
 
XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_digest (XXH_NOESCAPE const XXH3_state_t *statePtr)
 Returns the calculated XXH3 64-bit hash value from an XXH3_state_t.
 
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits (XXH_NOESCAPE const void *data, size_t len)
 Calculates 128-bit unseeded variant of XXH3 of data.
 
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSeed (XXH_NOESCAPE const void *data, size_t len, XXH64_hash_t seed)
 Calculates 128-bit seeded variant of XXH3 hash of data.
 
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSecret (XXH_NOESCAPE const void *data, size_t len, XXH_NOESCAPE const void *secret, size_t secretSize)
 Calculates 128-bit variant of XXH3 with a custom "secret".
 
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset (XXH_NOESCAPE XXH3_state_t *statePtr)
 Resets an XXH3_state_t to begin a new hash.
 
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSeed (XXH_NOESCAPE XXH3_state_t *statePtr, XXH64_hash_t seed)
 Resets an XXH3_state_t with 64-bit seed to begin a new hash.
 
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSecret (XXH_NOESCAPE XXH3_state_t *statePtr, XXH_NOESCAPE const void *secret, size_t secretSize)
 Resets an XXH3_state_t with secret data to begin a new hash.
 
XXH_PUBLIC_API XXH_errorcode XXH3_128bits_update (XXH_NOESCAPE XXH3_state_t *statePtr, XXH_NOESCAPE const void *input, size_t length)
 Consumes a block of input to an XXH3_state_t.
 
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_digest (XXH_NOESCAPE const XXH3_state_t *statePtr)
 Returns the calculated XXH3 128-bit hash value from an XXH3_state_t.
 
XXH_PUBLIC_API XXH_PUREF int XXH128_isEqual (XXH128_hash_t h1, XXH128_hash_t h2)
 Check equality of two XXH128_hash_t values.
 
XXH_PUBLIC_API XXH_PUREF int XXH128_cmp (XXH_NOESCAPE const void *h128_1, XXH_NOESCAPE const void *h128_2)
 Compares two XXH128_hash_t.
 
XXH_PUBLIC_API void XXH128_canonicalFromHash (XXH_NOESCAPE XXH128_canonical_t *dst, XXH128_hash_t hash)
 Converts an XXH128_hash_t to a big endian XXH128_canonical_t.
 
XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH128_hashFromCanonical (XXH_NOESCAPE const XXH128_canonical_t *src)
 Converts an XXH128_canonical_t to a native XXH128_hash_t.
 

Detailed Description


XXH3 is a more recent hash algorithm featuring:

Speed analysis methodology is explained here:

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

Compared to XXH64, expect XXH3 to run approximately ~2x faster on large inputs and >3x faster on small ones, exact differences vary depending on platform.

XXH3's speed benefits greatly from SIMD and 64-bit arithmetic, but does not require it. Most 32-bit and 64-bit targets that can run XXH32 smoothly can run XXH3 at competitive speeds, even without vector support. Further details are explained in the implementation.

XXH3 has a fast scalar implementation, but it also includes accelerated SIMD implementations for many common platforms:

XXH3 implementation is portable: it has a generic C90 formulation that can be compiled on any platform, all implementations generate exactly the same hash value on all platforms. Starting from v0.8.0, it's also labelled "stable", meaning that any future version will also generate the same hash value.

XXH3 offers 2 variants, _64bits and _128bits.

When only 64 bits are needed, prefer invoking the _64bits variant, as it reduces the amount of mixing, resulting in faster speed on small inputs. It's also generally simpler to manipulate a scalar return type than a struct.

The API supports one-shot hashing, streaming mode, and custom secrets.

Macro Definition Documentation

◆ XXH3_SECRET_SIZE_MIN

#define XXH3_SECRET_SIZE_MIN   136

The bare minimum size for a custom secret.

See also
XXH3_64bits_withSecret(), XXH3_64bits_reset_withSecret(), XXH3_128bits_withSecret(), XXH3_128bits_reset_withSecret().

Definition at line 1184 of file xxhash.h.

◆ XXH_AVX2

#define XXH_AVX2   2

AVX2 for Haswell and Bulldozer

Definition at line 1114 of file xxhash.h.

◆ XXH_AVX512

#define XXH_AVX512   3

AVX512 for Skylake and Icelake

Definition at line 1115 of file xxhash.h.

◆ XXH_LASX

#define XXH_LASX   8

LASX (256-bit SIMD) for LoongArch64

Definition at line 1120 of file xxhash.h.

◆ XXH_LSX

#define XXH_LSX   7

LSX (128-bit SIMD) for LoongArch64

Definition at line 1119 of file xxhash.h.

◆ XXH_NEON

#define XXH_NEON   4

NEON for most ARMv7-A, all AArch64, and WASM SIMD128

Definition at line 1116 of file xxhash.h.

◆ XXH_RVV

#define XXH_RVV   9

RVV (RISC-V Vector) for RISC-V

Definition at line 1121 of file xxhash.h.

◆ XXH_SCALAR

#define XXH_SCALAR   0

Possible values for XXH_VECTOR.

Unless set explicitly, determined automatically. Portable scalar version

Definition at line 1112 of file xxhash.h.

◆ XXH_SSE2

#define XXH_SSE2   1

SSE2 for Pentium 4, Opteron, all x86_64.

Definition at line 1113 of file xxhash.h.

◆ XXH_SVE

#define XXH_SVE   6

SVE for some ARMv8-A and ARMv9-A

Definition at line 1118 of file xxhash.h.

◆ XXH_VSX

#define XXH_VSX   5

VSX and ZVector for POWER8/z13 (64-bit)

Definition at line 1117 of file xxhash.h.

Typedef Documentation

◆ XXH3_state_t

typedef struct XXH3_state_s XXH3_state_t

The opaque state struct for the XXH3 streaming API.

See also
XXH3_state_s for details.
Streaming Example

Definition at line 1236 of file xxhash.h.

Function Documentation

◆ XXH128_canonicalFromHash()

XXH_PUBLIC_API void XXH128_canonicalFromHash ( XXH_NOESCAPE XXH128_canonical_t * dst,
XXH128_hash_t hash )

Converts an XXH128_hash_t to a big endian XXH128_canonical_t.

Parameters
dstThe XXH128_canonical_t pointer to be stored to.
hashThe XXH128_hash_t to be converted.
Precondition
dst must not be NULL.
See also
Canonical Representation Example

◆ XXH128_cmp()

XXH_PUBLIC_API XXH_PUREF int XXH128_cmp ( XXH_NOESCAPE const void * h128_1,
XXH_NOESCAPE const void * h128_2 )

Compares two XXH128_hash_t.

This comparator is compatible with stdlib's qsort()/bsearch().

Parameters
h128_1Left-hand side value
h128_2Right-hand side value
Returns
>0 if h128_1 > h128_2
=0 if h128_1 == h128_2
<0 if h128_1 < h128_2

◆ XXH128_hashFromCanonical()

XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH128_hashFromCanonical ( XXH_NOESCAPE const XXH128_canonical_t * src)

Converts an XXH128_canonical_t to a native XXH128_hash_t.

Parameters
srcThe XXH128_canonical_t to convert.
Precondition
src must not be NULL.
Returns
The converted hash.
See also
Canonical Representation Example

◆ XXH128_isEqual()

XXH_PUBLIC_API XXH_PUREF int XXH128_isEqual ( XXH128_hash_t h1,
XXH128_hash_t h2 )

Check equality of two XXH128_hash_t values.

Parameters
h1The 128-bit hash value.
h2Another 128-bit hash value.
Returns
1 if h1 and h2 are equal.
0 if they are not.

◆ XXH3_128bits()

XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits ( XXH_NOESCAPE const void * data,
size_t len )

Calculates 128-bit unseeded variant of XXH3 of data.

Parameters
dataThe block of data to be hashed, at least length bytes in size.
lenThe length of data, in bytes.
Returns
The calculated 128-bit variant of XXH3 value.

The 128-bit variant of XXH3 has more strength, but it has a bit of overhead for shorter inputs.

This is equivalent to XXH3_128bits_withSeed() with a seed of 0, however it may have slightly better performance due to constant propagation of the defaults.

See also
XXH3_128bits_withSeed(), XXH3_128bits_withSecret(): other seeding variants
Single Shot Example for an example.

◆ XXH3_128bits_digest()

XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_digest ( XXH_NOESCAPE const XXH3_state_t * statePtr)

Returns the calculated XXH3 128-bit hash value from an XXH3_state_t.

Parameters
statePtrThe state struct to calculate the hash from.
Precondition
statePtr must not be NULL.
Returns
The calculated XXH3 128-bit hash value from that state.
Note
Calling XXH3_128bits_digest() will not affect statePtr, so you can update, digest, and update again.

◆ XXH3_128bits_reset()

XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset ( XXH_NOESCAPE XXH3_state_t * statePtr)

Resets an XXH3_state_t to begin a new hash.

Parameters
statePtrThe state struct to reset.
Precondition
statePtr must not be NULL.
Returns
XXH_OK on success.
XXH_ERROR on failure.
Note
See also
Streaming Example

◆ XXH3_128bits_reset_withSecret()

XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSecret ( XXH_NOESCAPE XXH3_state_t * statePtr,
XXH_NOESCAPE const void * secret,
size_t secretSize )

Resets an XXH3_state_t with secret data to begin a new hash.

Parameters
statePtrThe state struct to reset.
secretThe secret data.
secretSizeThe length of secret, in bytes.
Precondition
statePtr must not be NULL.
Returns
XXH_OK on success.
XXH_ERROR on failure.

secret is referenced, it must outlive the hash streaming session. Similar to one-shot API, secretSize must be >= XXH3_SECRET_SIZE_MIN, and the quality of produced hash values depends on secret's entropy (secret's content should look like a bunch of random bytes). When in doubt about the randomness of a candidate secret, consider employing XXH3_generateSecret() instead (see below).

See also
Streaming Example

◆ XXH3_128bits_reset_withSeed()

XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSeed ( XXH_NOESCAPE XXH3_state_t * statePtr,
XXH64_hash_t seed )

Resets an XXH3_state_t with 64-bit seed to begin a new hash.

Parameters
statePtrThe state struct to reset.
seedThe 64-bit seed to alter the hash result predictably.
Precondition
statePtr must not be NULL.
Returns
XXH_OK on success.
XXH_ERROR on failure.
Note
See also
Streaming Example

◆ XXH3_128bits_update()

XXH_PUBLIC_API XXH_errorcode XXH3_128bits_update ( XXH_NOESCAPE XXH3_state_t * statePtr,
XXH_NOESCAPE const void * input,
size_t length )

Consumes a block of input to an XXH3_state_t.

Call this to incrementally consume blocks of data.

Parameters
statePtrThe state struct to update.
inputThe block of data to be hashed, at least length bytes in size.
lengthThe length of input, in bytes.
Precondition
statePtr must not be NULL.
Returns
XXH_OK on success.
XXH_ERROR on failure.
Note
The memory between input and input + length must be valid, readable, contiguous memory. However, if length is 0, input may be NULL. In C++, this also must be TriviallyCopyable.

◆ XXH3_128bits_withSecret()

XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSecret ( XXH_NOESCAPE const void * data,
size_t len,
XXH_NOESCAPE const void * secret,
size_t secretSize )

Calculates 128-bit variant of XXH3 with a custom "secret".

Parameters
dataThe block of data to be hashed, at least len bytes in size.
lenThe length of data, in bytes.
secretThe secret data.
secretSizeThe length of secret, in bytes.
Returns
The calculated 128-bit variant of XXH3 value.

It's possible to provide any blob of bytes 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 secretSize must be large enough (>= XXH3_SECRET_SIZE_MIN). However, the quality of the secret impacts the dispersion of the hash algorithm. Therefore, the secret must look like a bunch of random bytes. Avoid "trivial" or structured data such as repeated sequences or a text document. Whenever in doubt about the "randomness" of the blob of bytes, consider employing XXH3_generateSecret() instead (see below). It will generate a proper high entropy secret derived from the blob of bytes. Another advantage of using XXH3_generateSecret() is that it guarantees that all bits within the initial blob of bytes will impact every bit of the output. This is not necessarily the case when using the blob of bytes directly because, when hashing small inputs, only a portion of the secret is employed.

See also
Single Shot Example for an example.

◆ XXH3_128bits_withSeed()

XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSeed ( XXH_NOESCAPE const void * data,
size_t len,
XXH64_hash_t seed )

Calculates 128-bit seeded variant of XXH3 hash of data.

Parameters
dataThe block of data to be hashed, at least length bytes in size.
lenThe length of data, in bytes.
seedThe 64-bit seed to alter the hash result predictably.
Returns
The calculated 128-bit variant of XXH3 value.
Note
seed == 0 produces the same results as XXH3_64bits().

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.

See also
XXH3_128bits(), XXH3_128bits_withSecret(): other seeding variants
Single Shot Example for an example.

◆ XXH3_64bits()

XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits ( XXH_NOESCAPE const void * input,
size_t length )

Calculates 64-bit unseeded variant of XXH3 hash of input.

Parameters
inputThe block of data to be hashed, at least length bytes in size.
lengthThe length of input, in bytes.
Precondition
The memory between input and input + length must be valid, readable, contiguous memory. However, if length is 0, input may be NULL. In C++, this also must be TriviallyCopyable.
Returns
The calculated 64-bit XXH3 hash value.
Note
This is equivalent to XXH3_64bits_withSeed() with a seed of 0, however it may have slightly better performance due to constant propagation of the defaults.
See also
XXH3_64bits_withSeed(), XXH3_64bits_withSecret(): other seeding variants
Single Shot Example for an example.

◆ XXH3_64bits_digest()

XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_digest ( XXH_NOESCAPE const XXH3_state_t * statePtr)

Returns the calculated XXH3 64-bit hash value from an XXH3_state_t.

Parameters
statePtrThe state struct to calculate the hash from.
Precondition
statePtr must not be NULL.
Returns
The calculated XXH3 64-bit hash value from that state.
Note
Calling XXH3_64bits_digest() will not affect statePtr, so you can update, digest, and update again.
See also
Streaming Example

◆ XXH3_64bits_reset()

XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset ( XXH_NOESCAPE XXH3_state_t * statePtr)

Resets an XXH3_state_t to begin a new hash.

Parameters
statePtrThe state struct to reset.
Precondition
statePtr must not be NULL.
Returns
XXH_OK on success.
XXH_ERROR on failure.
Note
  • This function resets statePtr and generate a secret with default parameters.
  • Call this function before XXH3_64bits_update().
  • Digest will be equivalent to XXH3_64bits().
See also
Streaming Example

◆ XXH3_64bits_reset_withSecret()

XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSecret ( XXH_NOESCAPE XXH3_state_t * statePtr,
XXH_NOESCAPE const void * secret,
size_t secretSize )

Resets an XXH3_state_t with secret data to begin a new hash.

Parameters
statePtrThe state struct to reset.
secretThe secret data.
secretSizeThe length of secret, in bytes.
Precondition
statePtr must not be NULL.
Returns
XXH_OK on success.
XXH_ERROR on failure.
Note
secret is referenced, it must outlive the hash streaming session.

Similar to one-shot API, secretSize must be >= XXH3_SECRET_SIZE_MIN, and the quality of produced hash values depends on secret's entropy (secret's content should look like a bunch of random bytes). When in doubt about the randomness of a candidate secret, consider employing XXH3_generateSecret() instead (see below).

See also
Streaming Example

◆ XXH3_64bits_reset_withSeed()

XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSeed ( XXH_NOESCAPE XXH3_state_t * statePtr,
XXH64_hash_t seed )

Resets an XXH3_state_t with 64-bit seed to begin a new hash.

Parameters
statePtrThe state struct to reset.
seedThe 64-bit seed to alter the hash result predictably.
Precondition
statePtr must not be NULL.
Returns
XXH_OK on success.
XXH_ERROR on failure.
Note
See also
Streaming Example

◆ XXH3_64bits_update()

XXH_PUBLIC_API XXH_errorcode XXH3_64bits_update ( XXH_NOESCAPE XXH3_state_t * statePtr,
XXH_NOESCAPE const void * input,
size_t length )

Consumes a block of input to an XXH3_state_t.

Parameters
statePtrThe state struct to update.
inputThe block of data to be hashed, at least length bytes in size.
lengthThe length of input, in bytes.
Precondition
statePtr must not be NULL.
The memory between input and input + length must be valid, readable, contiguous memory. However, if length is 0, input may be NULL. In C++, this also must be TriviallyCopyable.
Returns
XXH_OK on success.
XXH_ERROR on failure.
Note
Call this to incrementally consume blocks of data.
See also
Streaming Example

◆ XXH3_64bits_withSecret()

XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_withSecret ( XXH_NOESCAPE const void * data,
size_t len,
XXH_NOESCAPE const void * secret,
size_t secretSize )

Calculates 64-bit variant of XXH3 with a custom "secret".

Parameters
dataThe block of data to be hashed, at least len bytes in size.
lenThe length of data, in bytes.
secretThe secret data.
secretSizeThe length of secret, in bytes.
Returns
The calculated 64-bit XXH3 hash value.
Precondition
The memory between data and data + len must be valid, readable, contiguous memory. However, if length is 0, data may be NULL. In C++, this also must be TriviallyCopyable.

It's possible to provide any blob of bytes 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 secretSize must be large enough (>= XXH3_SECRET_SIZE_MIN). However, the quality of the secret impacts the dispersion of the hash algorithm. Therefore, the secret must look like a bunch of random bytes. Avoid "trivial" or structured data such as repeated sequences or a text document. Whenever in doubt about the "randomness" of the blob of bytes, consider employing XXH3_generateSecret() instead (see below). It will generate a proper high entropy secret derived from the blob of bytes. Another advantage of using XXH3_generateSecret() is that it guarantees that all bits within the initial blob of bytes will impact every bit of the output. This is not necessarily the case when using the blob of bytes directly because, when hashing small inputs, only a portion of the secret is employed.

See also
Single Shot Example for an example.

◆ XXH3_64bits_withSeed()

XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_withSeed ( XXH_NOESCAPE const void * input,
size_t length,
XXH64_hash_t seed )

Calculates 64-bit seeded variant of XXH3 hash of input.

Parameters
inputThe block of data to be hashed, at least length bytes in size.
lengthThe length of input, in bytes.
seedThe 64-bit seed to alter the hash result predictably.
Precondition
The memory between input and input + length must be valid, readable, contiguous memory. However, if length is 0, input may be NULL. In C++, this also must be TriviallyCopyable.
Returns
The calculated 64-bit XXH3 hash value.
Note
seed == 0 produces the same results as XXH3_64bits().

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.

See also
Single Shot Example for an example.

◆ XXH3_copyState()

XXH_PUBLIC_API void XXH3_copyState ( XXH_NOESCAPE XXH3_state_t * dst_state,
XXH_NOESCAPE const XXH3_state_t * src_state )

Copies one XXH3_state_t to another.

Parameters
dst_stateThe state to copy to.
src_stateThe state to copy from.
Precondition
dst_state and src_state must not be NULL and must not overlap.

◆ XXH3_createState()

XXH_PUBLIC_API XXH_MALLOCF XXH3_state_t * XXH3_createState ( void )

◆ XXH3_freeState()

XXH_PUBLIC_API XXH_errorcode XXH3_freeState ( XXH3_state_t * statePtr)