@GwtCompatible public abstract class Equivalence<T> extends Object implements BiPredicate<T,T>
A future version of this class will implement BiPredicate<T, T>
. In the meantime, to
use an equivalence (say, named equivalence
) as a bi-predicate, use the method reference
equivalence::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)
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<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.
|
boolean |
test(T t,
T u)
Deprecated.
Provided only to satisfy the
BiPredicate interface; use
equivalent(T, T) instead. |
<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) . |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
and, negate, or
protected Equivalence()
public final boolean equivalent(@Nullable T a, @Nullable T b)
true
if the given objects are considered equivalent.
The equivalent
method implements an equivalence relation on object references:
x
, including null, equivalent(x, x)
returns true
.
x
and y
, equivalent(x, y) == equivalent(y, x)
.
x
, y
, and z
, if
equivalent(x, y)
returns true
and equivalent(y, z)
returns true
, then equivalent(x, z)
returns true
.
x
and y
, multiple invocations
of equivalent(x, y)
consistently return true
or consistently return false
(provided that neither x
nor y
is modified).
@Deprecated public final boolean test(@Nullable T t, @Nullable T u)
BiPredicate
interface; use
equivalent(T, T)
instead.test
in interface BiPredicate<T,T>
protected abstract boolean doEquivalent(T a, T b)
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.
public final int hash(@Nullable 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
.
protected abstract int doHash(T t)
t
.
Called by hash(T)
.
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
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.
public final <S extends T> Equivalence.Wrapper<S> wrap(@Nullable 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(@Nullable 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-2017. All Rights Reserved.