HashCode
Date: 2016-05-24

com.google.common.hash

## Class HashCode

- java.lang.Object
- - com.google.common.hash.HashCode

-     @Beta
      public abstract class HashCode
      extends java.lang.Object

  An immutable hash code of arbitrary bit length.
  Since:
    11.0

- - ### Method Summary

    Methods
    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(java.lang.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(java.lang.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.
    `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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(java.lang.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
                       java.lang.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 `java.lang.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 `java.lang.Object`

    - #### toString

          public final java.lang.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 `java.lang.Object`