Package org.apache.datasketches.hash

# Class MurmurHash3FFM21

java.lang.Object
org.apache.datasketches.hash.MurmurHash3FFM21

public final class MurmurHash3FFM21 extends Object
`MurmurHash3FFM21` relies on preview features of the Java platform:

- `MurmurHash3FFM21` refers to one or more preview APIs: `MemorySegment`.

Programs can only use `MurmurHash3FFM21` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
The MurmurHash3 is a fast, non-cryptographic, 128-bit hash function that has excellent avalanche and 2-way bit independence properties.

Austin Appleby's C++ MurmurHash3_x64_128(...), final revision 150, which is in the Public Domain, was the inspiration for this implementation in Java.

This implementation of the MurmurHash3 allows hashing of a block of on-heap Memory defined by an offset and length. The calling API also allows the user to supply the small output array of two longs, so that the entire hash function is static and free of object allocations.

This implementation produces exactly the same hash result as the MurmurHash3 function in datasketches-java given compatible inputs.

This FFM21 version of the implementation leverages the java.lang.foreign package (FFM) of JDK-21 in place of the Unsafe class.

Author:
  Lee Rhodes

## Method Summary

Modifier and Type
Method
Description
`static long[]`
`hash(byte[] in, long seed)`
Returns a 128-bit hash of the input.
`static long[]`
`hash(char[] in, long seed)`
Returns a 128-bit hash of the input.
`static long[]`
`hash(double in, long seed, long[] hashOut)`
Returns a 128-bit hash of the input.
`static long[]`
`hash(int[] in, long seed)`
Returns a 128-bit hash of the input.
`static long[]`
`hash(long[] in, long seed)`
Returns a 128-bit hash of the input.
`static long[]`
`hash(long in, long seed, long[] hashOut)`
Returns a 128-bit hash of the input.
`static long[]`
`hash(MemorySegmentPREVIEW seg, long offsetBytes, long lengthBytes, long seed, long[] hashOut)`
Returns a 128-bit hash of the input as a long array of size 2.
`static long[]`
`hash(String in, long seed, long[] hashOut)`
Returns a 128-bit hash of the input.
`static long[]`
`hash(org.apache.datasketches.memory.Memory mem, long offsetBytes, long lengthBytes, long seed, long[] hashOut)`
Returns a 128-bit hash of the input as a long array of size 2.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Method Details

### hash

public static long[] hash(long[] in, long seed)
Returns a 128-bit hash of the input. Provided for compatibility with older version of MurmurHash3, but empty or null input now throws IllegalArgumentException.

Parameters:
  `in` - long array
  `seed` - A long valued seed.
Returns:
  the hash
Throws:
  `IllegalArgumentException` - if input is empty or null

### hash

public static long[] hash(int[] in, long seed)
Returns a 128-bit hash of the input. Provided for compatibility with older version of MurmurHash3, but empty or null input now throws IllegalArgumentException.

Parameters:
  `in` - int array
  `seed` - A long valued seed.
Returns:
  the hash
Throws:
  `IllegalArgumentException` - if input is empty or null

### hash

public static long[] hash(char[] in, long seed)
Returns a 128-bit hash of the input. Provided for compatibility with older version of MurmurHash3, but empty or null input now throws IllegalArgumentException.

Parameters:
  `in` - char array
  `seed` - A long valued seed.
Returns:
  the hash
Throws:
  `IllegalArgumentException` - if input is empty or null

### hash

public static long[] hash(byte[] in, long seed)
Returns a 128-bit hash of the input. Provided for compatibility with older version of MurmurHash3, but empty or null input now throws IllegalArgumentException.

Parameters:
  `in` - byte array
  `seed` - A long valued seed.
Returns:
  the hash
Throws:
  `IllegalArgumentException` - if input is empty or null

### hash

public static long[] hash(long in, long seed, long[] hashOut)
Returns a 128-bit hash of the input. Note the entropy of the resulting hash cannot be more than 64 bits.

Parameters:
  `in` - a long
  `seed` - A long valued seed.
  `hashOut` - A long array of size 2
Returns:
  the hash

### hash

public static long[] hash(double in, long seed, long[] hashOut)
Returns a 128-bit hash of the input. Note the entropy of the resulting hash cannot be more than 64 bits.

Parameters:
  `in` - a double
  `seed` - A long valued seed.
  `hashOut` - A long array of size 2
Returns:
  the hash

### hash

public static long[] hash(String in, long seed, long[] hashOut)
Returns a 128-bit hash of the input. An empty or null input throws IllegalArgumentException.

Parameters:
  `in` - a String
  `seed` - A long valued seed.
  `hashOut` - A long array of size 2
Returns:
  the hash
Throws:
  `IllegalArgumentException` - if input is empty or null

### hash

public static long[] hash(org.apache.datasketches.memory.Memory mem, long offsetBytes, long lengthBytes, long seed, long[] hashOut)
Returns a 128-bit hash of the input as a long array of size 2.

Parameters:
  `mem` - The input Memory. Must be non-null and non-empty, otherwise throws IllegalArgumentException.
  `offsetBytes` - the starting point within Memory.
  `lengthBytes` - the total number of bytes to be hashed.
  `seed` - A long valued seed.
  `hashOut` - the size 2 long array for the resulting 128-bit hash
Returns:
  the hash.

### hash

public static long[] hash(MemorySegmentPREVIEW seg, long offsetBytes, long lengthBytes, long seed, long[] hashOut)
Returns a 128-bit hash of the input as a long array of size 2.

Parameters:
  `seg` - The input MemorySegment. Must be non-null and non-empty, otherwise throws IllegalArgumentException.
  `offsetBytes` - the starting point within Memory.
  `lengthBytes` - the total number of bytes to be hashed.
  `seed` - A long valued seed.
  `hashOut` - the size 2 long array for the resulting 128-bit hash
Returns:
  the hash.
Throws:
  `IllegalArgumentException` - if input MemorySegment is empty