com.diffplug.common.hash

Class HashCode

java.lang.Object

com.diffplug.common.hash.HashCode

@Beta
public abstract class HashCode
extends Object

An immutable hash code of arbitrary bit length.

Since:

11.0

Method Summary

Modifier and Type	Method and Description
abstract byte[]	asBytes() Returns the value of this hash code as a byte array.
abstract int	asInt() Returns the first four bytes of this hashcode's bytes, converted to an int value in little-endian order.
abstract long	asLong() Returns the first eight bytes of this hashcode's bytes, converted to a long value in little-endian order.
abstract int	bits() Returns the number of bits in this hash code; a positive multiple of 8.
boolean	equals(Object object) Returns true if object is a HashCode instance with the identical byte representation to this hash code.
static HashCode	fromBytes(byte[] bytes) Creates a HashCode from a byte array.
static HashCode	fromInt(int hash) Creates a 32-bit HashCode representation of the given int value.
static HashCode	fromLong(long hash) Creates a 64-bit HashCode representation of the given long value.
static HashCode	fromString(String string) Creates a HashCode from a hexadecimal (base 16) encoded string.
int	hashCode() Returns a “Java hash code” for this HashCode instance; this is well-defined (so, for example, you can safely put HashCode instances into a HashSet) but is otherwise probably not what you want to use.
abstract long	padToLong() If this hashcode has enough bits, returns asLong(), otherwise returns a long value with asBytes() as the least-significant bytes and 0x00 as the remaining most-significant bytes.
String	toString() Returns a string containing each byte of asBytes(), in order, as a two-digit unsigned hexadecimal number in lower case.
int	writeBytesTo(byte[] dest, int offset, int maxLength) Copies bytes from this hash code into dest.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

bits

@CheckReturnValue
public abstract int bits()

Returns the number of bits in this hash code; a positive multiple of 8.

asInt

@CheckReturnValue
public abstract int asInt()

Returns the first four bytes of this hashcode's bytes, converted to an int value in little-endian order.

Throws:

IllegalStateException - if bits() < 32

asLong

@CheckReturnValue
public abstract long asLong()

Returns the first eight bytes of this hashcode's bytes, converted to a long value in little-endian order.

Throws:

IllegalStateException - if bits() < 64

padToLong

@CheckReturnValue
public abstract long padToLong()

If this hashcode has enough bits, returns asLong(), otherwise returns a long value with asBytes() as the least-significant bytes and 0x00 as the remaining most-significant bytes.

Since:

14.0 (since 11.0 as Hashing.padToLong(HashCode))

asBytes

@CheckReturnValue
public abstract byte[] asBytes()

Returns the value of this hash code as a byte array. The caller may modify the byte array; changes to it will not be reflected in this HashCode object or any other arrays returned by this method.

writeBytesTo

public int writeBytesTo(byte[] dest,
                        int offset,
                        int maxLength)

Copies bytes from this hash code into dest.

Parameters:

dest - the byte array into which the hash code will be written

offset - the start offset in the data

maxLength - the maximum number of bytes to write

Returns:

the number of bytes written to dest

Throws:

IndexOutOfBoundsException - if there is not enough room in dest

fromInt

@CheckReturnValue
public static HashCode fromInt(int hash)

Creates a 32-bit HashCode representation of the given int value. The underlying bytes are interpreted in little endian order.

Since:

15.0 (since 12.0 in HashCodes)

fromLong

@CheckReturnValue
public static HashCode fromLong(long hash)

Creates a 64-bit HashCode representation of the given long value. The underlying bytes are interpreted in little endian order.

Since:

15.0 (since 12.0 in HashCodes)

fromBytes

@CheckReturnValue
public static HashCode fromBytes(byte[] bytes)

Creates a HashCode from a byte array. The array is defensively copied to preserve the immutability contract of HashCode. The array cannot be empty.

Since:

15.0 (since 12.0 in HashCodes)

fromString

@CheckReturnValue
public static HashCode fromString(String string)

Creates a HashCode from a hexadecimal (base 16) encoded string. The string must be at least 2 characters long, and contain only valid, lower-cased hexadecimal characters.

This method accepts the exact format generated by toString(). If you require more lenient base 16 decoding, please use BaseEncoding.decode(java.lang.CharSequence) (and pass the result to fromBytes(byte[])).

Since:

15.0

equals

public final boolean equals(@Nullable
                            Object object)

Returns true if object is a HashCode instance with the identical byte representation to this hash code.

Security note:

this method uses a constant-time (not short-circuiting) implementation to protect against timing attacks.

Overrides:

equals in class Object

hashCode

public final int hashCode()

Returns a “Java hash code” for this HashCode instance; this is well-defined (so, for example, you can safely put HashCode instances into a HashSet) but is otherwise probably not what you want to use.

Overrides:

hashCode in class Object

toString

public final String toString()

Returns a string containing each byte of asBytes(), in order, as a two-digit unsigned hexadecimal number in lower case.

Note that if the output is considered to be a single hexadecimal number, this hash code’s bytes are the big-endian representation of that number. This may be surprising since everything else in the hashing API uniformly treats multibyte values as little-endian. But this format conveniently matches that of utilities such as the UNIX md5sum command.

To create a HashCode from its string representation, see fromString(java.lang.String).

Overrides:

toString in class Object