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

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

Go to download

Guava is a suite of core and expanded libraries that include utility classes, google's collections, io classes, and much much more.

There is a newer version: 33.3.0-jre
Show newest version
/*
 * 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 javax.annotation.CheckForNull;
import org.checkerframework.checker.nullness.qual.NonNull;
import org.checkerframework.checker.nullness.qual.Nullable;

/**
 * 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
@ElementTypesAreNonnullByDefault
/*
 * The type parameter is  rather than  so that we can use T in the
 * doEquivalent and doHash methods to indicate that the parameter cannot be null.
 */
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(@CheckForNull T a, @CheckForNull T b) {
    if (a == b) {
      return true;
    }
    if (a == null || b == null) {
      return false;
    }
    return doEquivalent(a, b);
  }

  /**
   *
   * @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(@CheckForNull 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)}.
   *
   * 
The returned object is serializable if both this {@code Equivalence} and {@code reference}
   * are serializable (including when {@code reference} is null).
   *
   * @since 10.0
   */
  public final  Wrapper wrap(@ParametricNullness 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 {
    /*
     * Equivalence's type argument is always non-nullable: Equivalence, never
     * Equivalence<@Nullable Number>. That can still produce wrappers of various types --
     * Wrapper, Wrapper, Wrapper<@Nullable Integer>, etc. If we used just
     * Equivalence below, no type could satisfy both that bound and T's own
     * bound. With this type, they have some overlap: in our example, Equivalence
     * and Equivalence.
     */
    private final Equivalence equivalence;

    @ParametricNullness private final T reference;

    private Wrapper(Equivalence equivalence, @ParametricNullness T reference) {
      this.equivalence = checkNotNull(equivalence);
      this.reference = reference;
    }

    /** Returns the (possibly null) reference wrapped by this instance. */
    @ParametricNullness
    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(@CheckForNull 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.
   *
   * 
The returned object is serializable if this object is serializable.
   *
   * @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<@Nullable T> equivalentTo(@CheckForNull T target) {
    return new EquivalentToPredicate(this, target);
  }

  private static final class EquivalentToPredicate
      implements Predicate<@Nullable T>, Serializable {

    private final Equivalence equivalence;
    @CheckForNull private final T target;

    EquivalentToPredicate(Equivalence equivalence, @CheckForNull T target) {
      this.equivalence = checkNotNull(equivalence);
      this.target = target;
    }

    @Override
    public boolean apply(@CheckForNull T input) {
      return equivalence.equivalent(input, target);
    }

    @Override
    public boolean equals(@CheckForNull 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;
  }
}
    

    

    
            
    
            







    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy