@GwtCompatible public abstract class Equivalence<T> extends Object
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 bipredicate like this: myEquivalence::equivalent
.
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 . 
Modifier  Constructor and Description 

protected 
Equivalence()
Constructor for use by subclasses.

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> 
pairwise()
Returns an equivalence over iterables based on the equivalence of their elements.

<S extends T> 
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) . 
protected Equivalence()
public final boolean equivalent(@NullableDecl T a, @NullableDecl T b)
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)
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.
@ForOverride protected abstract boolean doEquivalent(T a, T b)
equivalent(T, T)
. When equivalent(T, T)
calls
this method, a
and b
are guaranteed to be distinct, nonnull instances.public final int hash(@NullableDecl T t)
t
.
The hash
has the following properties:
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.
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
.
@ForOverride protected abstract int doHash(T t)
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 nonnull.
public final <F> Equivalence<F> onResultOf(Function<F,? extends T> function)
F
which evaluates equivalence by first applying
function
to the argument, then evaluating using this
. That is, for any pair of
nonnull 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.
public final <S extends T> Equivalence.Wrapper<S> wrap(@NullableDecl S reference)
reference
that implements Object.equals()
such that wrap(a).equals(wrap(b))
if and only if equivalent(a,
b)
.@GwtCompatible(serializable=true) public final <S extends T> Equivalence<Iterable<S>> pairwise()
this
. Null
iterables are equivalent to one another.
Note that this method performs a similar function for equivalences as Ordering.lexicographical()
does for orderings.
public final Predicate<T> equivalentTo(@NullableDecl T target)
target
according to this equivalence relation.public static Equivalence<Object> equals()
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.public static Equivalence<Object> identity()
==
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.Copyright © 2010–2019. All rights reserved.