com.google.common.base

Class Equivalence<T>

java.lang.Object

com.google.common.base.Equivalence<T>

@GwtCompatible
public abstract class Equivalence<T>
extends Object

A strategy for determining whether two instances are considered equivalent, and for computing hash codes in a manner consistent with that equivalence. Two examples of equivalences are the identity equivalence and the "equals" equivalence.

For users targeting Android API level 24 or higher: This class will eventually implement BiPredicate<T, T> (as it does in the main Guava artifact), but we currently target a lower API level. In the meantime, if you have support for method references you can use an equivalence as a bi-predicate like this: myEquivalence::equivalent.

Since:

10.0 (mostly source-compatible since 4.0)

Author:

Bob Lee, Ben Yu, Gregory Kick

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

Modifier and Type	Method and Description
protected abstract boolean	doEquivalent(T a, T b) This method should not be called except by equivalent(T, T).
protected abstract int	doHash(T t) Implemented by the user to return a hash code for t, subject to the requirements specified in hash(T).
static Equivalence<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<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<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(@NullableDecl
                                T a,
                                @NullableDecl
                                T b)

Returns true if the given objects are considered equivalent.

This method describes an equivalence relation on object references, meaning that for all references x, y, and z (any of which may be null):

• equivalent(x, x) is true (reflexive property)
• equivalent(x, y) and equivalent(y, x) each return the same result (symmetric property)
• If equivalent(x, y) and equivalent(y, z) are both true, then equivalent(x, z) is also true (transitive property)

Note that all calls to equivalent(x, y) are expected to return the same result as long as neither x nor y is modified.

doEquivalent

@ForOverride
protected abstract boolean doEquivalent(T a,
                                                     T b)

This method should not be called except by equivalent(T, T). When equivalent(T, T) calls this method, a and b are guaranteed to be distinct, non-null instances.

Since:

10.0 (previously, subclasses would override equivalent())

hash

public final int hash(@NullableDecl
                      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

@ForOverride
protected abstract int doHash(T t)

Implemented by the user to return a hash code for t, subject to the requirements specified in hash(T).

This method should not be called except by hash(T). When hash(T) calls this method, t is guaranteed to be non-null.

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(@NullableDecl
                                                       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<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

public final Predicate<T> equivalentTo(@NullableDecl
                                       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<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<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)