de.caff.generics

## Class HashCoder<T>

- java.lang.Object
- - de.caff.generics.HashCoder<T>

- Type Parameters:
    `T` - type of hashed object
  All Implemented Interfaces:
    HashCodeCalculator<T>, Matcher<T,T>, UniformMatcher<T>, java.util.function.BiPredicate<T,T>

      public class HashCoder<T>
      extends java.lang.Object
      implements HashCodeCalculator<T>, UniformMatcher<T>

  Helper interface for `HashCoderMap`.

  This class provides substitute hash values and equals implementation. To be `null`-safe all three arguments of `HashCoder(HashCodeCalculator, Matcher, Function)` need to be `null`-safe. The default implementations used in the constructors with fewer arguments are `null`-safe.

  Since:
    Mai 18, 2020
  Author:
    Rammi

- - ### Field Summary

    - ### Fields inherited from interface de.caff.generics.HashCodeCalculator

      `OBJECTS`

    - ### Fields inherited from interface de.caff.generics.UniformMatcher

      `IDENTICAL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `HashCoder(java.util.function.Function<T,T> copier)` Constructor.
    `HashCoder(HashCodeCalculator<? super T> codeCalculator)` Constructor.
    `HashCoder(HashCodeCalculator<? super T> codeCalculator, Matcher<? super T,? super T> matcher)` Constructor.
    `HashCoder(HashCodeCalculator<? super T> codeCalculator, Matcher<? super T,? super T> matcher, java.util.function.Function<T,T> copier)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `areEqual(T object1, T object2)` Are the given two objects considered equal?
    `T` | `copy(T key)` Copy a key.
    `int` | `getHashCode(T obj)` Get the hash code value of the given object.
    `static <V> HashCoder<V>` | `natural()` Get a fast natural hash coder using just the object's methods for hashing and equality, but not checking for `null` values.
    `static <V> HashCoder<V>` | `naturalNullSafe()` Get a natural hash coder using just the object's methods for hashing and equality, allowing for `null` values.

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

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

    - ### Methods inherited from interface de.caff.generics.HashCodeCalculator

      `objects`

    - ### Methods inherited from interface de.caff.generics.UniformMatcher

      `identical`

    - ### Methods inherited from interface de.caff.generics.Matcher

      `foldLeft, foldRight, test`

    - ### Methods inherited from interface java.util.function.BiPredicate

      `and, negate, or`

- - ### Constructor Detail

    - #### HashCoder

          public HashCoder(@NotNull
                           HashCodeCalculator<? super T> codeCalculator,
                           @NotNull
                           Matcher<? super T,? super T> matcher,
                           @NotNull
                           java.util.function.Function<T,T> copier)

      Constructor.
      Parameters:
        `codeCalculator` - calculator for hash codes
        `matcher` - equality checker
        `copier` - copier for incoming and outgoing keys, useful to make keys immutable which is a basic requirements for hash keys

    - #### HashCoder

          public HashCoder(@NotNull
                           HashCodeCalculator<? super T> codeCalculator,
                           @NotNull
                           Matcher<? super T,? super T> matcher)

      Constructor.

      This used simple copying for the keys.

      Parameters:
        `codeCalculator` - calculator for hash codes
        `matcher` - equality checker

    - #### HashCoder

          public HashCoder(@NotNull
                           HashCodeCalculator<? super T> codeCalculator)

      Constructor. This uses `Objects.equals(java.lang.Object, java.lang.Object)` and simple copying for the keys.
      Parameters:
        `codeCalculator` - hash code calculator

    - #### HashCoder

          public HashCoder(@NotNull
                           java.util.function.Function<T,T> copier)

      Constructor. This is useful to decouple hash keys, allowing to use mutable objects for keys in a hash map or set. Obviuosly then the copier has to really copy the object.

      Hashcode and equality checks are just using the standard implementation from the key objects.

      Parameters:
        `copier` - copier for incoming and outgoing keys

  - ### Method Detail

    - #### getHashCode

          public int getHashCode(T obj)

      Description copied from interface: `HashCodeCalculator`
      Get the hash code value of the given object.
      Specified by:
        `getHashCode` in interface `HashCodeCalculator<T>`
      Parameters:
        `obj` - object for which the hash code is requested
      Returns:
        hash code

    - #### areEqual

          public boolean areEqual(T object1,
                                  T object2)

      Description copied from interface: `Matcher`
      Are the given two objects considered equal?
      Specified by:
        `areEqual` in interface `Matcher<T,T>`
      Parameters:
        `object1` - first object
        `object2` - second object
      Returns:
        `true` if this matcher considers the two objects equal
        `false` if this matcher considers them different

    - #### copy

          public T copy(T key)

      Copy a key.
      Parameters:
        `key` - key to copy
      Returns:
        copied key, possible the incoming one

    - #### natural

          @NotNull
          public static <V> HashCoder<V> natural()

      Get a fast natural hash coder using just the object's methods for hashing and equality, but not checking for `null` values.
      Specified by:
        `natural` in interface `HashCodeCalculator<T>`
      Specified by:
        `natural` in interface `UniformMatcher<T>`
      Type Parameters:
        `V` - value type
      Returns:
        natural hash coder

    - #### naturalNullSafe

          @NotNull
          public static <V> HashCoder<V> naturalNullSafe()

      Get a natural hash coder using just the object's methods for hashing and equality, allowing for `null` values.
      Specified by:
        `naturalNullSafe` in interface `HashCodeCalculator<T>`
      Specified by:
        `naturalNullSafe` in interface `UniformMatcher<T>`
      Type Parameters:
        `V` - value type
      Returns:
        natural hash coder