public class XXHash
extends java.lang.Object
xxHash is an extremely fast Hash algorithm, running at RAM speed limits. It also successfully passes all tests from the SMHasher suite.
A 64-bit version, named XXH64, is available since r35. It offers much better speed, but for 64-bit applications only.
XXH3 is a new hash algorithm, featuring improved speed performance for both small and large inputs. See full speed analysis at: Presenting XXH3
In general, expect XXH3 to run about ~2x faster on large inputs, and >3x faster on small ones, though exact differences depend on platform.
The algorithm is portable, will generate the same hash on all platforms. It benefits greatly from vectorization units, but does not require it.
XXH3 offers 2 variants, _64bits and _128bits. When only 64 bits are needed, prefer calling the _64bits variant: 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 XXH3 algorithm is still considered experimental. Produced results can still change between versions. Results produced by v0.7.x are not comparable with results from v0.7.y. It's nonetheless possible to use XXH3 for ephemeral data (local sessions), but avoid storing values in long-term storage for later reads.
The API supports one-shot hashing, streaming mode, and custom secrets.
| Modifier and Type | Field and Description |
|---|---|
static int |
XXH_3_SECRET_SIZE_MIN |
static int |
XXH_ERROR
Error codes.
|
static int |
XXH_OK
Error codes.
|
static int |
XXH_VERSION_MAJOR
The major version number.
|
static int |
XXH_VERSION_MINOR
The minor version number.
|
static int |
XXH_VERSION_NUMBER
The version number
|
static int |
XXH_VERSION_RELEASE
The release version number.
|
| Modifier and Type | Method and Description |
|---|---|
static void |
nXXH128_canonicalFromHash(long dst,
long hash) |
static int |
nXXH128_cmp(long h128_1,
long h128_2)
Unsafe version of:
XXH128_cmp(java.nio.ByteBuffer, java.nio.ByteBuffer) |
static void |
nXXH128_hashFromCanonical(long src,
long __result) |
static int |
nXXH128_isEqual(long h1,
long h2)
|
static void |
nXXH128(long data,
long len,
long seed,
long __result) |
static void |
nXXH3_128bits_digest(long statePtr,
long __result) |
static int |
nXXH3_128bits_reset_withSecret(long statePtr,
long secret,
long secretSize) |
static int |
nXXH3_128bits_reset_withSeed(long statePtr,
long seed) |
static int |
nXXH3_128bits_reset(long statePtr) |
static int |
nXXH3_128bits_update(long statePtr,
long input,
long length) |
static void |
nXXH3_128bits_withSecret(long data,
long len,
long secret,
long secretSize,
long __result) |
static void |
nXXH3_128bits_withSeed(long data,
long len,
long seed,
long __result) |
static void |
nXXH3_128bits(long data,
long len,
long __result) |
static long |
nXXH3_64bits_digest(long statePtr) |
static int |
nXXH3_64bits_reset_withSecret(long statePtr,
long secret,
long secretSize)
|
static int |
nXXH3_64bits_reset_withSeed(long statePtr,
long seed)
Unsafe version of:
XXH3_64bits_reset_withSeed(org.lwjgl.util.xxhash.XXH3State, long) |
static int |
nXXH3_64bits_reset(long statePtr)
Unsafe version of:
XXH3_64bits_reset(org.lwjgl.util.xxhash.XXH3State) |
static int |
nXXH3_64bits_update(long statePtr,
long input,
long length) |
static long |
nXXH3_64bits_withSecret(long data,
long len,
long secret,
long secretSize)
Unsafe version of:
XXH3_64bits_withSecret(java.nio.ByteBuffer, java.nio.ByteBuffer) |
static long |
nXXH3_64bits_withSeed(long data,
long len,
long seed)
Unsafe version of:
XXH3_64bits_withSeed(java.nio.ByteBuffer, long) |
static long |
nXXH3_64bits(long data,
long len)
Unsafe version of:
XXH3_64bits(java.nio.ByteBuffer) |
static void |
nXXH3_copyState(long dst_state,
long srct_state) |
static long |
nXXH3_createState() |
static int |
nXXH3_freeState(long statePtr) |
static void |
nXXH32_canonicalFromHash(long dst,
int hash)
Unsafe version of:
XXH32_canonicalFromHash(org.lwjgl.util.xxhash.XXH32Canonical, int) |
static void |
nXXH32_copyState(long dst_state,
long src_state) |
static long |
nXXH32_createState()
Unsafe version of:
XXH32_createState() |
static int |
nXXH32_digest(long statePtr)
Unsafe version of:
XXH32_digest(org.lwjgl.util.xxhash.XXH32State) |
static int |
nXXH32_freeState(long statePtr)
Unsafe version of:
XXH32_freeState(org.lwjgl.util.xxhash.XXH32State) |
static int |
nXXH32_hashFromCanonical(long src)
Unsafe version of:
XXH32_hashFromCanonical(org.lwjgl.util.xxhash.XXH32Canonical) |
static int |
nXXH32_reset(long statePtr,
int seed)
Unsafe version of:
XXH32_reset(org.lwjgl.util.xxhash.XXH32State, int) |
static int |
nXXH32_update(long statePtr,
long input,
long length)
Unsafe version of:
XXH32_update(org.lwjgl.util.xxhash.XXH32State, java.nio.ByteBuffer) |
static int |
nXXH32(long input,
long length,
int seed)
Unsafe version of:
XXH32(java.nio.ByteBuffer, int) |
static void |
nXXH64_canonicalFromHash(long dst,
long hash)
Unsafe version of:
XXH64_canonicalFromHash(org.lwjgl.util.xxhash.XXH64Canonical, long) |
static void |
nXXH64_copyState(long dst_state,
long src_state) |
static long |
nXXH64_createState()
Unsafe version of:
XXH64_createState() |
static long |
nXXH64_digest(long statePtr)
Unsafe version of:
XXH64_digest(org.lwjgl.util.xxhash.XXH64State) |
static int |
nXXH64_freeState(long statePtr)
Unsafe version of:
XXH64_freeState(org.lwjgl.util.xxhash.XXH64State) |
static long |
nXXH64_hashFromCanonical(long src)
Unsafe version of:
XXH64_hashFromCanonical(org.lwjgl.util.xxhash.XXH64Canonical) |
static int |
nXXH64_reset(long statePtr,
long seed)
Unsafe version of:
XXH64_reset(org.lwjgl.util.xxhash.XXH64State, long) |
static int |
nXXH64_update(long statePtr,
long input,
long length)
Unsafe version of:
XXH64_update(org.lwjgl.util.xxhash.XXH64State, java.nio.ByteBuffer) |
static long |
nXXH64(long input,
long length,
long seed)
Unsafe version of:
XXH64(java.nio.ByteBuffer, long) |
static void |
XXH128_canonicalFromHash(XXH128Canonical dst,
XXH128Hash hash) |
static int |
XXH128_cmp(java.nio.ByteBuffer h128_1,
java.nio.ByteBuffer h128_2)
This comparator is compatible with stdlib's
qsort(). |
static XXH128Hash |
XXH128_hashFromCanonical(XXH128Canonical src,
XXH128Hash __result) |
static boolean |
XXH128_isEqual(XXH128Hash h1,
XXH128Hash h2)
Returns 1 if equal, 0 if different.
|
static XXH128Hash |
XXH128(java.nio.ByteBuffer data,
long seed,
XXH128Hash __result) |
static XXH128Hash |
XXH3_128bits_digest(XXH3State statePtr,
XXH128Hash __result) |
static int |
XXH3_128bits_reset_withSecret(XXH3State statePtr,
java.nio.ByteBuffer secret) |
static int |
XXH3_128bits_reset_withSeed(XXH3State statePtr,
long seed) |
static int |
XXH3_128bits_reset(XXH3State statePtr) |
static int |
XXH3_128bits_update(XXH3State statePtr,
java.nio.ByteBuffer input) |
static XXH128Hash |
XXH3_128bits_withSecret(java.nio.ByteBuffer data,
java.nio.ByteBuffer secret,
XXH128Hash __result) |
static XXH128Hash |
XXH3_128bits_withSeed(java.nio.ByteBuffer data,
long seed,
XXH128Hash __result) |
static XXH128Hash |
XXH3_128bits(java.nio.ByteBuffer data,
XXH128Hash __result) |
static long |
XXH3_64bits_digest(XXH3State statePtr) |
static int |
XXH3_64bits_reset_withSecret(XXH3State statePtr,
java.nio.ByteBuffer secret)
secret is referenced, and must outlive the hash streaming session. |
static int |
XXH3_64bits_reset_withSeed(XXH3State statePtr,
long seed)
Generate a custom secret from
seed, and store it into state. |
static int |
XXH3_64bits_reset(XXH3State statePtr)
Initialize with default parameters.
|
static int |
XXH3_64bits_update(XXH3State statePtr,
java.nio.ByteBuffer input) |
static long |
XXH3_64bits_withSecret(java.nio.ByteBuffer data,
java.nio.ByteBuffer secret)
It's possible to provide any blob of bytes as a "secret" to generate the hash.
|
static long |
XXH3_64bits_withSeed(java.nio.ByteBuffer data,
long seed)
This variant generates on the fly a custom secret, based on the default secret, altered using the
seed value. |
static long |
XXH3_64bits(java.nio.ByteBuffer data)
Default 64-bit variant, using default secret and default seed of 0.
|
static void |
XXH3_copyState(XXH3State dst_state,
XXH3State srct_state) |
static XXH3State |
XXH3_createState() |
static int |
XXH3_freeState(XXH3State statePtr) |
static void |
XXH32_canonicalFromHash(XXH32Canonical dst,
int hash)
Default return values from XXH functions are basic unsigned 32 and 64 bits.
|
static void |
XXH32_copyState(XXH32State dst_state,
XXH32State src_state) |
static XXH32State |
XXH32_createState()
Creates memory for
XXH32_state_t. |
static int |
XXH32_digest(XXH32State statePtr)
Returns the final 32-bits hash of the specified
XXH32_state_t. |
static int |
XXH32_freeState(XXH32State statePtr)
Frees the specified
XXH32_state_t. |
static int |
XXH32_hashFromCanonical(XXH32Canonical src)
Transforms the specified canonical representation to a primitive value.
|
static int |
XXH32_reset(XXH32State statePtr,
int seed)
Resets the specified
XXH32_state_t. |
static int |
XXH32_update(XXH32State statePtr,
java.nio.ByteBuffer input)
Streaming functions generate the xxHash value from an incrememtal input.
|
static int |
XXH32(java.nio.ByteBuffer input,
int seed)
Calculates the 32-bits hash of sequence
length bytes stored at memory address input. |
static void |
XXH64_canonicalFromHash(XXH64Canonical dst,
long hash)
64-bit version of
32_canonicalFromHash. |
static void |
XXH64_copyState(XXH64State dst_state,
XXH64State src_state) |
static XXH64State |
XXH64_createState()
64-bit version of
32_createState. |
static long |
XXH64_digest(XXH64State statePtr)
64-bit version of
32_digest. |
static int |
XXH64_freeState(XXH64State statePtr)
64-bit version of
32_freeState. |
static long |
XXH64_hashFromCanonical(XXH64Canonical src)
64-bit version of
32_hashFromCanonical. |
static int |
XXH64_reset(XXH64State statePtr,
long seed)
64-bit version of
32_reset. |
static int |
XXH64_update(XXH64State statePtr,
java.nio.ByteBuffer input)
64-bit version of
32_update. |
static long |
XXH64(java.nio.ByteBuffer input,
long seed)
64-bit version of
32. |
public static final int XXH_OK
public static final int XXH_ERROR
public static final int XXH_VERSION_MAJOR
public static final int XXH_VERSION_MINOR
public static final int XXH_VERSION_RELEASE
public static final int XXH_VERSION_NUMBER
public static final int XXH_3_SECRET_SIZE_MIN
public static int nXXH32(long input,
long length,
int seed)
XXH32(java.nio.ByteBuffer, int)length - the number of bytes stored at memory address inputpublic static int XXH32(java.nio.ByteBuffer input,
int seed)
length bytes stored at memory address input.input - the bytes to hash. The memory between input & input+length must be valid (allocated and read-accessible).seed - the seed that can be used to alter the result predictablypublic static long nXXH32_createState()
XXH32_createState()@Nullable public static XXH32State XXH32_createState()
XXH32_state_t. The state must then be initialized using 32_reset before first use.
LWJGL note: This function simply delegates to the system malloc() function.
public static int nXXH32_freeState(long statePtr)
XXH32_freeState(org.lwjgl.util.xxhash.XXH32State)public static int XXH32_freeState(XXH32State statePtr)
XXH32_state_t.statePtr - the state to freepublic static void nXXH32_copyState(long dst_state,
long src_state)
public static void XXH32_copyState(XXH32State dst_state, XXH32State src_state)
public static int nXXH32_reset(long statePtr,
int seed)
XXH32_reset(org.lwjgl.util.xxhash.XXH32State, int)public static int XXH32_reset(XXH32State statePtr, int seed)
XXH32_state_t.statePtr - the XXH32_state_t to resetseed - the seed that can be used to alter the hashing result predictablypublic static int nXXH32_update(long statePtr,
long input,
long length)
XXH32_update(org.lwjgl.util.xxhash.XXH32State, java.nio.ByteBuffer)length - the number of bytes stored at memory address inputpublic static int XXH32_update(XXH32State statePtr, java.nio.ByteBuffer input)
32.
XXH state must first be allocated, using 32_createState.
Start a new hash by initializing state with a seed, using 32_reset.
Then, feed the hash state by calling 32_update as many times as necessary. Obviously, input must be allocated and read accessible. 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 32_digest. This function returns the 32-bits hash as an int.
It's still possible to continue inserting input into the hash state after a digest, and generate some new hash values later on, by calling again
32_digest.
When done, release the state, using 32_freeState.
statePtr - the XXH32_state_t to useinput - the bytes to hash. The memory between input & input+length must be valid (allocated and read-accessible).public static int nXXH32_digest(long statePtr)
XXH32_digest(org.lwjgl.util.xxhash.XXH32State)public static int XXH32_digest(XXH32State statePtr)
XXH32_state_t.statePtr - the XXH32_state_t to usepublic static void nXXH32_canonicalFromHash(long dst,
int hash)
XXH32_canonicalFromHash(org.lwjgl.util.xxhash.XXH32Canonical, int)public static void XXH32_canonicalFromHash(XXH32Canonical dst, int hash)
The canonical representation settles this issue, by mandating big-endian convention, aka, the same convention as human-readable numbers (large digits first). When writing hash values to storage, sending them over a network, or printing them, it's highly recommended to use the canonical representation, to ensure portability across a wider range of systems, present and future.
The following functions allow transformation of hash values into and from canonical format.
dst - the destination canonical representationhash - the source hashpublic static int nXXH32_hashFromCanonical(long src)
XXH32_hashFromCanonical(org.lwjgl.util.xxhash.XXH32Canonical)public static int XXH32_hashFromCanonical(XXH32Canonical src)
src - the source canonical representationpublic static long nXXH64(long input,
long length,
long seed)
XXH64(java.nio.ByteBuffer, long)length - the number of bytes stored at memory address inputpublic static long XXH64(java.nio.ByteBuffer input,
long seed)
32.
This function runs 2x faster on 64-bits systems, but slower on 32-bits systems.
input - the bytes to hash. The memory between input & input+length must be valid (allocated and read-accessible).seed - the seed that can be used to alter the result predictablypublic static long nXXH64_createState()
XXH64_createState()@Nullable public static XXH64State XXH64_createState()
32_createState.public static int nXXH64_freeState(long statePtr)
XXH64_freeState(org.lwjgl.util.xxhash.XXH64State)public static int XXH64_freeState(XXH64State statePtr)
32_freeState.statePtr - the state to freepublic static void nXXH64_copyState(long dst_state,
long src_state)
public static void XXH64_copyState(XXH64State dst_state, XXH64State src_state)
public static int nXXH64_reset(long statePtr,
long seed)
XXH64_reset(org.lwjgl.util.xxhash.XXH64State, long)public static int XXH64_reset(XXH64State statePtr, long seed)
32_reset.statePtr - the XXH64_state_t to resetseed - the seed that can be used to alter the hashing result predictablypublic static int nXXH64_update(long statePtr,
long input,
long length)
XXH64_update(org.lwjgl.util.xxhash.XXH64State, java.nio.ByteBuffer)length - the number of bytes stored at memory address inputpublic static int XXH64_update(XXH64State statePtr, java.nio.ByteBuffer input)
32_update.statePtr - the XXH64_state_t to useinput - the bytes to hash. The memory between input & input+length must be valid (allocated and read-accessible).public static long nXXH64_digest(long statePtr)
XXH64_digest(org.lwjgl.util.xxhash.XXH64State)public static long XXH64_digest(XXH64State statePtr)
32_digest.statePtr - the XXH64_state_t to usepublic static void nXXH64_canonicalFromHash(long dst,
long hash)
XXH64_canonicalFromHash(org.lwjgl.util.xxhash.XXH64Canonical, long)public static void XXH64_canonicalFromHash(XXH64Canonical dst, long hash)
32_canonicalFromHash.dst - the destination canonical representationhash - the source hashpublic static long nXXH64_hashFromCanonical(long src)
XXH64_hashFromCanonical(org.lwjgl.util.xxhash.XXH64Canonical)public static long XXH64_hashFromCanonical(XXH64Canonical src)
32_hashFromCanonical.src - the source canonical representationpublic static long nXXH3_64bits(long data,
long len)
XXH3_64bits(java.nio.ByteBuffer)public static long XXH3_64bits(java.nio.ByteBuffer data)
It's the fastest variant.
public static long nXXH3_64bits_withSecret(long data,
long len,
long secret,
long secretSize)
XXH3_64bits_withSecret(java.nio.ByteBuffer, java.nio.ByteBuffer)public static long XXH3_64bits_withSecret(java.nio.ByteBuffer data,
java.nio.ByteBuffer secret)
The secret must be large enough (≥ 3_SECRET_SIZE_MIN). It should consist of random bytes. Avoid repeating same character, or sequences of
bytes, and especially avoid swathes of \0. Failure to respect these conditions will result in a poor quality hash.
public static long nXXH3_64bits_withSeed(long data,
long len,
long seed)
XXH3_64bits_withSeed(java.nio.ByteBuffer, long)public static long XXH3_64bits_withSeed(java.nio.ByteBuffer data,
long seed)
seed value.
While this operation is decently fast, note that it's not completely free. Note seed==0 produces same results as 3_64bits.
public static long nXXH3_createState()
@Nullable public static XXH3State XXH3_createState()
public static int nXXH3_freeState(long statePtr)
public static int XXH3_freeState(XXH3State statePtr)
public static void nXXH3_copyState(long dst_state,
long srct_state)
public static int nXXH3_64bits_reset(long statePtr)
XXH3_64bits_reset(org.lwjgl.util.xxhash.XXH3State)public static int XXH3_64bits_reset(XXH3State statePtr)
Result will be equivalent to 3_64bits.
public static int nXXH3_64bits_reset_withSeed(long statePtr,
long seed)
XXH3_64bits_reset_withSeed(org.lwjgl.util.xxhash.XXH3State, long)public static int XXH3_64bits_reset_withSeed(XXH3State statePtr, long seed)
seed, and store it into state.
Digest will be equivalent to 3_64bits_withSeed.
public static int nXXH3_64bits_reset_withSecret(long statePtr,
long secret,
long secretSize)
public static int XXH3_64bits_reset_withSecret(XXH3State statePtr, java.nio.ByteBuffer secret)
secret is referenced, and must outlive the hash streaming session.
secretSize must be ≥ 3_SECRET_SIZE_MIN.
public static int nXXH3_64bits_update(long statePtr,
long input,
long length)
public static int XXH3_64bits_update(XXH3State statePtr, java.nio.ByteBuffer input)
public static long nXXH3_64bits_digest(long statePtr)
public static long XXH3_64bits_digest(XXH3State statePtr)
public static void nXXH128(long data,
long len,
long seed,
long __result)
public static XXH128Hash XXH128(java.nio.ByteBuffer data, long seed, XXH128Hash __result)
public static void nXXH3_128bits(long data,
long len,
long __result)
public static XXH128Hash XXH3_128bits(java.nio.ByteBuffer data, XXH128Hash __result)
public static void nXXH3_128bits_withSeed(long data,
long len,
long seed,
long __result)
public static XXH128Hash XXH3_128bits_withSeed(java.nio.ByteBuffer data, long seed, XXH128Hash __result)
public static void nXXH3_128bits_withSecret(long data,
long len,
long secret,
long secretSize,
long __result)
public static XXH128Hash XXH3_128bits_withSecret(java.nio.ByteBuffer data, java.nio.ByteBuffer secret, XXH128Hash __result)
public static int nXXH3_128bits_reset(long statePtr)
public static int XXH3_128bits_reset(XXH3State statePtr)
public static int nXXH3_128bits_reset_withSeed(long statePtr,
long seed)
public static int XXH3_128bits_reset_withSeed(XXH3State statePtr, long seed)
public static int nXXH3_128bits_reset_withSecret(long statePtr,
long secret,
long secretSize)
public static int XXH3_128bits_reset_withSecret(XXH3State statePtr, java.nio.ByteBuffer secret)
public static int nXXH3_128bits_update(long statePtr,
long input,
long length)
public static int XXH3_128bits_update(XXH3State statePtr, java.nio.ByteBuffer input)
public static void nXXH3_128bits_digest(long statePtr,
long __result)
public static XXH128Hash XXH3_128bits_digest(XXH3State statePtr, XXH128Hash __result)
public static int nXXH128_isEqual(long h1,
long h2)
public static boolean XXH128_isEqual(XXH128Hash h1, XXH128Hash h2)
public static int nXXH128_cmp(long h128_1,
long h128_2)
XXH128_cmp(java.nio.ByteBuffer, java.nio.ByteBuffer)public static int XXH128_cmp(java.nio.ByteBuffer h128_1,
java.nio.ByteBuffer h128_2)
qsort().public static void nXXH128_canonicalFromHash(long dst,
long hash)
public static void XXH128_canonicalFromHash(XXH128Canonical dst, XXH128Hash hash)
public static void nXXH128_hashFromCanonical(long src,
long __result)
public static XXH128Hash XXH128_hashFromCanonical(XXH128Canonical src, XXH128Hash __result)
Copyright LWJGL. All Rights Reserved. License terms.