Package com.exonum.binding.common.hash

Interface Hasher

All Superinterfaces:
PrimitiveSink
@Beta
@CanIgnoreReturnValue
public interface Hasher
extends PrimitiveSink
A PrimitiveSink that can compute a hash code after reading the input. Each hasher should translate all multibyte values (putInt(int), putLong(long), etc) to bytes in little-endian order.

Warning: The result of calling any methods after calling hash() is undefined.

Warning: Using a specific character encoding when hashing a CharSequence with putString(CharSequence, Charset) is generally only useful for cross-language compatibility (otherwise prefer putUnencodedChars(java.lang.CharSequence)). However, the character encodings must be identical across languages. Also beware that Charset definitions may occasionally change between Java releases.

Warning: Chunks of data that are put into the Hasher are not delimited. The resulting HashCode is dependent only on the bytes inserted, and the order in which they were inserted, not how those bytes were chunked into discrete put() operations. For example, the following three expressions all generate colliding hash codes: 

   

   newHasher().putByte(b1).putByte(b2).putByte(b3).hash()
   newHasher().putByte(b1).putBytes(new byte[] { b2, b3 }).hash()
   newHasher().putBytes(new byte[] { b1, b2, b3 }).hash()

If you wish to avoid this, you should either prepend or append the size of each chunk. Keep in mind that when dealing with char sequences, the encoded form of two concatenated char sequences is not equivalent to the concatenation of their encoded form. Therefore, putString(CharSequence, Charset) should only be used consistently with complete sequences and not broken into chunks.

Since:
11.0
Author:
Kevin Bourrillion

  • Method Summary

    Modifier and Type Method Description
    HashCode hash()
    Computes a hash code based on the data that have been provided to this hasher.
    int hashCode()
    Deprecated.
    This returns Object.hashCode(); you almost certainly mean to call hash().asInt().
    Hasher putBoolean​(boolean b)
    Equivalent to putByte(b ? (byte) 1 : (byte) 0).
    Hasher putByte​(byte b)
    Puts a byte into this sink.
    Hasher putBytes​(byte[] bytes)
    Puts an array of bytes into this sink.
    Hasher putBytes​(byte[] bytes, int off, int len)
    Puts a chunk of an array of bytes into this sink.
    Hasher putBytes​(java.nio.ByteBuffer bytes)
    Puts the remaining bytes of a byte buffer into this sink.
    Hasher putChar​(char c)
    Puts a character into this sink.
    Hasher putDouble​(double d)
    Equivalent to putLong(Double.doubleToRawLongBits(d)).
    Hasher putFloat​(float f)
    Equivalent to putInt(Float.floatToRawIntBits(f)).
    Hasher putInt​(int i)
    Puts an int into this sink.
    Hasher putLong​(long l)
    Puts a long into this sink.
    <T> Hasher putObject​(T instance, Funnel<? super T> funnel)
    A simple convenience for funnel.funnel(object, this).
    Hasher putShort​(short s)
    Puts a short into this sink.
    Hasher putString​(java.lang.CharSequence charSequence, java.nio.charset.Charset charset)
    Equivalent to putBytes(charSequence.toString().getBytes(charset)).
    Hasher putUnencodedChars​(java.lang.CharSequence charSequence)
    Equivalent to processing each char value in the CharSequence, in order.

  • Method Details

    • putByte

      Hasher putByte​(byte b)
      Description copied from interface: PrimitiveSink
      Puts a byte into this sink.
      Specified by:
      putByte in interface PrimitiveSink
      Parameters:
      b - a byte
      Returns:
      this instance

    • putBytes

      Hasher putBytes​(byte[] bytes)
      Description copied from interface: PrimitiveSink
      Puts an array of bytes into this sink.
      Specified by:
      putBytes in interface PrimitiveSink
      Parameters:
      bytes - a byte array
      Returns:
      this instance

    • putBytes

      Hasher putBytes​(byte[] bytes, int off, int len)
      Description copied from interface: PrimitiveSink
      Puts a chunk of an array of bytes into this sink. bytes[off] is the first byte written, bytes[off + len - 1] is the last.
      Specified by:
      putBytes in interface PrimitiveSink
      Parameters:
      bytes - a byte array
      off - the start offset in the array
      len - the number of bytes to write
      Returns:
      this instance

    • putBytes

      Hasher putBytes​(java.nio.ByteBuffer bytes)
      Description copied from interface: PrimitiveSink
      Puts the remaining bytes of a byte buffer into this sink. bytes.position() is the first byte written, bytes.limit() - 1 is the last. The position of the buffer will be equal to the limit when this method returns.
      Specified by:
      putBytes in interface PrimitiveSink
      Parameters:
      bytes - a byte buffer
      Returns:
      this instance

    • putShort

      Hasher putShort​(short s)
      Description copied from interface: PrimitiveSink
      Puts a short into this sink.
      Specified by:
      putShort in interface PrimitiveSink

    • putInt

      Hasher putInt​(int i)
      Description copied from interface: PrimitiveSink
      Puts an int into this sink.
      Specified by:
      putInt in interface PrimitiveSink

    • putLong

      Hasher putLong​(long l)
      Description copied from interface: PrimitiveSink
      Puts a long into this sink.
      Specified by:
      putLong in interface PrimitiveSink

    • putFloat

      Hasher putFloat​(float f)
      Equivalent to putInt(Float.floatToRawIntBits(f)).
      Specified by:
      putFloat in interface PrimitiveSink

    • putDouble

      Hasher putDouble​(double d)
      Equivalent to putLong(Double.doubleToRawLongBits(d)).
      Specified by:
      putDouble in interface PrimitiveSink

    • putBoolean

      Hasher putBoolean​(boolean b)
      Equivalent to putByte(b ? (byte) 1 : (byte) 0).
      Specified by:
      putBoolean in interface PrimitiveSink

    • putChar

      Hasher putChar​(char c)
      Description copied from interface: PrimitiveSink
      Puts a character into this sink.
      Specified by:
      putChar in interface PrimitiveSink

    • putUnencodedChars

      Hasher putUnencodedChars​(java.lang.CharSequence charSequence)
      Equivalent to processing each char value in the CharSequence, in order. In other words, no character encoding is performed; the low byte and high byte of each char are hashed directly (in that order). The input must not be updated while this method is in progress.

      Warning: This method will produce different output than most other languages do when running the same hash function on the equivalent input. For cross-language compatibility, use putString(java.lang.CharSequence, java.nio.charset.Charset), usually with a charset of UTF-8. For other use cases, use putUnencodedChars.

      Specified by:
      putUnencodedChars in interface PrimitiveSink
      Since:
      15.0 (since 11.0 as putString(CharSequence)).

    • putString

      Hasher putString​(java.lang.CharSequence charSequence, java.nio.charset.Charset charset)
      Equivalent to putBytes(charSequence.toString().getBytes(charset)).

      Warning: This method, which reencodes the input before hashing it, is useful only for cross-language compatibility. For other use cases, prefer putUnencodedChars(java.lang.CharSequence), which is faster, produces the same output across Java releases, and hashes every char in the input, even if some are invalid.

      Specified by:
      putString in interface PrimitiveSink

    • putObject

      <T> Hasher putObject​(T instance, Funnel<? super T> funnel)
      A simple convenience for funnel.funnel(object, this).

    • hash

      HashCode hash()
      Computes a hash code based on the data that have been provided to this hasher. The result is unspecified if this method is called more than once on the same instance.

    • hashCode

      @Deprecated int hashCode()
      Deprecated.
      This returns Object.hashCode(); you almost certainly mean to call hash().asInt().
      Overrides:
      hashCode in class java.lang.Object