net.openhft.hashing

Class LongHashFunction

java.lang.Object

net.openhft.hashing.LongHashFunction

All Implemented Interfaces:

Serializable

public abstract class LongHashFunction
extends Object
implements Serializable

Hash function producing long-valued result from byte sequences of any length and a plenty of different sources which "feels like byte sequences". Except hashBytes(byte[]), hashBytes(ByteBuffer) (with their "sliced" versions) and hashMemory(long, long) methods, which actually accept byte sequences, notion of byte sequence is defined as follows:

• For methods accepting arrays of Java primitives, Strings and StringBuilders, byte sequence is how the input's bytes are actually lay in memory.
• For methods accepting single primitive values, byte sequence is how this primitive would be put into memory with native byte order, or equivalently, hashXxx(primitive) has always the same result as hashXxxs(new xxx[] {primitive}), where "xxx" is any Java primitive type name.
• For hash(Object, Access, long, long) method byte sequence abstraction is defined by the given Access strategy to the given object.

Hash function implementation could either produce equal results for equal input on platforms with different ByteOrder, favoring one byte order in terms of performance, or different results, but performing equally good. This choice should be explicitly documented for all LongHashFunction implementations.

Subclassing

To implement a specific hash function algorithm, this class should be subclassed. Only methods that accept single primitives, hashVoid() and hash(Object, Access, long, long) should be implemented; other have default implementations which in the end delegate to hash(Object, Access, long, long) abstract method.

Notes about how exactly methods with default implementations are implemented in doc comments are given for information and could be changed at any moment. However, it could hardly cause any issues with subclassing, except probably little performance degradation. Methods documented as "shortcuts" could either delegate to the referenced method or delegate directly to the method to which the referenced method delegates.

LongHashFunction implementations shouldn't assume that Access strategies do defensive checks, and access only bytes within the requested range.

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LongHashFunction() Constructor for use in subclasses.

Method Summary

Methods

Modifier and Type	Method and Description
static LongHashFunction	city_1_1() Returns a hash function implementing CityHash64 algorithm, version 1.1 without seed values.
static LongHashFunction	city_1_1(long seed) Returns a hash function implementing CityHash64 algorithm, version 1.1 using the given seed value.
static LongHashFunction	city_1_1(long seed0, long seed1) Returns a hash function implementing CityHash64 algorithm, version 1.1 using the two given seed values.
abstract <T> long	hash(T input, Access<T> access, long off, long len) Returns the hash code for len continuous bytes of the given input object, starting from the given offset.
long	hashBoolean(boolean input) Shortcut for hashBooleans(new boolean[] {input}).
long	hashBooleans(boolean[] input) Shortcut for hashBooleans(input, 0, input.length).
long	hashBooleans(boolean[] input, int off, int len) Returns the hash code for the specified subsequence of the given boolean array.
abstract long	hashByte(byte input) Returns the hash code for the given byte value.
long	hashBytes(byte[] input) Shortcut for hashBytes(input, 0, input.length).
long	hashBytes(byte[] input, int off, int len) Returns the hash code for the specified subsequence of the given byte array.
long	hashBytes(ByteBuffer input) Shortcut for hashBytes(input, input.position(), input.remaining()).
long	hashBytes(ByteBuffer input, int off, int len) Returns the hash code for the specified subsequence of the given ByteBuffer.
abstract long	hashChar(char input) Returns the hash code for the given char value; this method is consistent with LongHashFunction methods that accept sequences of bytes, assuming the input value is interpreted in native byte order.
long	hashChars(char[] input) Shortcut for hashChars(input, 0, input.length).
long	hashChars(char[] input, int off, int len) Returns the hash code for bytes, as they lay in memory, of the specified subsequence of the given char array.
long	hashChars(String input) Shortcut for hashChars(input, 0, input.length()).
long	hashChars(StringBuilder input) Shortcut for {@link #hashChars(StringBuilder, int, int) hashChars(input, 0.
long	hashChars(StringBuilder input, int off, int len) Returns the hash code for bytes of the specified subsequence of the given StringBuilder's underlying char array.
long	hashChars(String input, int off, int len) Returns the hash code for bytes of the specified subsequence of the given String's underlying char array.
abstract long	hashInt(int input) Returns the hash code for the given int value; this method is consistent with LongHashFunction methods that accept sequences of bytes, assuming the input value is interpreted in native byte order.
long	hashInts(int[] input) Shortcut for hashInts(input, 0, input.length).
long	hashInts(int[] input, int off, int len) Returns the hash code for bytes, as they lay in memory, of the specified subsequence of the given int array.
abstract long	hashLong(long input) Returns the hash code for the given long value; this method is consistent with LongHashFunction methods that accept sequences of bytes, assuming the input value is interpreted in native byte order.
long	hashLongs(long[] input) Shortcut for hashLongs(input, 0, input.length).
long	hashLongs(long[] input, int off, int len) Returns the hash code for bytes, as they lay in memory, of the specified subsequence of the given long array.
long	hashMemory(long address, long len) Returns the hash code of bytes of the wild memory from the given address.
abstract long	hashShort(short input) Returns the hash code for the given short value; this method is consistent with LongHashFunction methods that accept sequences of bytes, assuming the input value is interpreted in native byte order.
long	hashShorts(short[] input) Shortcut for hashShorts(input, 0, input.length).
long	hashShorts(short[] input, int off, int len) Returns the hash code for bytes, as they lay in memory, of the specified subsequence of the given short array.
abstract long	hashVoid() Returns the hash code for the empty (zero-length) bytes sequence, for example hashBytes(new byte[0]).
static LongHashFunction	murmur_3() Returns a hash function implementing MurmurHash3 algorithm without seed values.
static LongHashFunction	murmur_3(long seed) Returns a hash function implementing MurmurHash3 algorithm with the given seed value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LongHashFunction

protected LongHashFunction()

Constructor for use in subclasses.

Method Detail

city_1_1

public static LongHashFunction city_1_1()

Returns a hash function implementing CityHash64 algorithm, version 1.1 without seed values. This implementation produce equal results for equal input on platforms with different ByteOrder, but is slower on big-endian platforms than on little-endian.

See Also:

city_1_1(long), city_1_1(long, long)

city_1_1

public static LongHashFunction city_1_1(long seed)

Returns a hash function implementing CityHash64 algorithm, version 1.1 using the given seed value. This implementation produce equal results for equal input on platforms with different ByteOrder, but is slower on big-endian platforms than on little-endian.

See Also:

city_1_1(), city_1_1(long, long)

city_1_1

public static LongHashFunction city_1_1(long seed0,
                        long seed1)

Returns a hash function implementing CityHash64 algorithm, version 1.1 using the two given seed values. This implementation produce equal results for equal input on platforms with different ByteOrder, but is slower on big-endian platforms than on little-endian.

See Also:

city_1_1(), city_1_1(long)

murmur_3

public static LongHashFunction murmur_3()

Returns a hash function implementing MurmurHash3 algorithm without seed values. This implementation produce equal results for equal input on platforms with different ByteOrder, but is slower on big-endian platforms than on little-endian.

See Also:

murmur_3(long)

murmur_3

public static LongHashFunction murmur_3(long seed)

Returns a hash function implementing MurmurHash3 algorithm with the given seed value. This implementation produce equal results for equal input on platforms with different ByteOrder, but is slower on big-endian platforms than on little-endian.

See Also:

murmur_3()

hashLong

public abstract long hashLong(long input)

Returns the hash code for the given long value; this method is consistent with LongHashFunction methods that accept sequences of bytes, assuming the input value is interpreted in native byte order. For example, the result of hashLong(v) call is identical to the result of hashLongs(new long[] {v}) call for any long value.

hashInt

public abstract long hashInt(int input)

Returns the hash code for the given int value; this method is consistent with LongHashFunction methods that accept sequences of bytes, assuming the input value is interpreted in native byte order. For example, the result of hashInt(v) call is identical to the result of hashInts(new int[] {v}) call for any int value.

hashShort

public abstract long hashShort(short input)

Returns the hash code for the given short value; this method is consistent with LongHashFunction methods that accept sequences of bytes, assuming the input value is interpreted in native byte order. For example, the result of hashShort(v) call is identical to the result of hashShorts(new short[] {v}) call for any short value. As a consequence, hashShort(v) call produce always the same result as hashChar((char) v).

hashChar

public abstract long hashChar(char input)

Returns the hash code for the given char value; this method is consistent with LongHashFunction methods that accept sequences of bytes, assuming the input value is interpreted in native byte order. For example, the result of hashChar(v) call is identical to the result of hashChars(new char[] {v}) call for any char value. As a consequence, hashChar(v) call produce always the same result as hashShort((short) v).

hashByte

public abstract long hashByte(byte input)

Returns the hash code for the given byte value. This method is consistent with LongHashFunction methods that accept sequences of bytes. For example, the result of hashByte(v) call is identical to the result of hashBytes(new byte[] {v}) call for any byte value.

hashVoid

public abstract long hashVoid()

Returns the hash code for the empty (zero-length) bytes sequence, for example hashBytes(new byte[0]).

hash

public abstract <T> long hash(T input,
            Access<T> access,
            long off,
            long len)

Returns the hash code for len continuous bytes of the given input object, starting from the given offset. The abstraction of input as ordered byte sequence and "offset within the input" is defined by the given access strategy.

This method doesn't promise to throw a RuntimeException if [off, off + len - 1] subsequence exceeds the bounds of the bytes sequence, defined by access strategy for the given input, so use this method with caution.

Type Parameters:

T - the type of the input

Parameters:

input - the object to read bytes from

access - access which defines the abstraction of the given input as ordered byte sequence

off - offset to the first byte of the subsequence to hash

len - length of the subsequence to hash

Returns:

hash code for the specified bytes subsequence

hashBoolean

public long hashBoolean(boolean input)

Shortcut for hashBooleans(new boolean[] {input}). Note that this is not necessarily equal to hashByte(input ? (byte) 1 : (byte) 0), because booleans could be stored differently in this JVM.

hashBooleans

public long hashBooleans(@NotNull
                boolean[] input)

Shortcut for hashBooleans(input, 0, input.length).

hashBooleans

public long hashBooleans(@NotNull
                boolean[] input,
                int off,
                int len)

Returns the hash code for the specified subsequence of the given boolean array.

Default implementation delegates to hash(Object, Access, long, long) method using unsafe Access.

Parameters:

input - the array to read data from

off - index of the first boolean in the subsequence to hash

len - length of the subsequence to hash

Returns:

hash code for the specified subsequence

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.length or len < 0

hashBytes

public long hashBytes(@NotNull
             byte[] input)

Shortcut for hashBytes(input, 0, input.length).

hashBytes

public long hashBytes(@NotNull
             byte[] input,
             int off,
             int len)

Returns the hash code for the specified subsequence of the given byte array.

Default implementation delegates to hash(Object, Access, long, long) method using unsafe Access.

Parameters:

input - the array to read bytes from

off - index of the first byte in the subsequence to hash

len - length of the subsequence to hash

Returns:

hash code for the specified subsequence

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.length or len < 0

hashBytes

public long hashBytes(ByteBuffer input)

Shortcut for hashBytes(input, input.position(), input.remaining()).

hashBytes

public long hashBytes(@NotNull
             ByteBuffer input,
             int off,
             int len)

Returns the hash code for the specified subsequence of the given ByteBuffer.

This method doesn't alter the state (mark, position, limit or order) of the given ByteBuffer.

Default implementation delegates to hash(Object, Access, long, long) method using Access.toByteBuffer().

Parameters:

input - the buffer to read bytes from

off - index of the first byte in the subsequence to hash

len - length of the subsequence to hash

Returns:

hash code for the specified subsequence

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.capacity() or len < 0

hashMemory

public long hashMemory(long address,
              long len)

Returns the hash code of bytes of the wild memory from the given address. Use with caution.

Default implementation delegates to hash(Object, Access, long, long) method using unsafe Access.

Parameters:

address - the address of the first byte to hash

len - length of the byte sequence to hash

Returns:

hash code for the specified byte sequence

hashChars

public long hashChars(@NotNull
             char[] input)

Shortcut for hashChars(input, 0, input.length).

hashChars

public long hashChars(@NotNull
             char[] input,
             int off,
             int len)

Returns the hash code for bytes, as they lay in memory, of the specified subsequence of the given char array.

Default implementation delegates to hash(Object, Access, long, long) method using unsafe Access.

Parameters:

input - the array to read data from

off - index of the first char in the subsequence to hash

len - length of the subsequence to hash, in chars (i. e. the length of the bytes sequence to hash is len * 2L)

Returns:

hash code for the specified subsequence

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.length or len < 0

hashChars

public long hashChars(@NotNull
             String input)

Shortcut for hashChars(input, 0, input.length()).

hashChars

public long hashChars(@NotNull
             String input,
             int off,
             int len)

Returns the hash code for bytes of the specified subsequence of the given String's underlying char array.

Default implementation could either delegate to hash(Object, Access, long, long) using Access.toNativeCharSequence(), or to hashChars(char[], int, int).

Parameters:

input - the string which bytes to hash

off - index of the first char in the subsequence to hash

len - length of the subsequence to hash, in chars (i. e. the length of the bytes sequence to hash is len * 2L)

Returns:

the hash code of the given String's bytes

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.length() or len < 0

hashChars

public long hashChars(@NotNull
             StringBuilder input)

Shortcut for hashChars(input, 0. input.length()).

hashChars

public long hashChars(@NotNull
             StringBuilder input,
             int off,
             int len)

Returns the hash code for bytes of the specified subsequence of the given StringBuilder's underlying char array.

Default implementation could either delegate to hash(Object, Access, long, long) using Access.toNativeCharSequence(), or to hashChars(char[], int, int).

Parameters:

input - the string builder which bytes to hash

off - index of the first char in the subsequence to hash

len - length of the subsequence to hash, in chars (i. e. the length of the bytes sequence to hash is len * 2L)

Returns:

the hash code of the given String's bytes

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.length() or len < 0

hashShorts

public long hashShorts(@NotNull
              short[] input)

Shortcut for hashShorts(input, 0, input.length).

hashShorts

public long hashShorts(@NotNull
              short[] input,
              int off,
              int len)

Returns the hash code for bytes, as they lay in memory, of the specified subsequence of the given short array.

Default implementation delegates to hash(Object, Access, long, long) method using unsafe Access.

Parameters:

input - the array to read data from

off - index of the first short in the subsequence to hash

len - length of the subsequence to hash, in shorts (i. e. the length of the bytes sequence to hash is len * 2L)

Returns:

hash code for the specified subsequence

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.length or len < 0

hashInts

public long hashInts(@NotNull
            int[] input)

Shortcut for hashInts(input, 0, input.length).

hashInts

public long hashInts(@NotNull
            int[] input,
            int off,
            int len)

Returns the hash code for bytes, as they lay in memory, of the specified subsequence of the given int array.

Default implementation delegates to hash(Object, Access, long, long) method using unsafe Access.

Parameters:

input - the array to read data from

off - index of the first int in the subsequence to hash

len - length of the subsequence to hash, in ints (i. e. the length of the bytes sequence to hash is len * 4L)

Returns:

hash code for the specified subsequence

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.length or len < 0

hashLongs

public long hashLongs(@NotNull
             long[] input)

Shortcut for hashLongs(input, 0, input.length).

hashLongs

public long hashLongs(@NotNull
             long[] input,
             int off,
             int len)

Returns the hash code for bytes, as they lay in memory, of the specified subsequence of the given long array.

Default implementation delegates to hash(Object, Access, long, long) method using unsafe Access.

Parameters:

input - the array to read data from

off - index of the first long in the subsequence to hash

len - length of the subsequence to hash, in longs (i. e. the length of the bytes sequence to hash is len * 8L)

Returns:

hash code for the specified subsequence

Throws:

IndexOutOfBoundsException - if off < 0 or off + len > input.length or len < 0