@GwtCompatible public abstract class Equivalence<T> extends Object implements BiPredicate<T,T>
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)
Implemented by the user to determine whether
a and b are considered equivalent,
subject to the requirements specified in 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.
|
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(T a, 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.
@Deprecated public final boolean test(T t, T u)
BiPredicate
interface; use equivalent(T, T)
instead.java.util.function.BiPredicate
test
in interface BiPredicate<T,T>
t
- the first input argumentu
- the second input argumenttrue
if the input arguments match the predicate,
otherwise false
@ForOverride protected abstract boolean doEquivalent(T a, T b)
a
and b
are considered equivalent,
subject to the requirements specified in equivalent(T, T)
.
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.
public final int hash(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 non-null.
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(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(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.