Class Equivalence<T>
 java.lang.Object

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

 All Implemented Interfaces:
BiPredicate<T,T>
@GwtCompatible public abstract class Equivalence<T> extends Object implements BiPredicate<T,T>
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. Since:
 10.0 (mostly sourcecompatible since 4.0)
 Author:
 Bob Lee, Ben Yu, Gregory Kick


Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Equivalence.Wrapper<T>
Wraps an object so thatEquivalence.Wrapper.equals(Object)
andEquivalence.Wrapper.hashCode()
delegate to anEquivalence
.

Constructor Summary
Constructors Modifier Constructor Description protected
Equivalence()
Constructor for use by subclasses.

Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected abstract boolean
doEquivalent(T a, T b)
Implemented by the user to determine whethera
andb
are considered equivalent, subject to the requirements specified inequivalent(T, T)
.protected abstract int
doHash(T t)
Implemented by the user to return a hash code fort
, subject to the requirements specified inhash(T)
.static Equivalence<Object>
equals()
Returns an equivalence that delegates toObject.equals(java.lang.Object)
andObject.hashCode()
.boolean
equivalent(@Nullable T a, @Nullable T b)
Returnstrue
if the given objects are considered equivalent.Predicate<T>
equivalentTo(@Nullable T target)
Returns a predicate that evaluates to true if and only if the input is equivalent totarget
according to this equivalence relation.int
hash(@Nullable T t)
Returns a hash code fort
.static Equivalence<Object>
identity()
Returns an equivalence that uses==
to compare values andSystem.identityHashCode(Object)
to compute the hash code.<F> Equivalence<F>
onResultOf(Function<F,? extends T> function)
Returns a new equivalence relation forF
which evaluates equivalence by first applyingfunction
to the argument, then evaluating usingthis
.<S extends T>
Equivalence<Iterable<S>>pairwise()
Returns an equivalence over iterables based on the equivalence of their elements.boolean
test(@Nullable T t, @Nullable T u)
Deprecated.Provided only to satisfy theBiPredicate
interface; useequivalent(T, T)
instead.<S extends T>
Equivalence.Wrapper<S>wrap(@Nullable S reference)
Returns a wrapper ofreference
that implementsObject.equals()
such thatwrap(a).equals(wrap(b))
if and only ifequivalent(a, b)
.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.function.BiPredicate
and, negate, or




Constructor Detail

Equivalence
protected Equivalence()
Constructor for use by subclasses.


Method Detail

equivalent
public final boolean equivalent(@Nullable T a, @Nullable T b)
Returnstrue
if the given objects are considered equivalent.This method describes an equivalence relation on object references, meaning that for all references
x
,y
, andz
(any of which may be null):equivalent(x, x)
is true (reflexive property)equivalent(x, y)
andequivalent(y, x)
each return the same result (symmetric property) If
equivalent(x, y)
andequivalent(y, z)
are both true, thenequivalent(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 neitherx
nory
is modified.

test
@Deprecated public final boolean test(@Nullable T t, @Nullable T u)
Deprecated.Provided only to satisfy theBiPredicate
interface; useequivalent(T, T)
instead.Description copied from interface:java.util.function.BiPredicate
Evaluates this predicate on the given arguments. Specified by:
test
in interfaceBiPredicate<T,T>
 Parameters:
t
 the first input argumentu
 the second input argument Returns:
true
if the input arguments match the predicate, otherwisefalse
 Since:
 21.0

doEquivalent
@ForOverride protected abstract boolean doEquivalent(T a, T b)
Implemented by the user to determine whethera
andb
are considered equivalent, subject to the requirements specified inequivalent(T, T)
.This method should not be called except by
equivalent(T, T)
. Whenequivalent(T, T)
calls this method,a
andb
are guaranteed to be distinct, nonnull instances. Since:
 10.0 (previously, subclasses would override equivalent())

hash
public final int hash(@Nullable T t)
Returns a hash code fort
.The
hash
has the following properties: It is consistent: for any reference
x
, multiple invocations ofhash(x
} consistently return the same value providedx
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
andy
, ifequivalent(x, y)
, thenhash(x) == hash(y)
. It is not necessary that the hash be distributable across inequivalence. Ifequivalence(x, y)
is false,hash(x) == hash(y)
may still be true. hash(null)
is0
.
 It is consistent: for any reference

doHash
@ForOverride protected abstract int doHash(T t)
Implemented by the user to return a hash code fort
, subject to the requirements specified inhash(T)
.This method should not be called except by
hash(T)
. Whenhash(T)
calls this method,t
is guaranteed to be nonnull. 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 forF
which evaluates equivalence by first applyingfunction
to the argument, then evaluating usingthis
. That is, for any pair of nonnull objectsx
andy
,equivalence.onResultOf(function).equivalent(a, b)
is true if and only ifequivalence.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 tothis
equivalence relation. That is, invokingFunction.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 thatObject.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 ofreference
that implementsObject.equals()
such thatwrap(a).equals(wrap(b))
if and only ifequivalent(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 tothis
. 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(@Nullable T target)
Returns a predicate that evaluates to true if and only if the input is equivalent totarget
according to this equivalence relation. Since:
 10.0

equals
public static Equivalence<Object> equals()
Returns an equivalence that delegates toObject.equals(java.lang.Object)
andObject.hashCode()
.equivalent(T, T)
returnstrue
if both values are null, or if neither value is null andObject.equals(java.lang.Object)
returnstrue
.hash(T)
returns0
if passed a null value. Since:
 13.0, 8.0 (in Equivalences with nullfriendly behavior), 4.0 (in Equivalences)

identity
public static Equivalence<Object> identity()
Returns an equivalence that uses==
to compare values andSystem.identityHashCode(Object)
to compute the hash code.equivalent(T, T)
returnstrue
ifa == b
, including in the case that a and b are both null. Since:
 13.0, 4.0 (in Equivalences)

