All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.base.Equivalence Maven / Gradle / Ivy

/*
 * Copyright (C) 2010 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.common.base;

import static com.google.common.base.Preconditions.checkNotNull;

import com.google.common.annotations.GwtCompatible;
import com.google.errorprone.annotations.ForOverride;
import java.io.Serializable;
import org.checkerframework.checker.nullness.compatqual.NullableDecl;

/**
 * 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
 * {@linkplain #identity() identity equivalence} and the {@linkplain #equals "equals" equivalence}.
 *
 * 

For users targeting Android API level 24 or higher: This class will eventually * implement {@code BiPredicate} (as it does in the main Guava artifact), but we currently * target a lower API level. In the meantime, if you have support for method references you can use * an equivalence as a bi-predicate like this: {@code myEquivalence::equivalent}. * * @author Bob Lee * @author Ben Yu * @author Gregory Kick * @since 10.0 (mostly * source-compatible since 4.0) */ @GwtCompatible public abstract class Equivalence { /** Constructor for use by subclasses. */ protected Equivalence() {} /** * Returns {@code true} if the given objects are considered equivalent. * *

This method describes an equivalence relation on object references, meaning that for * all references {@code x}, {@code y}, and {@code z} (any of which may be null): * *

    *
  • {@code equivalent(x, x)} is true (reflexive property) *
  • {@code equivalent(x, y)} and {@code equivalent(y, x)} each return the same result * (symmetric property) *
  • If {@code equivalent(x, y)} and {@code equivalent(y, z)} are both true, then {@code * equivalent(x, z)} is also true (transitive property) *
* *

Note that all calls to {@code equivalent(x, y)} are expected to return the same result as * long as neither {@code x} nor {@code y} is modified. */ public final boolean equivalent(@NullableDecl T a, @NullableDecl T b) { if (a == b) { return true; } if (a == null || b == null) { return false; } return doEquivalent(a, b); } /** * This method should not be called except by {@link #equivalent}. When {@link #equivalent} calls * this method, {@code a} and {@code b} are guaranteed to be distinct, non-null instances. * * @since 10.0 (previously, subclasses would override equivalent()) */ @ForOverride protected abstract boolean doEquivalent(T a, T b); /** * Returns a hash code for {@code t}. * *

The {@code hash} has the following properties: * *

    *
  • It is consistent: for any reference {@code x}, multiple invocations of {@code * hash(x}} consistently return the same value provided {@code 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 {@code x} and {@code * y}, if {@code equivalent(x, y)}, then {@code hash(x) == hash(y)}. It is not * necessary that the hash be distributable across inequivalence. If {@code * equivalence(x, y)} is false, {@code hash(x) == hash(y)} may still be true. *
  • {@code hash(null)} is {@code 0}. *
*/ public final int hash(@NullableDecl T t) { if (t == null) { return 0; } return doHash(t); } /** * Implemented by the user to return a hash code for {@code t}, subject to the requirements * specified in {@link #hash}. * *

This method should not be called except by {@link #hash}. When {@link #hash} calls this * method, {@code t} is guaranteed to be non-null. * * @since 10.0 (previously, subclasses would override hash()) */ @ForOverride protected abstract int doHash(T t); /** * Returns a new equivalence relation for {@code F} which evaluates equivalence by first applying * {@code function} to the argument, then evaluating using {@code this}. That is, for any pair of * non-null objects {@code x} and {@code y}, {@code equivalence.onResultOf(function).equivalent(a, * b)} is true if and only if {@code equivalence.equivalent(function.apply(a), function.apply(b))} * is true. * *

For example: * *

{@code
   * Equivalence SAME_AGE = Equivalence.equals().onResultOf(GET_PERSON_AGE);
   * }
* *

{@code function} will never be invoked with a null value. * *

Note that {@code function} must be consistent according to {@code this} equivalence * relation. That is, invoking {@link Function#apply} multiple times for a given value must return * equivalent results. For example, {@code * Equivalence.identity().onResultOf(Functions.toStringFunction())} is broken because it's not * guaranteed that {@link Object#toString}) always returns the same string instance. * * @since 10.0 */ public final Equivalence onResultOf(Function function) { return new FunctionalEquivalence<>(function, this); } /** * Returns a wrapper of {@code reference} that implements {@link Wrapper#equals(Object) * Object.equals()} such that {@code wrap(a).equals(wrap(b))} if and only if {@code equivalent(a, * b)}. * * @since 10.0 */ public final Wrapper wrap(@NullableDecl S reference) { return new Wrapper(this, reference); } /** * Wraps an object so that {@link #equals(Object)} and {@link #hashCode()} delegate to an {@link * Equivalence}. * *

For example, given an {@link Equivalence} for {@link String strings} named {@code equiv} * that tests equivalence using their lengths: * *

{@code
   * 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. * *

{@code
   * equiv.wrap(obj).equals(obj) // always false
   * }
* * @since 10.0 */ public static final class Wrapper implements Serializable { private final Equivalence equivalence; @NullableDecl private final T reference; private Wrapper(Equivalence equivalence, @NullableDecl T reference) { this.equivalence = checkNotNull(equivalence); this.reference = reference; } /** Returns the (possibly null) reference wrapped by this instance. */ @NullableDecl public T get() { return reference; } /** * Returns {@code true} if {@link Equivalence#equivalent(Object, Object)} applied to the wrapped * references is {@code true} and both wrappers use the {@link Object#equals(Object) same} * equivalence. */ @Override public boolean equals(@NullableDecl Object obj) { if (obj == this) { return true; } if (obj instanceof Wrapper) { Wrapper that = (Wrapper) obj; // note: not necessarily a Wrapper if (this.equivalence.equals(that.equivalence)) { /* * We'll accept that as sufficient "proof" that either equivalence should be able to * handle either reference, so it's safe to circumvent compile-time type checking. */ @SuppressWarnings("unchecked") Equivalence equivalence = (Equivalence) this.equivalence; return equivalence.equivalent(this.reference, that.reference); } } return false; } /** Returns the result of {@link Equivalence#hash(Object)} applied to the wrapped reference. */ @Override public int hashCode() { return equivalence.hash(reference); } /** * Returns a string representation for this equivalence wrapper. The form of this string * representation is not specified. */ @Override public String toString() { return equivalence + ".wrap(" + reference + ")"; } private static final long serialVersionUID = 0; } /** * 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 {@code this}. Null * iterables are equivalent to one another. * *

Note that this method performs a similar function for equivalences as {@link * com.google.common.collect.Ordering#lexicographical} does for orderings. * * @since 10.0 */ @GwtCompatible(serializable = true) public final Equivalence> pairwise() { // Ideally, the returned equivalence would support Iterable. However, // the need for this is so rare that it's not worth making callers deal with the ugly wildcard. return new PairwiseEquivalence(this); } /** * Returns a predicate that evaluates to true if and only if the input is equivalent to {@code * target} according to this equivalence relation. * * @since 10.0 */ public final Predicate equivalentTo(@NullableDecl T target) { return new EquivalentToPredicate(this, target); } private static final class EquivalentToPredicate implements Predicate, Serializable { private final Equivalence equivalence; @NullableDecl private final T target; EquivalentToPredicate(Equivalence equivalence, @NullableDecl T target) { this.equivalence = checkNotNull(equivalence); this.target = target; } @Override public boolean apply(@NullableDecl T input) { return equivalence.equivalent(input, target); } @Override public boolean equals(@NullableDecl Object obj) { if (this == obj) { return true; } if (obj instanceof EquivalentToPredicate) { EquivalentToPredicate that = (EquivalentToPredicate) obj; return equivalence.equals(that.equivalence) && Objects.equal(target, that.target); } return false; } @Override public int hashCode() { return Objects.hashCode(equivalence, target); } @Override public String toString() { return equivalence + ".equivalentTo(" + target + ")"; } private static final long serialVersionUID = 0; } /** * Returns an equivalence that delegates to {@link Object#equals} and {@link Object#hashCode}. * {@link Equivalence#equivalent} returns {@code true} if both values are null, or if neither * value is null and {@link Object#equals} returns {@code true}. {@link Equivalence#hash} returns * {@code 0} if passed a null value. * * @since 13.0 * @since 8.0 (in Equivalences with null-friendly behavior) * @since 4.0 (in Equivalences) */ public static Equivalence equals() { return Equals.INSTANCE; } /** * Returns an equivalence that uses {@code ==} to compare values and {@link * System#identityHashCode(Object)} to compute the hash code. {@link Equivalence#equivalent} * returns {@code true} if {@code a == b}, including in the case that a and b are both null. * * @since 13.0 * @since 4.0 (in Equivalences) */ public static Equivalence identity() { return Identity.INSTANCE; } static final class Equals extends Equivalence implements Serializable { static final Equals INSTANCE = new Equals(); @Override protected boolean doEquivalent(Object a, Object b) { return a.equals(b); } @Override protected int doHash(Object o) { return o.hashCode(); } private Object readResolve() { return INSTANCE; } private static final long serialVersionUID = 1; } static final class Identity extends Equivalence implements Serializable { static final Identity INSTANCE = new Identity(); @Override protected boolean doEquivalent(Object a, Object b) { return false; } @Override protected int doHash(Object o) { return System.identityHashCode(o); } private Object readResolve() { return INSTANCE; } private static final long serialVersionUID = 1; } }