Class XXHash


  • public class XXHash
    extends java.lang.Object
    Native bindings to xxhash.

    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

    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. For example, results produced by v0.7.1 are not comparable with results from v0.7.0 . It's nonetheless possible to use XXH3 for ephemeral data (local sessions), but avoid storing values in long-term storage for later re-use.

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

    • Method Detail

      • nXXH32

        public static int nXXH32​(long input,
                                 long length,
                                 int seed)
        Parameters:
        length - the number of bytes stored at memory address input
      • XXH32

        public static int XXH32​(java.nio.ByteBuffer input,
                                int seed)
        Calculates the 32-bits hash of sequence length bytes stored at memory address input.
        Parameters:
        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 predictably
      • nXXH32_createState

        public static long nXXH32_createState()
        Unsafe version of: XXH32_createState()
      • XXH32_createState

        @Nullable
        public static XXH32State XXH32_createState()
        Creates memory for 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.

      • XXH32_freeState

        public static int XXH32_freeState​(XXH32State statePtr)
        Frees the specified XXH32_state_t.
        Parameters:
        statePtr - the state to free
      • nXXH32_copyState

        public static void nXXH32_copyState​(long dst_state,
                                            long src_state)
      • XXH32_copyState

        public static void XXH32_copyState​(XXH32State dst_state,
                                           XXH32State src_state)
      • XXH32_reset

        public static int XXH32_reset​(XXH32State statePtr,
                                      int seed)
        Resets the specified XXH32_state_t.
        Parameters:
        statePtr - the XXH32_state_t to reset
        seed - the seed that can be used to alter the hashing result predictably
      • XXH32_update

        public static int XXH32_update​(XXH32State statePtr,
                                       java.nio.ByteBuffer input)
        These functions generate the xxHash of an input provided in multiple segments. Note that, for small input, they are slower than single-call functions, due to state management. For small input, prefer 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 hashes later on, by calling again 32_digest.

        When done, free XXH state space.

        Parameters:
        statePtr - the XXH32_state_t to use
        input - the bytes to hash. The memory between input & input+length must be valid (allocated and read-accessible).
      • XXH32_digest

        public static int XXH32_digest​(XXH32State statePtr)
        Returns the final 32-bits hash of the specified XXH32_state_t.
        Parameters:
        statePtr - the XXH32_state_t to use
      • XXH32_canonicalFromHash

        public static void XXH32_canonicalFromHash​(XXH32Canonical dst,
                                                   int hash)
        Default result type for XXH functions are primitive unsigned 32 and 64 bits.

        The canonical representation uses human-readable write convention, aka big-endian (large digits first). These functions allow transformation of hash result into and from its canonical format. This way, hash values can be written into a file / memory, remaining comparable across different systems.

        Parameters:
        dst - the destination canonical representation
        hash - the source hash
      • XXH32_hashFromCanonical

        public static int XXH32_hashFromCanonical​(XXH32Canonical src)
        Transforms the specified canonical representation to a primitive value.
        Parameters:
        src - the source canonical representation
      • nXXH64

        public static long nXXH64​(long input,
                                  long length,
                                  long seed)
        Parameters:
        length - the number of bytes stored at memory address input
      • XXH64

        public static long XXH64​(java.nio.ByteBuffer input,
                                 long seed)
        64-bit version of 32.

        This function runs 2x faster on 64-bits systems, but slower on 32-bits systems.

        Parameters:
        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 predictably
      • nXXH64_createState

        public static long nXXH64_createState()
        Unsafe version of: XXH64_createState()
      • XXH64_freeState

        public static int XXH64_freeState​(XXH64State statePtr)
        64-bit version of 32_freeState.
        Parameters:
        statePtr - the state to free
      • nXXH64_copyState

        public static void nXXH64_copyState​(long dst_state,
                                            long src_state)
      • XXH64_copyState

        public static void XXH64_copyState​(XXH64State dst_state,
                                           XXH64State src_state)
      • XXH64_reset

        public static int XXH64_reset​(XXH64State statePtr,
                                      long seed)
        64-bit version of 32_reset.
        Parameters:
        statePtr - the XXH64_state_t to reset
        seed - the seed that can be used to alter the hashing result predictably
      • XXH64_update

        public static int XXH64_update​(XXH64State statePtr,
                                       java.nio.ByteBuffer input)
        64-bit version of 32_update.
        Parameters:
        statePtr - the XXH64_state_t to use
        input - the bytes to hash. The memory between input & input+length must be valid (allocated and read-accessible).
      • XXH64_digest

        public static long XXH64_digest​(XXH64State statePtr)
        64-bit version of 32_digest.
        Parameters:
        statePtr - the XXH64_state_t to use
      • XXH64_canonicalFromHash

        public static void XXH64_canonicalFromHash​(XXH64Canonical dst,
                                                   long hash)
        64-bit version of 32_canonicalFromHash.
        Parameters:
        dst - the destination canonical representation
        hash - the source hash
      • XXH64_hashFromCanonical

        public static long XXH64_hashFromCanonical​(XXH64Canonical src)
        64-bit version of 32_hashFromCanonical.
        Parameters:
        src - the source canonical representation
      • XXH3_64bits

        public static long XXH3_64bits​(java.nio.ByteBuffer data)
        Default 64-bit variant, using default secret and default seed of 0.

        It's the fastest variant.

      • XXH3_64bits_withSecret

        public 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. This makes it more difficult for an external actor to prepare an intentional collision.

        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.

      • XXH3_64bits_withSeed

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

        While this operation is decently fast, note that it's not completely free. Note seed==0 produces same results as 3_64bits.

      • nXXH3_createState

        public static long nXXH3_createState()
      • XXH3_createState

        @Nullable
        public static XXH3State XXH3_createState()
      • nXXH3_freeState

        public static int nXXH3_freeState​(long statePtr)
      • XXH3_freeState

        public static int XXH3_freeState​(XXH3State statePtr)
      • nXXH3_copyState

        public static void nXXH3_copyState​(long dst_state,
                                           long srct_state)
      • XXH3_copyState

        public static void XXH3_copyState​(XXH3State dst_state,
                                          XXH3State srct_state)
      • XXH3_64bits_reset

        public static int XXH3_64bits_reset​(XXH3State statePtr)
        Initialize with default parameters.

        Result will be equivalent to 3_64bits.

      • XXH3_64bits_reset_withSeed

        public static int XXH3_64bits_reset_withSeed​(XXH3State statePtr,
                                                     long seed)
        Generate a custom secret from seed, and store it into state.

        Digest will be equivalent to 3_64bits_withSeed.

      • XXH3_64bits_reset_withSecret

        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.

      • nXXH3_64bits_update

        public static int nXXH3_64bits_update​(long statePtr,
                                              long input,
                                              long length)
      • XXH3_64bits_update

        public static int XXH3_64bits_update​(XXH3State statePtr,
                                             java.nio.ByteBuffer input)
      • nXXH3_64bits_digest

        public static long nXXH3_64bits_digest​(long statePtr)
      • XXH3_64bits_digest

        public static long XXH3_64bits_digest​(XXH3State statePtr)
      • nXXH128

        public static void nXXH128​(long data,
                                   long len,
                                   long seed,
                                   long __result)
      • XXH128

        public static XXH128Hash XXH128​(java.nio.ByteBuffer data,
                                        long seed,
                                        XXH128Hash __result)
      • nXXH3_128bits

        public static void nXXH3_128bits​(long data,
                                         long len,
                                         long __result)
      • XXH3_128bits

        public static XXH128Hash XXH3_128bits​(java.nio.ByteBuffer data,
                                              XXH128Hash __result)
      • nXXH3_128bits_withSeed

        public static void nXXH3_128bits_withSeed​(long data,
                                                  long len,
                                                  long seed,
                                                  long __result)
      • XXH3_128bits_withSeed

        public static XXH128Hash XXH3_128bits_withSeed​(java.nio.ByteBuffer data,
                                                       long seed,
                                                       XXH128Hash __result)
      • nXXH3_128bits_withSecret

        public static void nXXH3_128bits_withSecret​(long data,
                                                    long len,
                                                    long secret,
                                                    long secretSize,
                                                    long __result)
      • XXH3_128bits_withSecret

        public static XXH128Hash XXH3_128bits_withSecret​(java.nio.ByteBuffer data,
                                                         java.nio.ByteBuffer secret,
                                                         XXH128Hash __result)
      • nXXH3_128bits_reset

        public static int nXXH3_128bits_reset​(long statePtr)
      • XXH3_128bits_reset

        public static int XXH3_128bits_reset​(XXH3State statePtr)
      • nXXH3_128bits_reset_withSeed

        public static int nXXH3_128bits_reset_withSeed​(long statePtr,
                                                       long seed)
      • XXH3_128bits_reset_withSeed

        public static int XXH3_128bits_reset_withSeed​(XXH3State statePtr,
                                                      long seed)
      • nXXH3_128bits_reset_withSecret

        public static int nXXH3_128bits_reset_withSecret​(long statePtr,
                                                         long secret,
                                                         long secretSize)
      • XXH3_128bits_reset_withSecret

        public static int XXH3_128bits_reset_withSecret​(XXH3State statePtr,
                                                        java.nio.ByteBuffer secret)
      • nXXH3_128bits_update

        public static int nXXH3_128bits_update​(long statePtr,
                                               long input,
                                               long length)
      • XXH3_128bits_update

        public static int XXH3_128bits_update​(XXH3State statePtr,
                                              java.nio.ByteBuffer input)
      • nXXH3_128bits_digest

        public static void nXXH3_128bits_digest​(long statePtr,
                                                long __result)
      • XXH128_isEqual

        public static boolean XXH128_isEqual​(XXH128Hash h1,
                                             XXH128Hash h2)
        Returns 1 if equal, 0 if different.
      • XXH128_cmp

        public static int XXH128_cmp​(java.nio.ByteBuffer h128_1,
                                     java.nio.ByteBuffer h128_2)
        This comparator is compatible with stdlib's qsort().
      • nXXH128_canonicalFromHash

        public static void nXXH128_canonicalFromHash​(long dst,
                                                     long hash)
      • nXXH128_hashFromCanonical

        public static void nXXH128_hashFromCanonical​(long src,
                                                     long __result)