Class Equivalence<T>
For Java 8+ users
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
.
- Since:
- 10.0 (mostly source-compatible since 4.0)
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Wraps an object so thatEquivalence.Wrapper.equals(Object)
andEquivalence.Wrapper.hashCode()
delegate to anEquivalence
. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected abstract boolean
doEquivalent
(T a, T b) Returnstrue
ifa
andb
are considered equivalent.protected abstract int
Returns a hash code for non-null objectt
.static Equivalence
<Object> equals()
Returns an equivalence that delegates toObject.equals(java.lang.Object)
andObject.hashCode()
.final boolean
equivalent
(T a, T b) Returnstrue
if the given objects are considered equivalent.equivalentTo
(T target) Returns a predicate that evaluates to true if and only if the input is equivalent totarget
according to this equivalence relation.final int
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.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
.final <S extends T>
Equivalence<Iterable<S>> pairwise()
Returns an equivalence over iterables based on the equivalence of their elements.final <S extends T>
Equivalence.Wrapper<S> wrap
(S reference) Returns a wrapper ofreference
that implementsObject.equals()
such thatwrap(a).equals(wrap(b))
if and only ifequivalent(a, b)
.
-
Constructor Details
-
Equivalence
protected Equivalence()Constructor for use by subclasses.
-
-
Method Details
-
equivalent
Returnstrue
if the given objects are considered equivalent.The
equivalent
method implements an equivalence relation on object references:- It is reflexive: for any reference
x
, including null,equivalent(x, x)
returnstrue
. - It is symmetric: for any references
x
andy
,equivalent(x, y) == equivalent(y, x)
. - It is transitive: for any references
x
,y
, andz
, ifequivalent(x, y)
returnstrue
andequivalent(y, z)
returnstrue
, thenequivalent(x, z)
returnstrue
. - It is consistent: for any references
x
andy
, multiple invocations ofequivalent(x, y)
consistently returntrue
or consistently returnfalse
(provided that neitherx
nory
is modified).
- It is reflexive: for any reference
-
doEquivalent
Returnstrue
ifa
andb
are considered equivalent.Called by
equivalent(T, T)
.a
andb
are not the same object and are not nulls.- Since:
- 10.0 (previously, subclasses would override equivalent())
-
hash
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
Returns a hash code for non-null objectt
.Called by
hash(T)
.- Since:
- 10.0 (previously, subclasses would override hash())
-
onResultOf
Returns a new equivalence relation forF
which evaluates equivalence by first applyingfunction
to the argument, then evaluating usingthis
. That is, for any pair of non-null 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
Returns a wrapper ofreference
that implementsObject.equals()
such thatwrap(a).equals(wrap(b))
if and only ifequivalent(a, b)
.- Since:
- 10.0
-
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
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
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 null-friendly behavior), 4.0 (in Equivalences)
-
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)
-