Top Description Inners Constructors Methods
com.google.common.base

public abstract Class Equivalence<T>

extends Object
implements BiPredicate<@Nullable T, @Nullable T>
Class Inheritance
All Implemented Interfaces
java.util.function.BiPredicate
Known Direct Subclasses
com.google.common.base.Equivalence.Equals, com.google.common.base.Equivalence.Identity, com.google.common.base.FunctionalEquivalence, com.google.common.base.PairwiseEquivalence
Annotations
@GwtCompatible
@ElementTypesAreNonnullByDefault
Static Imports
com.google.common.base.Preconditions.checkNotNull

A strategy for determining whether two instances are considered equivalent, and for computing hash codes in a manner consistent with that equivalence. Two examples of equivalences are the identity equivalence and the "equals" equivalence.
Authors
Bob Lee, Ben Yu, Gregory Kick
Since
10.0 (mostly source-compatible since 4.0)

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
private static class
pack-priv static class
public static class
Equivalence.Wrapper<T extends @Nullable Object>

Wraps an object so that equals(Object) and hashCode() delegate to an Equivalence.

Constructor Summary

AccessConstructor and Description
protected
Equivalence()

Constructor for use by subclasses.

Method Summary

Modifier and TypeMethod 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.

protected abstract int
doHash(T t)

Implemented by the user to return a hash code for t, subject to the requirements specified in hash.

public static Equivalence<Object>
equals()

Returns an equivalence that delegates to Object#equals and Object#hashCode.

public final boolean
equivalent(T a, T b)

Returns true if the given objects are considered equivalent.

public final Predicate<@Nullable 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.

public final int
hash(T t)

Returns a hash code for t.

public static Equivalence<Object>
identity()

Returns an equivalence that uses == to compare values and System#identityHashCode(Object) to compute the hash code.

public final <F> Equivalence<F>
onResultOf(Function<? super F, ? extends @Nullable T> function)

Returns a new equivalence relation for F which evaluates equivalence by first applying function to the argument, then evaluating using this.

public final <S extends @Nullable T> Equivalence<Iterable<S>>
pairwise()

Returns an equivalence over iterables based on the equivalence of their elements.

public final boolean
test(T
the first input argument
t
,
T
the second input argument
u
)

Implements java.util.function.BiPredicate.test.

Deprecated Provided only to satisfy the BiPredicate interface; use equivalent instead.
Evaluates this predicate on the given arguments.
public final <S extends @Nullable T> Equivalence.Wrapper<S>
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).

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Equivalenceback to summary
protected Equivalence()

Constructor for use by subclasses.

Method Detail

doEquivalentback to summary
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.

This method should not be called except by equivalent. When equivalent calls this method, a and b are guaranteed to be distinct, non-null instances.

Annotations
@ForOverride
Since
10.0 (previously, subclasses would override equivalent())
doHashback to summary
protected abstract int doHash(T t)

Implemented by the user to return a hash code for t, subject to the requirements specified in hash.

This method should not be called except by hash. When hash calls this method, t is guaranteed to be non-null.

Annotations
@ForOverride
Since
10.0 (previously, subclasses would override hash())
equalsback to summary
public static Equivalence<Object> equals()

Returns an equivalence that delegates to Object#equals and Object#hashCode. Equivalence#equivalent returns true if both values are null, or if neither value is null and Object#equals returns true. Equivalence#hash returns 0 if passed a null value.

Since
13.0, 8.0 (in Equivalences with null-friendly behavior), 4.0 (in Equivalences)
equivalentback to summary
public final boolean equivalent(T a, T b)

Returns 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)
  • If 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.

equivalentToback to summary
public final Predicate<@Nullable 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.

Since
10.0
hashback to summary
public final int hash(T t)

Returns a hash code for t.

The hash has the following properties:

  • It is consistent: for any reference 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.
  • It is distributable across equivalence: for any references 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.
identityback to summary
public static Equivalence<Object> identity()

Returns an equivalence that uses == to compare values and System#identityHashCode(Object) to compute the hash code. Equivalence#equivalent returns true if a == b, including in the case that a and b are both null.

Since
13.0, 4.0 (in Equivalences)
onResultOfback to summary
public final <F> Equivalence<F> onResultOf(Function<? super F, ? extends @Nullable 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 = 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 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.

Since
10.0
pairwiseback to summary
public final <S extends @Nullable 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 com.google.common.collect.Ordering#lexicographical does for orderings.

The returned object is serializable if this object is serializable.

Annotations
@GwtCompatible
serializable:true
Since
10.0
testback to summary
public final boolean test(T t, T u)

Implements java.util.function.BiPredicate.test.

Doc from java.util.function.BiPredicate.test.

Deprecated

Provided only to satisfy the BiPredicate interface; use equivalent instead.

Evaluates this predicate on the given arguments.

Parameters
t:T

the first input argument

u:T

the second input argument

Returns:boolean

true if the input arguments match the predicate, otherwise false

Annotations
@Deprecated
@Override
Since
21.0
wrapback to summary
public final <S extends @Nullable T> Equivalence.Wrapper<S> 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).

The returned object is serializable if both this Equivalence and reference are serializable (including when reference is null).

Since
10.0
com.google.common.base back to summary

pack-priv final Class Equivalence.Equals

extends Equivalence<Object>
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable

Field Summary

Modifier and TypeField and Description
pack-priv static final Equivalence.Equals
private static final long

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
protected boolean
doEquivalent(Object a, Object b)

Implements abstract com.google.common.base.Equivalence.doEquivalent.

Implemented by the user to determine whether a and b are considered equivalent, subject to the requirements specified in equivalent.
protected int
doHash(Object o)

Implements abstract com.google.common.base.Equivalence.doHash.

Implemented by the user to return a hash code for t, subject to the requirements specified in hash.
private Object
Inherited from com.google.common.base.Equivalence:
equalsequivalentequivalentTohashidentityonResultOfpairwisetestwrap

Field Detail

INSTANCEback to summary
pack-priv static final Equivalence.Equals INSTANCE
serialVersionUIDback to summary
private static final long serialVersionUID

Constructor Detail

Equalsback to summary
pack-priv Equals()

Method Detail

doEquivalentback to summary
protected boolean doEquivalent(Object a, Object b)

Implements abstract com.google.common.base.Equivalence.doEquivalent.

Doc from com.google.common.base.Equivalence.doEquivalent.

Implemented by the user to determine whether a and b are considered equivalent, subject to the requirements specified in equivalent.

This method should not be called except by equivalent. When equivalent calls this method, a and b are guaranteed to be distinct, non-null instances.

Annotations
@Override
doHashback to summary
protected int doHash(Object o)

Implements abstract com.google.common.base.Equivalence.doHash.

Doc from com.google.common.base.Equivalence.doHash.

Implemented by the user to return a hash code for t, subject to the requirements specified in hash.

This method should not be called except by hash. When hash calls this method, t is guaranteed to be non-null.

Annotations
@Override
readResolveback to summary
private Object readResolve()
com.google.common.base back to summary

private final Class Equivalence.EquivalentToPredicate<T>

extends Object
implements Predicate<@Nullable T>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, com.google.common.base.Predicate, java.util.function.Predicate

Field Summary

Modifier and TypeField and Description
private final Equivalence<T>
private static final long
private final T

Constructor Summary

AccessConstructor and Description
pack-priv
EquivalentToPredicate(Equivalence<T> equivalence, T target)

Method Summary

Modifier and TypeMethod and Description
public boolean
apply(T input)

Implements com.google.common.base.Predicate.apply.

Returns the result of applying this predicate to input (Java 8+ users, see notes in the class documentation above).
public boolean
equals(Object
the reference object with which to compare.
obj
)

Overrides java.lang.Object.equals.

Implements com.google.common.base.Predicate.equals.

Indicates whether another object is equal to this predicate.
public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

equivalenceback to summary
private final Equivalence<T> equivalence
serialVersionUIDback to summary
private static final long serialVersionUID
targetback to summary
private final T target
Annotations
@CheckForNull

Constructor Detail

EquivalentToPredicateback to summary
pack-priv EquivalentToPredicate(Equivalence<T> equivalence, T target)

Method Detail

applyback to summary
public boolean apply(T input)

Implements com.google.common.base.Predicate.apply.

Doc from com.google.common.base.Predicate.apply.

Returns the result of applying this predicate to input (Java 8+ users, see notes in the class documentation above). This method is generally expected, but not absolutely required, to have the following properties:

  • Its execution does not cause any observable side effects.
  • The computation is consistent with equals; that is, Objects.equal(a, b) implies that predicate.apply(a) == predicate.apply(b)).
Annotations
@Override
equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Implements com.google.common.base.Predicate.equals.

Doc from com.google.common.base.Predicate.equals.

Indicates whether another object is equal to this predicate.

Most implementations will have no reason to override the behavior of Object#equals. However, an implementation may also choose to return true whenever object is a Predicate that it considers interchangeable with this one. "Interchangeable" typically means that this.apply(t) == that.apply(t) for all t of type T). Note that a false result from this method does not imply that the predicates are known not to be interchangeable.

Parameters
obj:Object

Doc from java.lang.Object.equals.

the reference object with which to compare.

Returns:boolean

Doc from java.lang.Object.equals.

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object

Annotations
@Override
com.google.common.base back to summary

pack-priv final Class Equivalence.Identity

extends Equivalence<Object>
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable

Field Summary

Modifier and TypeField and Description
pack-priv static final Equivalence.Identity
private static final long

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
protected boolean
doEquivalent(Object a, Object b)

Implements abstract com.google.common.base.Equivalence.doEquivalent.

Implemented by the user to determine whether a and b are considered equivalent, subject to the requirements specified in equivalent.
protected int
doHash(Object o)

Implements abstract com.google.common.base.Equivalence.doHash.

Implemented by the user to return a hash code for t, subject to the requirements specified in hash.
private Object
Inherited from com.google.common.base.Equivalence:
equalsequivalentequivalentTohashidentityonResultOfpairwisetestwrap

Field Detail

INSTANCEback to summary
pack-priv static final Equivalence.Identity INSTANCE
serialVersionUIDback to summary
private static final long serialVersionUID

Constructor Detail

Identityback to summary
pack-priv Identity()

Method Detail

doEquivalentback to summary
protected boolean doEquivalent(Object a, Object b)

Implements abstract com.google.common.base.Equivalence.doEquivalent.

Doc from com.google.common.base.Equivalence.doEquivalent.

Implemented by the user to determine whether a and b are considered equivalent, subject to the requirements specified in equivalent.

This method should not be called except by equivalent. When equivalent calls this method, a and b are guaranteed to be distinct, non-null instances.

Annotations
@Override
doHashback to summary
protected int doHash(Object o)

Implements abstract com.google.common.base.Equivalence.doHash.

Doc from com.google.common.base.Equivalence.doHash.

Implemented by the user to return a hash code for t, subject to the requirements specified in hash.

This method should not be called except by hash. When hash calls this method, t is guaranteed to be non-null.

Annotations
@Override
readResolveback to summary
private Object readResolve()
com.google.common.base back to summary

public final Class Equivalence.Wrapper<T extends @Nullable Object>

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable

Wraps an object so that equals(Object) and hashCode() delegate to an Equivalence.

For example, given an Equivalence for strings named equiv that tests equivalence using their lengths:

equiv.wrap("a").equals(equiv.wrap("b")) // true
equiv.wrap("a").equals(equiv.wrap("hello")) // false

Note in particular that an equivalence wrapper is never equal to the object it wraps.

equiv.wrap(obj).equals(obj) // always false
Since
10.0

Field Summary

Modifier and TypeField and Description
private final Equivalence<? super @NonNull T>
private final T
private static final long

Constructor Summary

AccessConstructor and Description
private
Wrapper(Equivalence<? super @NonNull T> equivalence, T reference)

Method Summary

Modifier and TypeMethod and Description
public boolean
equals(Object
the reference object with which to compare.
obj
)

Overrides java.lang.Object.equals.

Returns true if Equivalence#equivalent(Object, Object) applied to the wrapped references is true and both wrappers use the same equivalence.
public T
get()

Returns the (possibly null) reference wrapped by this instance.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns the result of Equivalence#hash(Object) applied to the wrapped reference.
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation for this equivalence wrapper.
Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

equivalenceback to summary
private final Equivalence<? super @NonNull T> equivalence
referenceback to summary
private final T reference
Annotations
@ParametricNullness
serialVersionUIDback to summary
private static final long serialVersionUID

Constructor Detail

Wrapperback to summary
private Wrapper(Equivalence<? super @NonNull T> equivalence, T reference)

Method Detail

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Returns true if Equivalence#equivalent(Object, Object) applied to the wrapped references is true and both wrappers use the same equivalence.

Parameters
obj:Object

Doc from java.lang.Object.equals.

the reference object with which to compare.

Returns:boolean

Doc from java.lang.Object.equals.

true if this object is the same as the obj argument; false otherwise.

Annotations
@Override
getback to summary
public T get()

Returns the (possibly null) reference wrapped by this instance.

Annotations
@ParametricNullness
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Returns the result of Equivalence#hash(Object) applied to the wrapped reference.

Returns:int

Doc from java.lang.Object.hashCode.

a hash code value for this object

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a string representation for this equivalence wrapper. The form of this string representation is not specified.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object

Annotations
@Override