Class Equivalence<T>


public abstract class Equivalence<T> extends Object
A strategy for determining whether two instances are considered equivalent. Examples of equivalences are the identity equivalence and equals equivalence.
10.0 (mostly source-compatible since 4.0)
Bob Lee, Ben Yu, Gregory Kick
  • Constructor Details

    • Equivalence

      public Equivalence()
  • Method Details

    • equals

      public static Equivalence<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.
      4.0 (in Equivalences)
    • identity

      public static Equivalence<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.
      4.0 (in Equivalences)
    • equivalent

      public final boolean equivalent(T a, 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.

      10.0 (previously, subclasses would override equivalent())
    • hash

      public final int hash(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).

      10.0 (previously, subclasses would override hash())