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

java.lang.Object
  extended by com.google.common.base.Equivalence<T>

@Beta
@GwtCompatible
public abstract class Equivalence<T>
extends Object

A strategy for determining whether two instances are considered equivalent. Examples of equivalences are the identity equivalence and equals equivalence.

Since:
10.0 (mostly source-compatible since 4.0)
Author:
Bob Lee, Ben Yu, Gregory Kick

Nested Class Summary
static class Equivalence.Wrapper<T>
          Wraps an object so that Equivalence.Wrapper.equals(Object) and Equivalence.Wrapper.hashCode() delegate to an Equivalence.
 
Constructor Summary
protected Equivalence()
          Constructor for use by subclasses.
 
Method Summary
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.
 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.
<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>
Equivalence<Iterable<S>>
pairwise()
          Returns an equivalence over iterables based on the equivalence of their elements.
<S extends T>
Equivalence.Wrapper<S>
wrap(S reference)
          Returns a wrapper of reference that implements Object.equals() such that wrap(this, a).equals(wrap(this, b)) if and only if this.equivalent(a, b).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Equivalence

protected Equivalence()
Constructor for use by subclasses.

Method Detail

equivalent

public final boolean equivalent(@Nullable
                                T a,
                                @Nullable
                                T b)
Returns true if the given objects are considered equivalent.

The equivalent method implements an equivalence relation on object references:


doEquivalent

protected abstract boolean doEquivalent(T a,
                                        T b)
Returns 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.

Since:
10.0 (previously, subclasses would override equivalent())

hash

public final int hash(@Nullable
                      T t)
Returns a hash code for t.

The hash has the following properties:


doHash

protected abstract int doHash(T t)
Returns a hash code for non-null object t.

Called by hash(T).

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 for 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 = Equivalences.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, Equivalences.identity().onResultOf(Functions.toStringFunction()) is broken because it's not guaranteed that Object.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 of reference that implements Object.equals() such that wrap(this, a).equals(wrap(this, b)) if and only if this.equivalent(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 to this. 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 to target according to this equivalence relation.

Since:
10.0


Copyright © 2010-2011. All Rights Reserved.