xxHash 0.8.2
Extremely fast non-cryptographic hash function
Loading...
Searching...
No Matches
Data Structures | Typedefs | Functions
XXH32 family

Data Structures

struct  XXH32_canonical_t
 Canonical (big endian) representation of XXH32_hash_t. More...
 

Typedefs

typedef struct XXH32_state_s XXH32_state_t
 The opaque state struct for the XXH32 streaming API.
 

Functions

XXH32_hash_t XXH32 (const void *input, size_t length, XXH32_hash_t seed)
 Calculates the 32-bit hash of input using xxHash32.
 
XXH32_state_tXXH32_createState (void)
 Allocates an XXH32_state_t.
 
XXH_errorcode XXH32_freeState (XXH32_state_t *statePtr)
 Frees an XXH32_state_t.
 
void XXH32_copyState (XXH32_state_t *dst_state, const XXH32_state_t *src_state)
 Copies one XXH32_state_t to another.
 
XXH_errorcode XXH32_reset (XXH32_state_t *statePtr, XXH32_hash_t seed)
 Resets an XXH32_state_t to begin a new hash.
 
XXH_errorcode XXH32_update (XXH32_state_t *statePtr, const void *input, size_t length)
 Consumes a block of input to an XXH32_state_t.
 
XXH32_hash_t XXH32_digest (const XXH32_state_t *statePtr)
 Returns the calculated hash value from an XXH32_state_t.
 
void XXH32_canonicalFromHash (XXH32_canonical_t *dst, XXH32_hash_t hash)
 Converts an XXH32_hash_t to a big endian XXH32_canonical_t.
 
XXH32_hash_t XXH32_hashFromCanonical (const XXH32_canonical_t *src)
 Converts an XXH32_canonical_t to a native XXH32_hash_t.
 

Detailed Description

Contains functions used in the classic 32-bit xxHash algorithm.

Note
XXH32 is useful for older platforms, with no or poor 64-bit performance. Note that the XXH3 family provides competitive speed for both 32-bit and 64-bit systems, and offers true 64/128 bit hash results.
See also
XXH64 family, XXH3 family : Other xxHash families
XXH32 implementation for implementation details

Typedef Documentation

◆ XXH32_state_t

The opaque state struct for the XXH32 streaming API.

Streaming functions generate the xxHash value from an incremental input. This method is slower than single-call functions, due to state management. For small inputs, prefer XXH32() and XXH64(), which are better optimized.

An XXH state must first be allocated using XXH*_createState().

Start a new hash by initializing the state with a seed using XXH*_reset().

Then, feed the hash state by calling XXH*_update() as many times as necessary.

The function returns an error code, with 0 meaning OK, and any other value meaning there is an error.

Finally, a hash value can be produced anytime, by using XXH*_digest(). This function returns the nn-bits hash as an int or long long.

It's still possible to continue inserting input into the hash state after a digest, and generate new hash values later on by invoking XXH*_digest().

When done, release the state using XXH*_freeState().

See also
streaming_example at the top of xxhash.h for an example.
See also
XXH32_state_s for details.

Function Documentation

◆ XXH32()

XXH32_hash_t XXH32 ( const void *  input,
size_t  length,
XXH32_hash_t  seed 
)

Calculates the 32-bit hash of input using xxHash32.

Speed on Core 2 Duo @ 3 GHz (single thread, SMHasher benchmark): 5.4 GB/s

See Single Shot Example for an example.

Parameters
inputThe block of data to be hashed, at least length bytes in size.
lengthThe length of input, in bytes.
seedThe 32-bit seed to alter the hash's output 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 32-bit hash value.
See also
XXH64(), XXH3_64bits_withSeed(), XXH3_128bits_withSeed(), XXH128(): Direct equivalents for the other variants of xxHash.
XXH32_createState(), XXH32_update(), XXH32_digest(): Streaming version.

◆ XXH32_createState()

XXH32_state_t * XXH32_createState ( void  )

Allocates an XXH32_state_t.

Must be freed with XXH32_freeState().

Returns
An allocated XXH32_state_t on success, NULL on failure.

◆ XXH32_freeState()

XXH_errorcode XXH32_freeState ( XXH32_state_t statePtr)

Frees an XXH32_state_t.

Must be allocated with XXH32_createState().

Parameters
statePtrA pointer to an XXH32_state_t allocated with XXH32_createState().
Returns
XXH_OK.

◆ XXH32_copyState()

void XXH32_copyState ( XXH32_state_t dst_state,
const XXH32_state_t src_state 
)

Copies one XXH32_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.

◆ XXH32_reset()

XXH_errorcode XXH32_reset ( XXH32_state_t statePtr,
XXH32_hash_t  seed 
)

Resets an XXH32_state_t to begin a new hash.

This function resets and seeds a state. Call it before XXH32_update().

Parameters
statePtrThe state struct to reset.
seedThe 32-bit seed to alter the hash result predictably.
Precondition
statePtr must not be NULL.
Returns
XXH_OK on success, XXH_ERROR on failure.

◆ XXH32_update()

XXH_errorcode XXH32_update ( XXH32_state_t statePtr,
const void *  input,
size_t  length 
)

Consumes a block of input to an XXH32_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.
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.

◆ XXH32_digest()

XXH32_hash_t XXH32_digest ( const XXH32_state_t statePtr)

Returns the calculated hash value from an XXH32_state_t.

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

◆ XXH32_canonicalFromHash()

void XXH32_canonicalFromHash ( XXH32_canonical_t dst,
XXH32_hash_t  hash 
)

Converts an XXH32_hash_t to a big endian XXH32_canonical_t.

Parameters
dstThe XXH32_canonical_t pointer to be stored to.
hashThe XXH32_hash_t to be converted.
Precondition
dst must not be NULL.

The default return values from XXH functions are unsigned 32 and 64 bit integers.

The canonical representation uses big endian convention, the same convention as human-readable numbers (large digits first).

This way, hash values can be written into a file or buffer, remaining comparable across different systems.

The following functions allow transformation of hash values to and from their canonical format.

◆ XXH32_hashFromCanonical()

XXH32_hash_t XXH32_hashFromCanonical ( const XXH32_canonical_t src)

Converts an XXH32_canonical_t to a native XXH32_hash_t.

Parameters
srcThe XXH32_canonical_t to convert.
Precondition
src must not be NULL.
Returns
The converted hash.