org.apache.datasketches.memory.MurmurHash3 Maven / Gradle / Ivy
Show all versions of datasketches-memory Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.datasketches.memory;
import org.apache.datasketches.memory.internal.MurmurHash3v3;
import jdk.incubator.foreign.MemorySegment;
/**
* 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 version 3 of the implementation leverages the jdk.incubator.foreign package of JDK-17 in place of
* the Unsafe class.
*
* @author Lee Rhodes
*/
public final class MurmurHash3 {
//Provided for backward compatibility
/**
* Returns a 128-bit hash of the input.
* Provided for compatibility with older version of MurmurHash3,
* but empty or null input now throws IllegalArgumentException.
* @param in long array
* @param seed A long valued seed.
* @return the hash
*/
public static long[] hash(
final long[] in,
final long seed) {
return MurmurHash3v3.hash(in, 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.
* @param in int array
* @param seed A long valued seed.
* @return the hash
*/
public static long[] hash(
final int[] in,
final long seed) {
return MurmurHash3v3.hash(in, 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.
* @param in char array
* @param seed A long valued seed.
* @return the hash
*/
public static long[] hash(
final char[] in,
final long seed) {
return MurmurHash3v3.hash(in, 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.
* @param in byte array
* @param seed A long valued seed.
* @return the hash
*/
public static long[] hash(
final byte[] in,
final long seed) {
return MurmurHash3v3.hash(in, seed);
}
//Single primitive inputs
/**
* Returns a 128-bit hash of the input.
* Note the entropy of the resulting hash cannot be more than 64 bits.
* @param in a long
* @param seed A long valued seed.
* @param hashOut A long array of size 2
* @return the hash
*/
public static long[] hash(
final long in,
final long seed,
final long[] hashOut) {
return MurmurHash3v3.hash(in, seed, hashOut);
}
/**
* Returns a 128-bit hash of the input.
* Note the entropy of the resulting hash cannot be more than 64 bits.
* @param in a double
* @param seed A long valued seed.
* @param hashOut A long array of size 2
* @return the hash
*/
public static long[] hash(
final double in,
final long seed,
final long[] hashOut) {
return MurmurHash3v3.hash(in, seed, hashOut);
}
/**
* Returns a 128-bit hash of the input.
* An empty or null input throws IllegalArgumentException.
* @param in a String
* @param seed A long valued seed.
* @param hashOut A long array of size 2
* @return the hash
*/
public static long[] hash(
final String in,
final long seed,
final long[] hashOut) {
return MurmurHash3v3.hash(in, seed, hashOut);
}
//The main API calls
/**
* Returns a 128-bit hash of the input as a long array of size 2.
*
* @param mem The input on-heap Memory. Must be non-null and non-empty.
* @param offsetBytes the starting point within Memory.
* @param lengthBytes the total number of bytes to be hashed.
* @param seed A long valued seed.
* @param hashOut the size 2 long array for the resulting 128-bit hash
* @return the hash.
*/
public static long[] hash(
final Memory mem,
final long offsetBytes,
final long lengthBytes,
final long seed,
final long[] hashOut) {
return MurmurHash3v3.hash(mem, offsetBytes, lengthBytes, seed, hashOut);
}
/**
* Returns a 128-bit hash of the input as a long array of size 2.
*
* @param seg The input MemorySegment. Must be non-null and non-empty.
* @param offsetBytes the starting point within Memory.
* @param lengthBytes the total number of bytes to be hashed.
* @param seed A long valued seed.
* @param hashOut the size 2 long array for the resulting 128-bit hash
* @return the hash.
*/
public static long[] hash(
final MemorySegment seg,
final long offsetBytes,
final long lengthBytes,
final long seed,
final long[] hashOut) {
return MurmurHash3v3.hash(seg, offsetBytes, lengthBytes, seed, hashOut);
}
}