net.openhft.chronicle.algo.hashing

Class LongHashFunction

java.lang.Object

net.openhft.chronicle.algo.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, ReadAccess, long, long) method byte sequence abstraction is defined by the given ReadAccess 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, ReadAccess, long, long) should be implemented; other have default implementations which in the end delegate to hash(Object, ReadAccess, 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 ReadAccess 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

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.
<S,T,A extends ReadAccess<T>> long	hash(Accessor<S,T,A> accessor, S source, long off, long len)
abstract <T> long	hash(T input, ReadAccess<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(@NotNull boolean[] input) Shortcut for hashBooleans(input, 0, input.length).
long	hashBooleans(@NotNull 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(@NotNull byte[] input) Shortcut for hashBytes(input, 0, input.length).
long	hashBytes(@NotNull 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(@NotNull 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(@NotNull char[] input) Shortcut for hashChars(input, 0, input.length).
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.
long	hashChars(@NotNull String input) Shortcut for hashChars(input, 0, input.length()).
long	hashChars(@NotNull StringBuilder input) Shortcut for hashChars(input, 0, input.length()).
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.
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.
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(@NotNull int[] input) Shortcut for hashInts(input, 0, input.length).
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.
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(@NotNull long[] input) Shortcut for hashLongs(input, 0, input.length).
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.
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(@NotNull short[] input) Shortcut for hashShorts(input, 0, input.length).
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.
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.
static LongHashFunction	xx_r39() Returns a hash function implementing xxHash algorithm, release 39 without seed value (0 is used as default seed value).
static LongHashFunction	xx_r39(long seed) Returns a hash function implementing xxHash algorithm, release 39 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)

xx_r39

public static LongHashFunction xx_r39()

Returns a hash function implementing xxHash algorithm, release 39 without seed value (0 is used as default 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.

Note: implementation is fully compatible with r40

See Also:

xx_r39(long)

xx_r39

public static LongHashFunction xx_r39(long seed)

Returns a hash function implementing xxHash algorithm, release 39 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.

Note: implementation is fully compatible with r40

See Also:

xx_r39()

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,
                              ReadAccess<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

hash

public <S,T,A extends ReadAccess<T>> long hash(Accessor<S,T,A> accessor,
                                               S source,
                                               long off,
                                               long len)

hashBoolean

public long hashBoolean(boolean input)

Shortcut for hashBooleans(new boolean[] {input}).

hashBooleans

public long hashBooleans(@NotNull
                         @NotNull boolean[] input)

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

hashBooleans

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

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

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
                      @NotNull byte[] input)

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

hashBytes

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

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

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

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.

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
                      @NotNull char[] input)

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

hashChars

public long hashChars(@NotNull
                      @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.

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
                      @NotNull String input)

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

hashChars

public long hashChars(@NotNull
                      @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.

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
                      @NotNull StringBuilder input)

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

hashChars

public long hashChars(@NotNull
                      @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.

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
                       @NotNull short[] input)

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

hashShorts

public long hashShorts(@NotNull
                       @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.

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
                     @NotNull int[] input)

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

hashInts

public long hashInts(@NotNull
                     @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.

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
                      @NotNull long[] input)

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

hashLongs

public long hashLongs(@NotNull
                      @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.

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