XXH32 family

Collaboration diagram for XXH32 family:

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

Macros
#define	XXH_FALLTHROUGH
#define	XXH_HAS_ATTRIBUTE(x)   0
#define	XXH_HAS_C_ATTRIBUTE(x)   0
#define	XXH_HAS_CPP_ATTRIBUTE(x)   0

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

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

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 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_impl for implementation details

Macro Definition Documentation

XXH_FALLTHROUGH

#define XXH_FALLTHROUGH

Definition at line 635 of file xxhash.h.

XXH_HAS_ATTRIBUTE

#define XXH_HAS_ATTRIBUTE

(

x

)

0

Definition at line 606 of file xxhash.h.

XXH_HAS_C_ATTRIBUTE

#define XXH_HAS_C_ATTRIBUTE

(

x

)

0

Definition at line 613 of file xxhash.h.

XXH_HAS_CPP_ATTRIBUTE

#define XXH_HAS_CPP_ATTRIBUTE

(

x

)

0

Definition at line 619 of file xxhash.h.

Typedef Documentation

XXH32_state_t

struct XXH32_state_s 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().

Example code for incrementally hashing a file:

#include <stdio.h>
#include <xxhash.h>
#define BUFFER_SIZE 256
 
// Note: XXH64 and XXH3 use the same interface.
XXH32_hash_t
hashFile(FILE* stream)
{
    XXH32_state_t* state;
    unsigned char buf[BUFFER_SIZE];
    size_t amt;
    XXH32_hash_t hash;
 
    state = XXH32_createState();       // Create a state
    assert(state != NULL);             // Error check here
    XXH32_reset(state, 0xbaad5eed);    // Reset state with our seed
    while ((amt = fread(buf, 1, sizeof(buf), stream)) != 0) {
        XXH32_update(state, buf, amt); // Hash the file in chunks
    }
    hash = XXH32_digest(state);        // Finalize the hash
    XXH32_freeState(state);            // Clean up
    return hash;
}

See also

XXH32_state_s for details.

Definition at line 473 of file xxhash.h.

Function Documentation

XXH32()

XXH_PUBLIC_API 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

Parameters

input	The block of data to be hashed, at least length bytes in size.
length	The length of input, in bytes.
seed	The 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_canonicalFromHash()

XXH_PUBLIC_API void XXH32_canonicalFromHash	(	XXH32_canonical_t *	dst,
		XXH32_hash_t	hash
	)

Converts an XXH32_hash_t to a big endian XXH32_canonical_t.

Parameters

dst	The XXH32_canonical_t pointer to be stored to.
hash	The XXH32_hash_t to be converted.

Precondition

dst must not be NULL.

XXH32_copyState()

XXH_PUBLIC_API void XXH32_copyState	(	XXH32_state_t *	dst_state,
		const XXH32_state_t *	src_state
	)

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

XXH32_createState()

XXH_PUBLIC_API 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_digest()

XXH_PUBLIC_API 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

statePtr

The state struct to calculate the hash from.

Precondition

statePtr must not be NULL.

Returns

The calculated xxHash32 value from that state.

XXH32_freeState()

XXH_PUBLIC_API XXH_errorcode XXH32_freeState

(

XXH32_state_t *

statePtr

)

Frees an XXH32_state_t.

Must be allocated with XXH32_createState().

Parameters

statePtr

A pointer to an XXH32_state_t allocated with XXH32_createState().

Returns

XXH_OK.

XXH32_hashFromCanonical()

XXH_PUBLIC_API XXH32_hash_t XXH32_hashFromCanonical

(

const XXH32_canonical_t *

src

)

Converts an XXH32_canonical_t to a native XXH32_hash_t.

Parameters

src	The XXH32_canonical_t to convert.

Precondition

src must not be NULL.

Returns

The converted hash.

XXH32_reset()

XXH_PUBLIC_API 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

statePtr	The state struct to reset.
seed	The 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_PUBLIC_API 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

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.