Class HashCode


  • @Beta
    public abstract class HashCode
    extends Object
    An immutable hash code of arbitrary bit length.
    Since:
    11.0
    Author:
    Dimitris Andreou, Kurt Alfred Kluever
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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​(@Nullable 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.
    • Method Detail

      • bits

        public abstract int bits()
        Returns the number of bits in this hash code; a positive multiple of 8.
      • padToLong

        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

        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

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

        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

        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

        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)
      • 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
        Parameters:
        object - the reference object with which to compare.
        Returns:
        true if this object is the same as the obj argument; false otherwise.
        See Also:
        Object.hashCode(), HashMap
      • 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
        Returns:
        a string representation of the object.