com.tomgibara.crinch.hashing

## Class PerfectStringHash

- java.lang.Object
- - com.tomgibara.crinch.hashing.PerfectStringHash

- All Implemented Interfaces:
    Hash<String>

      public class PerfectStringHash
      extends Object
      implements Hash<String>

  A "minimal perfect hash" for Strings. After construction with an array of n unique non-null strings, an instance of this class will return a unique hash value h (0 <= h < n) for any string s in the array. A negative has value will typically be returned for a string that is not in the array.

  However, the supplied array is not retained. This means that the implementation cannot necessarily confirm that a string is not in the supplied array. Where this implementation cannot distinguish that a string is not in the array, a 'valid' hash value may be returned. Under no circumstances will a hash value be returned that is greater than or equal to n.

  IMPORTANT NOTE: The array of strings supplied to the constructor will be mutated: it is re-ordered so that `hash(a[i]) == i`. Application code must generally use this information to map hash values back onto the appropriate string value.

  NOTE: Good performance of this algorithm is predicated on string hash values being cached by the `String` class. Experience indicates that is is a good assumption.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PerfectStringHash(String[] values)` Constructs a minimal perfect string hashing over the supplied strings.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `HashRange` | `getRange()`
    `BigInteger` | `hashAsBigInt(String value)` The hash value as a `BigInteger`.
    `int` | `hashAsInt(String value)` The hash value as an int.
    `long` | `hashAsLong(String value)` The hash value as a long.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PerfectStringHash

          public PerfectStringHash(String[] values)

      Constructs a minimal perfect string hashing over the supplied strings.
      Parameters:
        `values` - an array of unique non-null strings that will be reordered such that `hash(values[i]) == i`.

  - ### Method Detail

    - #### getRange

          public HashRange getRange()

      Specified by:
        `getRange` in interface `Hash<String>`

    - #### hashAsBigInt

          public BigInteger hashAsBigInt(String value)

      Description copied from interface: `Hash`
      The hash value as a `BigInteger`. This method may be useful in circumstances where the generated hash is too large to be accomodated in a single primitive value, eg. if cryptographic hashes are being used.
      Specified by:
        `hashAsBigInt` in interface `Hash<String>`
      Parameters:
        `value` - the object to be hashed
      Returns:
        the object's hash code, never null

    - #### hashAsInt

          public int hashAsInt(String value)

      Description copied from interface: `Hash`
      The hash value as an int. This method should provide better performance for integer-ranged hashes. This value is not guaranteed to lie within the indicated `HashRange`.
      Specified by:
        `hashAsInt` in interface `Hash<String>`
      Parameters:
        `value` - the object to be hashed
      Returns:
        the object's hash code

    - #### hashAsLong

          public long hashAsLong(String value)

      Description copied from interface: `Hash`
      The hash value as a long. This method should provide better performance for long-ranged hashes. This value is not guaranteed to lie within the indicated `HashRange`.
      Specified by:
        `hashAsLong` in interface `Hash<String>`
      Parameters:
        `value` - the object to be hashed
      Returns:
        the object's hash code