Collaboration diagram for XXH3 family:

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

Macros
#define	XXH3_SECRET_SIZE_MIN 136

Typedefs
typedef struct XXH3_state_s	XXH3_state_t
	The 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)
	64-bit unseeded variant of XXH3.

XXH_PUBLIC_API XXH_PUREF XXH64_hash_t	XXH3_64bits_withSeed (XXH_NOESCAPE const void *input, size_t length, XXH64_hash_t seed)
	64-bit seeded variant of XXH3

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)
	64-bit variant of XXH3 with a custom "secret".

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)

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)
	Unseeded 128-bit variant of XXH3.

XXH_PUBLIC_API XXH_PUREF XXH128_hash_t	XXH3_128bits_withSeed (XXH_NOESCAPE const void *data, size_t len, XXH64_hash_t seed)
	Seeded 128-bit variant of XXH3.

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)
	Custom secret 128-bit variant of XXH3.

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)
	Custom secret 128-bit variant of XXH3.

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)

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()`.

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:

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

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:

AVX512
AVX2
SSE2
ARM NEON
WebAssembly SIMD128
POWER8 VSX
s390x ZVector This can be controlled via the XXH_VECTOR macro, but it automatically selects the best version according to predefined macros. For the x86 family, an automatic runtime dispatcher is included separately in xxh_x86dispatch.c.

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 1093 of file xxhash.h.

Typedef Documentation

◆ XXH3_state_t

typedef struct XXH3_state_s XXH3_state_t

The state struct for the XXH3 streaming API.

See also: XXH3_state_s for details.

Definition at line 1130 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

dst	The XXH128_canonical_t pointer to be stored to.
hash	The XXH128_hash_t to be converted.

Precondition: dst must not be NULL.

◆ 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().

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

src	The XXH128_canonical_t to convert.

Precondition: src must not be NULL.

Returns: The converted hash.

◆ XXH128_isEqual()

XXH_PUBLIC_API XXH_PUREF int XXH128_isEqual	(	XXH128_hash_t	h1,
		XXH128_hash_t	h2
	)

XXH128_isEqual(): Return: 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
	)

Unseeded 128-bit variant of XXH3.

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: XXH32(), XXH64(), XXH3_64bits(): equivalent for the other xxHash algorithms; XXH3_128bits_withSeed(), XXH3_128bits_withSecret(): other seeding variants; XXH3_128bits_reset(), XXH3_128bits_update(), XXH3_128bits_digest(): Streaming version.

◆ 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.

Note: Calling XXH3_128bits_digest() will not affect statePtr, so you can update, digest, and update again.

Parameters

statePtr The state struct to calculate the hash from.

Precondition: statePtr must not be NULL.

Returns: The calculated XXH3 128-bit hash value from that state.

◆ 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.

This function resets statePtr and generate a secret with default parameters. Call it before XXH3_128bits_update(). Digest will be equivalent to XXH3_128bits().

Parameters

statePtr The state struct to reset.

Precondition: statePtr must not be NULL.

Returns: XXH_OK on success, XXH_ERROR on failure.

◆ 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
	)

Custom secret 128-bit variant of XXH3.

See also: XXH_64bits_reset_withSecret().

◆ 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.

This function resets statePtr and generate a secret from seed. Call it before XXH3_128bits_update(). Digest will be equivalent to XXH3_128bits_withSeed().

Parameters

statePtr	The state struct to reset.
seed	The 64-bit seed to alter the state.

Precondition: statePtr must not be NULL.

Returns: XXH_OK on success, XXH_ERROR on failure.

◆ 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

statePtr	The state struct to update.
input	The block of data to be hashed, at least `length` bytes in size.
length	The 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.

◆ 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
	)

Custom secret 128-bit variant of XXH3.

See also: XXH3_64bits_withSecret().

◆ 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
	)

Seeded 128-bit variant of XXH3.

See also: XXH3_64bits_withSeed().

◆ XXH3_64bits()

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

64-bit unseeded variant of XXH3.

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: XXH32(), XXH64(), XXH3_128bits(): equivalent for the other xxHash algorithms; XXH3_64bits_withSeed(), XXH3_64bits_withSecret(): other seeding variants; XXH3_64bits_reset(), XXH3_64bits_update(), XXH3_64bits_digest(): Streaming version.

◆ 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.

Note: Calling XXH3_64bits_digest() will not affect statePtr, so you can update, digest, and update again.

Parameters

statePtr The state struct to calculate the hash from.

Precondition: statePtr must not be NULL.

Returns: The calculated XXH3 64-bit hash value from that state.

◆ 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.

This function resets statePtr and generate a secret with default parameters. Call it before XXH3_64bits_update(). Digest will be equivalent to XXH3_64bits().

Parameters

statePtr The state struct to reset.

Precondition: statePtr must not be NULL.

Returns: XXH_OK on success, XXH_ERROR on failure.

◆ 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
	)

XXH3_64bits_reset_withSecret(): 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).

◆ 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.

This function resets statePtr and generate a secret from seed. Call it before XXH3_64bits_update(). Digest will be equivalent to XXH3_64bits_withSeed().

Parameters

statePtr	The state struct to reset.
seed	The 64-bit seed to alter the state.

Precondition: statePtr must not be NULL.

Returns: XXH_OK on success, XXH_ERROR on failure.

◆ 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.

Call this to incrementally consume blocks of data.

Parameters

statePtr	The state struct to update.
input	The block of data to be hashed, at least `length` bytes in size.
length	The 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.

◆ 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
	)

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

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.

◆ 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
	)

64-bit seeded variant of XXH3

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.

Note: seed == 0 produces the same results as XXH3_64bits().

Parameters

input	The data to hash
length	The length
seed	The 64-bit seed to alter the state.

◆ 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_state	The state to copy to.
src_state	The state to copy from.

Precondition: dst_state and src_state must not be NULL and must not overlap.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ XXH3_SECRET_SIZE_MIN

Typedef Documentation

◆ XXH3_state_t

Function Documentation

◆ XXH128_canonicalFromHash()

◆ XXH128_cmp()

◆ XXH128_hashFromCanonical()

◆ XXH128_isEqual()

◆ XXH3_128bits()

◆ XXH3_128bits_digest()

◆ XXH3_128bits_reset()

◆ XXH3_128bits_reset_withSecret()

◆ XXH3_128bits_reset_withSeed()

◆ XXH3_128bits_update()

◆ XXH3_128bits_withSecret()

◆ XXH3_128bits_withSeed()

◆ XXH3_64bits()

◆ XXH3_64bits_digest()

◆ XXH3_64bits_reset()

◆ XXH3_64bits_reset_withSecret()

◆ XXH3_64bits_reset_withSeed()

◆ XXH3_64bits_update()

◆ XXH3_64bits_withSecret()

◆ XXH3_64bits_withSeed()

◆ XXH3_copyState()