Equivalence
Date: 2016-05-24

com.google.common.base

## Class Equivalence<T>

- java.lang.Object
- - com.google.common.base.Equivalence<T>

-     @CheckReturnValue
      @GwtCompatible
      public abstract class Equivalence<T>
      extends java.lang.Object

  A strategy for determining whether two instances are considered equivalent. Examples of equivalences are the identity equivalence and equals equivalence.
  Since:
    10.0 (mostly source-compatible since 4.0)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Equivalence.Wrapper<T>` Wraps an object so that `Equivalence.Wrapper.equals(Object)` and `Equivalence.Wrapper.hashCode()` delegate to an `Equivalence`.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Equivalence()` Constructor for use by subclasses.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract boolean` | `doEquivalent(T a, T b)` Returns `true` if `a` and `b` are considered equivalent.
    `protected abstract int` | `doHash(T t)` Returns a hash code for non-null object `t`.
    `static Equivalence<java.lang.Object>` | `equals()` Returns an equivalence that delegates to `Object.equals(java.lang.Object)` and `Object.hashCode()`.
    `boolean` | `equivalent(T a, T b)` Returns `true` if the given objects are considered equivalent.
    `Predicate<T>` | `equivalentTo(T target)` Returns a predicate that evaluates to true if and only if the input is equivalent to `target` according to this equivalence relation.
    `int` | `hash(T t)` Returns a hash code for `t`.
    `static Equivalence<java.lang.Object>` | `identity()` Returns an equivalence that uses `==` to compare values and `System.identityHashCode(Object)` to compute the hash code.
    `<F> Equivalence<F>` | `onResultOf(Function<F,? extends T> function)` Returns a new equivalence relation for `F` which evaluates equivalence by first applying `function` to the argument, then evaluating using `this`.
    `<S extends T> Equivalence<java.lang.Iterable<S>>` | `pairwise()` Returns an equivalence over iterables based on the equivalence of their elements.
    `<S extends T> Equivalence.Wrapper<S>` | `wrap(S reference)` Returns a wrapper of `reference` that implements `Object.equals()` such that `wrap(a).equals(wrap(b))` if and only if `equivalent(a, b)`.

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

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

- - ### Constructor Detail

    - #### Equivalence

          protected Equivalence()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### equivalent

          public final boolean equivalent(@Nullable
                           T a,
                           @Nullable
                           T b)

      Returns `true` if the given objects are considered equivalent.

      The `equivalent` method implements an equivalence relation on object references:

      - It is reflexive: for any reference `x`, including null, `equivalent(x, x)` returns `true`.
      - It is symmetric: for any references `x` and `y`, `equivalent(x, y) == equivalent(y, x)`.
      - It is transitive: for any references `x`, `y`, and `z`, if `equivalent(x, y)` returns `true` and `equivalent(y, z)` returns `true`, then `equivalent(x, z)` returns `true`.
      - It is consistent: for any references `x` and `y`, multiple invocations of `equivalent(x, y)` consistently return `true` or consistently return `false` (provided that neither `x` nor `y` is modified).

    - #### doEquivalent

          protected abstract boolean doEquivalent(T a,
                             T b)

      Returns `true` if `a` and `b` are considered equivalent.

      Called by `equivalent(T, T)`. `a` and `b` are not the same object and are not nulls.

      Since:
        10.0 (previously, subclasses would override equivalent())

    - #### hash

          public final int hash(@Nullable
                 T t)

      Returns a hash code for `t`.

      The `hash` has the following properties:

      - It is consistent: for any reference `x`, multiple invocations of `hash(x`} consistently return the same value provided `x` remains unchanged according to the definition of the equivalence. The hash need not remain consistent from one execution of an application to another execution of the same application.
      - It is distributable across equivalence: for any references `x` and `y`, if `equivalent(x, y)`, then `hash(x) == hash(y)`. It is not necessary that the hash be distributable across inequivalence. If `equivalence(x, y)` is false, `hash(x) == hash(y)` may still be true.
      - `hash(null)` is `0`.

    - #### doHash

          protected abstract int doHash(T t)

      Returns a hash code for non-null object `t`.

      Called by `hash(T)`.

      Since:
        10.0 (previously, subclasses would override hash())

    - #### onResultOf

          public final <F> Equivalence<F> onResultOf(Function<F,? extends T> function)

      Returns a new equivalence relation for `F` which evaluates equivalence by first applying `function` to the argument, then evaluating using `this`. That is, for any pair of non-null objects `x` and `y`, `equivalence.onResultOf(function).equivalent(a, b)` is true if and only if `equivalence.equivalent(function.apply(a), function.apply(b))` is true.

      For example:

             Equivalence<Person> SAME_AGE = Equivalence.equals().onResultOf(GET_PERSON_AGE);

      `function` will never be invoked with a null value.

      Note that `function` must be consistent according to `this` equivalence relation. That is, invoking `Function.apply(F)` multiple times for a given value must return equivalent results. For example, `Equivalence.identity().onResultOf(Functions.toStringFunction())` is broken because it's not guaranteed that `Object.toString()`) always returns the same string instance.

      Since:
        10.0

    - #### wrap

          public final <S extends T> Equivalence.Wrapper<S> wrap(@Nullable
                                                  S reference)

      Returns a wrapper of `reference` that implements `Object.equals()` such that `wrap(a).equals(wrap(b))` if and only if `equivalent(a, b)`.
      Since:
        10.0

    - #### pairwise

          @GwtCompatible(serializable=true)
          public final <S extends T> Equivalence<java.lang.Iterable<S>> pairwise()

      Returns an equivalence over iterables based on the equivalence of their elements. More specifically, two iterables are considered equivalent if they both contain the same number of elements, and each pair of corresponding elements is equivalent according to `this`. Null iterables are equivalent to one another.

      Note that this method performs a similar function for equivalences as `Ordering.lexicographical()` does for orderings.

      Since:
        10.0

    - #### equivalentTo

          @Beta
          public final Predicate<T> equivalentTo(@Nullable
                                       T target)

      Returns a predicate that evaluates to true if and only if the input is equivalent to `target` according to this equivalence relation.
      Since:
        10.0

    - #### equals

          public static Equivalence<java.lang.Object> equals()

      Returns an equivalence that delegates to `Object.equals(java.lang.Object)` and `Object.hashCode()`. `equivalent(T, T)` returns `true` if both values are null, or if neither value is null and `Object.equals(java.lang.Object)` returns `true`. `hash(T)` returns `0` if passed a null value.
      Since:
        13.0, 8.0 (in Equivalences with null-friendly behavior), 4.0 (in Equivalences)

    - #### identity

          public static Equivalence<java.lang.Object> identity()

      Returns an equivalence that uses `==` to compare values and `System.identityHashCode(Object)` to compute the hash code. `equivalent(T, T)` returns `true` if `a == b`, including in the case that a and b are both null.
      Since:
        13.0, 4.0 (in Equivalences)