001 /*
002 * Copyright (C) 2010 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package com.google.common.base;
018
019 import static com.google.common.base.Preconditions.checkNotNull;
020
021 import com.google.common.annotations.Beta;
022 import com.google.common.annotations.GwtCompatible;
023
024 import java.io.Serializable;
025
026 import javax.annotation.Nullable;
027
028 /**
029 * A strategy for determining whether two instances are considered equivalent. Examples of
030 * equivalences are the {@link Equivalences#identity() identity equivalence} and {@link
031 * Equivalences#equals equals equivalence}.
032 *
033 * @author Bob Lee
034 * @author Ben Yu
035 * @author Gregory Kick
036 * @since 10.0 (<a href="http://code.google.com/p/guava-libraries/wiki/Compatibility"
037 * >mostly source-compatible</a> since 4.0)
038 */
039 @GwtCompatible
040 public abstract class Equivalence<T> {
041 /**
042 * Constructor for use by subclasses.
043 */
044 protected Equivalence() {}
045
046 /**
047 * Returns {@code true} if the given objects are considered equivalent.
048 *
049 * <p>The {@code equivalent} method implements an equivalence relation on object references:
050 *
051 * <ul>
052 * <li>It is <i>reflexive</i>: for any reference {@code x}, including null, {@code
053 * equivalent(x, x)} returns {@code true}.
054 * <li>It is <i>symmetric</i>: for any references {@code x} and {@code y}, {@code
055 * equivalent(x, y) == equivalent(y, x)}.
056 * <li>It is <i>transitive</i>: for any references {@code x}, {@code y}, and {@code z}, if
057 * {@code equivalent(x, y)} returns {@code true} and {@code equivalent(y, z)} returns {@code
058 * true}, then {@code equivalent(x, z)} returns {@code true}.
059 * <li>It is <i>consistent</i>: for any references {@code x} and {@code y}, multiple invocations
060 * of {@code equivalent(x, y)} consistently return {@code true} or consistently return {@code
061 * false} (provided that neither {@code x} nor {@code y} is modified).
062 * </ul>
063 */
064 public final boolean equivalent(@Nullable T a, @Nullable T b) {
065 if (a == b) {
066 return true;
067 }
068 if (a == null || b == null) {
069 return false;
070 }
071 return doEquivalent(a, b);
072 }
073
074 /**
075 * Returns {@code true} if {@code a} and {@code b} are considered equivalent.
076 *
077 * <p>Called by {@link #equivalent}. {@code a} and {@code b} are not the same
078 * object and are not nulls.
079 *
080 * @since 10.0 (previously, subclasses would override equivalent())
081 */
082 protected abstract boolean doEquivalent(T a, T b);
083
084 /**
085 * Returns a hash code for {@code t}.
086 *
087 * <p>The {@code hash} has the following properties:
088 * <ul>
089 * <li>It is <i>consistent</i>: for any reference {@code x}, multiple invocations of
090 * {@code hash(x}} consistently return the same value provided {@code x} remains unchanged
091 * according to the definition of the equivalence. The hash need not remain consistent from
092 * one execution of an application to another execution of the same application.
093 * <li>It is <i>distributable accross equivalence</i>: for any references {@code x} and {@code y},
094 * if {@code equivalent(x, y)}, then {@code hash(x) == hash(y)}. It is <i>not</i> necessary
095 * that the hash be distributable accorss <i>inequivalence</i>. If {@code equivalence(x, y)}
096 * is false, {@code hash(x) == hash(y)} may still be true.
097 * <li>{@code hash(null)} is {@code 0}.
098 * </ul>
099 */
100 public final int hash(@Nullable T t) {
101 if (t == null) {
102 return 0;
103 }
104 return doHash(t);
105 }
106
107 /**
108 * Returns a hash code for non-null object {@code t}.
109 *
110 * <p>Called by {@link #hash}.
111 *
112 * @since 10.0 (previously, subclasses would override hash())
113 */
114 protected abstract int doHash(T t);
115
116 /**
117 * Returns a new equivalence relation for {@code F} which evaluates equivalence by first applying
118 * {@code function} to the argument, then evaluating using {@code this}. That is, for any pair of
119 * non-null objects {@code x} and {@code y}, {@code
120 * equivalence.onResultOf(function).equivalent(a, b)} is true if and only if {@code
121 * equivalence.equivalent(function.apply(a), function.apply(b))} is true.
122 *
123 * <p>For example: <pre> {@code
124 *
125 * Equivalence<Person> SAME_AGE = Equivalences.equals().onResultOf(GET_PERSON_AGE);
126 * }</pre>
127 *
128 * <p>{@code function} will never be invoked with a null value.
129 *
130 * <p>Note that {@code function} must be consistent according to {@code this} equivalence
131 * relation. That is, invoking {@link Function#apply} multiple times for a given value must return
132 * equivalent results.
133 * For example, {@code Equivalences.identity().onResultOf(Functions.toStringFunction())} is broken
134 * because it's not guaranteed that {@link Object#toString}) always returns the same string
135 * instance.
136 *
137 * @since 10.0
138 */
139 public final <F> Equivalence<F> onResultOf(Function<F, ? extends T> function) {
140 return new FunctionalEquivalence<F, T>(function, this);
141 }
142
143 /**
144 * Returns a wrapper of {@code reference} that implements
145 * {@link Wrapper#equals(Object) Object.equals()} such that
146 * {@code wrap(this, a).equals(wrap(this, b))} if and only if {@code this.equivalent(a, b)}.
147 *
148 * @since 10.0
149 */
150 public final <S extends T> Wrapper<S> wrap(@Nullable S reference) {
151 return new Wrapper<S>(this, reference);
152 }
153
154 /**
155 * Wraps an object so that {@link #equals(Object)} and {@link #hashCode()} delegate to an
156 * {@link Equivalence}.
157 *
158 * <p>For example, given an {@link Equivalence} for {@link String strings} named {@code equiv}
159 * that tests equivalence using their lengths:
160 *
161 * <pre> {@code
162 * equiv.wrap("a").equals(equiv.wrap("b")) // true
163 * equiv.wrap("a").equals(equiv.wrap("hello")) // false
164 * }</pre>
165 *
166 * <p>Note in particular that an equivalence wrapper is never equal to the object it wraps.
167 *
168 * <pre> {@code
169 * equiv.wrap(obj).equals(obj) // always false
170 * }</pre>
171 *
172 * @since 10.0
173 */
174 public static final class Wrapper<T> implements Serializable {
175 private final Equivalence<? super T> equivalence;
176 @Nullable private final T reference;
177
178 private Wrapper(Equivalence<? super T> equivalence, @Nullable T reference) {
179 this.equivalence = checkNotNull(equivalence);
180 this.reference = reference;
181 }
182
183 /** Returns the (possibly null) reference wrapped by this instance. */
184 @Nullable public T get() {
185 return reference;
186 }
187
188 /**
189 * Returns {@code true} if {@link Equivalence#equivalent(Object, Object)} applied to the wrapped
190 * references is {@code true} and both wrappers use the {@link Object#equals(Object) same}
191 * equivalence.
192 */
193 @Override public boolean equals(@Nullable Object obj) {
194 if (obj == this) {
195 return true;
196 } else if (obj instanceof Wrapper) {
197 Wrapper<?> that = (Wrapper<?>) obj;
198 /*
199 * We cast to Equivalence<Object> here because we can't check the type of the reference held
200 * by the other wrapper. But, by checking that the Equivalences are equal, we know that
201 * whatever type it is, it is assignable to the type handled by this wrapper's equivalence.
202 */
203 @SuppressWarnings("unchecked")
204 Equivalence<Object> equivalence = (Equivalence<Object>) this.equivalence;
205 return equivalence.equals(that.equivalence)
206 && equivalence.equivalent(this.reference, that.reference);
207 } else {
208 return false;
209 }
210 }
211
212 /**
213 * Returns the result of {@link Equivalence#hash(Object)} applied to the the wrapped reference.
214 */
215 @Override public int hashCode() {
216 return equivalence.hash(reference);
217 }
218
219 /**
220 * Returns a string representation for this equivalence wrapper. The form of this string
221 * representation is not specified.
222 */
223 @Override public String toString() {
224 return equivalence + ".wrap(" + reference + ")";
225 }
226
227 private static final long serialVersionUID = 0;
228 }
229
230 /**
231 * Returns an equivalence over iterables based on the equivalence of their elements. More
232 * specifically, two iterables are considered equivalent if they both contain the same number of
233 * elements, and each pair of corresponding elements is equivalent according to
234 * {@code this}. Null iterables are equivalent to one another.
235 *
236 * <p>Note that this method performs a similar function for equivalences as {@link
237 * com.google.common.collect.Ordering#lexicographical} does for orderings.
238 *
239 * @since 10.0
240 */
241 @GwtCompatible(serializable = true)
242 public final <S extends T> Equivalence<Iterable<S>> pairwise() {
243 // Ideally, the returned equivalence would support Iterable<? extends T>. However,
244 // the need for this is so rare that it's not worth making callers deal with the ugly wildcard.
245 return new PairwiseEquivalence<S>(this);
246 }
247
248 /**
249 * Returns a predicate that evaluates to true if and only if the input is
250 * equivalent to {@code target} according to this equivalence relation.
251 *
252 * @since 10.0
253 */
254 @Beta
255 public final Predicate<T> equivalentTo(@Nullable T target) {
256 return new EquivalentToPredicate<T>(this, target);
257 }
258
259 private static final class EquivalentToPredicate<T> implements Predicate<T>, Serializable {
260
261 private final Equivalence<T> equivalence;
262 @Nullable private final T target;
263
264 EquivalentToPredicate(Equivalence<T> equivalence, @Nullable T target) {
265 this.equivalence = checkNotNull(equivalence);
266 this.target = target;
267 }
268
269 @Override public boolean apply(@Nullable T input) {
270 return equivalence.equivalent(input, target);
271 }
272
273 @Override public boolean equals(@Nullable Object obj) {
274 if (this == obj) {
275 return true;
276 }
277 if (obj instanceof EquivalentToPredicate) {
278 EquivalentToPredicate<?> that = (EquivalentToPredicate<?>) obj;
279 return equivalence.equals(that.equivalence)
280 && Objects.equal(target, that.target);
281 }
282 return false;
283 }
284
285 @Override public int hashCode() {
286 return Objects.hashCode(equivalence, target);
287 }
288
289 @Override public String toString() {
290 return equivalence + ".equivalentTo(" + target + ")";
291 }
292
293 private static final long serialVersionUID = 0;
294 }
295
296 /**
297 * Returns an equivalence that delegates to {@link Object#equals} and {@link Object#hashCode}.
298 * {@link Equivalence#equivalent} returns {@code true} if both values are null, or if neither
299 * value is null and {@link Object#equals} returns {@code true}. {@link Equivalence#hash} returns
300 * {@code 0} if passed a null value.
301 *
302 * @since 13.0
303 * @since 8.0 (in Equivalences with null-friendly behavior)
304 * @since 4.0 (in Equivalences)
305 */
306 public static Equivalence<Object> equals() {
307 return Equals.INSTANCE;
308 }
309
310 /**
311 * Returns an equivalence that uses {@code ==} to compare values and {@link
312 * System#identityHashCode(Object)} to compute the hash code. {@link Equivalence#equivalent}
313 * returns {@code true} if {@code a == b}, including in the case that a and b are both null.
314 *
315 * @since 13.0
316 * @since 4.0 (in Equivalences)
317 */
318 public static Equivalence<Object> identity() {
319 return Identity.INSTANCE;
320 }
321
322 static final class Equals extends Equivalence<Object>
323 implements Serializable {
324
325 static final Equals INSTANCE = new Equals();
326
327 @Override protected boolean doEquivalent(Object a, Object b) {
328 return a.equals(b);
329 }
330 @Override public int doHash(Object o) {
331 return o.hashCode();
332 }
333
334 private Object readResolve() {
335 return INSTANCE;
336 }
337 private static final long serialVersionUID = 1;
338 }
339
340 static final class Identity extends Equivalence<Object>
341 implements Serializable {
342
343 static final Identity INSTANCE = new Identity();
344
345 @Override protected boolean doEquivalent(Object a, Object b) {
346 return false;
347 }
348
349 @Override protected int doHash(Object o) {
350 return System.identityHashCode(o);
351 }
352
353 private Object readResolve() {
354 return INSTANCE;
355 }
356 private static final long serialVersionUID = 1;
357 }
358 }