1/*
2 * Copyright (C) 2010 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.google.common.base;
18
19import static com.google.common.base.Preconditions.checkNotNull;
20
21import com.google.common.annotations.Beta;
22import com.google.common.annotations.GwtCompatible;
23
24import java.io.Serializable;
25
26import javax.annotation.Nullable;
27
28/**
29 * A strategy for determining whether two instances are considered equivalent. Examples of
30 * equivalences are the {@link Equivalences#identity() identity equivalence} and {@link
31 * Equivalences#equals equals equivalence}.
32 *
33 * @author Bob Lee
34 * @author Ben Yu
35 * @author Gregory Kick
36 * @since 10.0 (<a href="http://code.google.com/p/guava-libraries/wiki/Compatibility"
37 *        >mostly source-compatible</a> since 4.0)
38 */
39@Beta
40@GwtCompatible
41public abstract class Equivalence<T> {
42  /**
43   * Constructor for use by subclasses.
44   */
45  protected Equivalence() {}
46
47  /**
48   * Returns {@code true} if the given objects are considered equivalent.
49   *
50   * <p>The {@code equivalent} method implements an equivalence relation on object references:
51   *
52   * <ul>
53   * <li>It is <i>reflexive</i>: for any reference {@code x}, including null, {@code
54   *     equivalent(x, x)} returns {@code true}.
55   * <li>It is <i>symmetric</i>: for any references {@code x} and {@code y}, {@code
56   *     equivalent(x, y) == equivalent(y, x)}.
57   * <li>It is <i>transitive</i>: for any references {@code x}, {@code y}, and {@code z}, if
58   *     {@code equivalent(x, y)} returns {@code true} and {@code equivalent(y, z)} returns {@code
59   *     true}, then {@code equivalent(x, z)} returns {@code true}.
60   * <li>It is <i>consistent</i>: for any references {@code x} and {@code y}, multiple invocations
61   *     of {@code equivalent(x, y)} consistently return {@code true} or consistently return {@code
62   *     false} (provided that neither {@code x} nor {@code y} is modified).
63   * </ul>
64   */
65  public final boolean equivalent(@Nullable T a, @Nullable T b) {
66    if (a == b) {
67      return true;
68    }
69    if (a == null || b == null) {
70      return false;
71    }
72    return doEquivalent(a, b);
73  }
74
75  /**
76   * Returns {@code true} if {@code a} and {@code b} are considered equivalent.
77   *
78   * <p>Called by {@link #equivalent}. {@code a} and {@code b} are not the same
79   * object and are not nulls.
80   *
81   * @since 10.0 (previously, subclasses would override equivalent())
82   */
83  protected abstract boolean doEquivalent(T a, T b);
84
85  /**
86   * Returns a hash code for {@code t}.
87   *
88   * <p>The {@code hash} has the following properties:
89   * <ul>
90   * <li>It is <i>consistent</i>: for any reference {@code x}, multiple invocations of
91   *     {@code hash(x}} consistently return the same value provided {@code x} remains unchanged
92   *     according to the definition of the equivalence. The hash need not remain consistent from
93   *     one execution of an application to another execution of the same application.
94   * <li>It is <i>distributable accross equivalence</i>: for any references {@code x} and {@code y},
95   *     if {@code equivalent(x, y)}, then {@code hash(x) == hash(y)}. It is <i>not</i> necessary
96   *     that the hash be distributable accorss <i>inequivalence</i>. If {@code equivalence(x, y)}
97   *     is false, {@code hash(x) == hash(y)} may still be true.
98   * <li>{@code hash(null)} is {@code 0}.
99   * </ul>
100   */
101  public final int hash(@Nullable T t) {
102    if (t == null) {
103      return 0;
104    }
105    return doHash(t);
106  }
107
108  /**
109   * Returns a hash code for non-null object {@code t}.
110   *
111   * <p>Called by {@link #hash}.
112   *
113   * @since 10.0 (previously, subclasses would override hash())
114   */
115  protected abstract int doHash(T t);
116
117  /**
118   * Returns a new equivalence relation for {@code F} which evaluates equivalence by first applying
119   * {@code function} to the argument, then evaluating using {@code this}. That is, for any pair of
120   * non-null objects {@code x} and {@code y}, {@code
121   * equivalence.onResultOf(function).equivalent(a, b)} is true if and only if {@code
122   * equivalence.equivalent(function.apply(a), function.apply(b))} is true.
123   *
124   * <p>For example: <pre>   {@code
125   *
126   *    Equivalence<Person> SAME_AGE = Equivalences.equals().onResultOf(GET_PERSON_AGE);
127   * }</pre>
128   *
129   * <p>{@code function} will never be invoked with a null value.
130   *
131   * <p>Note that {@code function} must be consistent according to {@code this} equivalence
132   * relation. That is, invoking {@link Function#apply} multiple times for a given value must return
133   * equivalent results.
134   * For example, {@code Equivalences.identity().onResultOf(Functions.toStringFunction())} is broken
135   * because it's not guaranteed that {@link Object#toString}) always returns the same string
136   * instance.
137   *
138   * @since 10.0
139   */
140  public final <F> Equivalence<F> onResultOf(Function<F, ? extends T> function) {
141    return new FunctionalEquivalence<F, T>(function, this);
142  }
143
144  /**
145   * Returns a wrapper of {@code reference} that implements
146   * {@link Wrapper#equals(Object) Object.equals()} such that
147   * {@code wrap(this, a).equals(wrap(this, b))} if and only if {@code this.equivalent(a, b)}.
148   *
149   * @since 10.0
150   */
151  public final <S extends T> Wrapper<S> wrap(@Nullable S reference) {
152    return new Wrapper<S>(this, reference);
153  }
154
155  /**
156   * Wraps an object so that {@link #equals(Object)} and {@link #hashCode()} delegate to an
157   * {@link Equivalence}.
158   *
159   * <p>For example, given an {@link Equivalence} for {@link String strings} named {@code equiv}
160   * that tests equivalence using their lengths:
161   *
162   * <pre>   {@code
163   *   equiv.wrap("a").equals(equiv.wrap("b")) // true
164   *   equiv.wrap("a").equals(equiv.wrap("hello")) // false
165   * }</pre>
166   *
167   * <p>Note in particular that an equivalence wrapper is never equal to the object it wraps.
168   *
169   * <pre>   {@code
170   *   equiv.wrap(obj).equals(obj) // always false
171   * }</pre>
172   *
173   * @since 10.0
174   */
175  @Beta
176  public static final class Wrapper<T> implements Serializable {
177    private final Equivalence<? super T> equivalence;
178    @Nullable private final T reference;
179
180    private Wrapper(Equivalence<? super T> equivalence, @Nullable T reference) {
181      this.equivalence = checkNotNull(equivalence);
182      this.reference = reference;
183    }
184
185    /** Returns the (possibly null) reference wrapped by this instance. */
186    @Nullable public T get() {
187      return reference;
188    }
189
190    /**
191     * Returns {@code true} if {@link Equivalence#equivalent(Object, Object)} applied to the wrapped
192     * references is {@code true} and both wrappers use the {@link Object#equals(Object) same}
193     * equivalence.
194     */
195    @Override public boolean equals(@Nullable Object obj) {
196      if (obj == this) {
197        return true;
198      } else if (obj instanceof Wrapper) {
199        Wrapper<?> that = (Wrapper<?>) obj;
200        /*
201         * We cast to Equivalence<Object> here because we can't check the type of the reference held
202         * by the other wrapper.  But, by checking that the Equivalences are equal, we know that
203         * whatever type it is, it is assignable to the type handled by this wrapper's equivalence.
204         */
205        @SuppressWarnings("unchecked")
206        Equivalence<Object> equivalence = (Equivalence<Object>) this.equivalence;
207        return equivalence.equals(that.equivalence)
208            && equivalence.equivalent(this.reference, that.reference);
209      } else {
210        return false;
211      }
212    }
213
214    /**
215     * Returns the result of {@link Equivalence#hash(Object)} applied to the the wrapped reference.
216     */
217    @Override public int hashCode() {
218      return equivalence.hash(reference);
219    }
220
221    /**
222     * Returns a string representation for this equivalence wrapper. The form of this string
223     * representation is not specified.
224     */
225    @Override public String toString() {
226      return equivalence + ".wrap(" + reference + ")";
227    }
228
229    private static final long serialVersionUID = 0;
230  }
231
232  /**
233   * Returns an equivalence over iterables based on the equivalence of their elements.  More
234   * specifically, two iterables are considered equivalent if they both contain the same number of
235   * elements, and each pair of corresponding elements is equivalent according to
236   * {@code this}.  Null iterables are equivalent to one another.
237   *
238   * <p>Note that this method performs a similar function for equivalences as {@link
239   * com.google.common.collect.Ordering#lexicographical} does for orderings.
240   *
241   * @since 10.0
242   */
243  @GwtCompatible(serializable = true)
244  public final <S extends T> Equivalence<Iterable<S>> pairwise() {
245    // Ideally, the returned equivalence would support Iterable<? extends T>. However,
246    // the need for this is so rare that it's not worth making callers deal with the ugly wildcard.
247    return new PairwiseEquivalence<S>(this);
248  }
249
250  /**
251   * Returns a predicate that evaluates to true if and only if the input is
252   * equivalent to {@code target} according to this equivalence relation.
253   *
254   * @since 10.0
255   */
256  public final Predicate<T> equivalentTo(@Nullable T target) {
257    return new EquivalentToPredicate<T>(this, target);
258  }
259
260  private static final class EquivalentToPredicate<T> implements Predicate<T>, Serializable {
261
262    private final Equivalence<T> equivalence;
263    @Nullable private final T target;
264
265    EquivalentToPredicate(Equivalence<T> equivalence, @Nullable T target) {
266      this.equivalence = checkNotNull(equivalence);
267      this.target = target;
268    }
269
270    @Override public boolean apply(@Nullable T input) {
271      return equivalence.equivalent(input, target);
272    }
273
274    @Override public boolean equals(@Nullable Object obj) {
275      if (this == obj) {
276        return true;
277      }
278      if (obj instanceof EquivalentToPredicate) {
279        EquivalentToPredicate<?> that = (EquivalentToPredicate<?>) obj;
280        return equivalence.equals(that.equivalence)
281            && Objects.equal(target, that.target);
282      }
283      return false;
284    }
285
286    @Override public int hashCode() {
287      return Objects.hashCode(equivalence, target);
288    }
289
290    @Override public String toString() {
291      return equivalence + ".equivalentTo(" + target + ")";
292    }
293
294    private static final long serialVersionUID = 0;
295  }
296}
297