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

The 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.Beta;
import com.google.common.annotations.GwtCompatible;

import java.io.Serializable;

import javax.annotation.Nullable;

/**
 * A strategy for determining whether two instances are considered equivalent. Examples of
 * equivalences are the {@link Equivalences#identity() identity equivalence} and {@link
 * Equivalences#equals equals equivalence}.
 *
 * @author Bob Lee
 * @author Ben Yu
 * @author Gregory Kick
 * @since 10.0 (mostly source-compatible since 4.0)
 */
@Beta
@GwtCompatible
public abstract class Equivalence {
  /**
   * Constructor for use by subclasses.
   */
  protected Equivalence() {}

  /**
   * Returns {@code true} if the given objects are considered equivalent.
   *
   * 
The {@code equivalent} method implements an equivalence relation on object references:
   *
   * 
    
   * 
  • It is reflexive: for any reference {@code x}, including null, {@code
   *     equivalent(x, x)} returns {@code true}.
   * 
  • It is symmetric: for any references {@code x} and {@code y}, {@code
   *     equivalent(x, y) == equivalent(y, x)}.
   * 
  • It is transitive: for any references {@code x}, {@code y}, and {@code z}, if
   *     {@code equivalent(x, y)} returns {@code true} and {@code equivalent(y, z)} returns {@code
   *     true}, then {@code equivalent(x, z)} returns {@code true}.
   * 
  • It is consistent: for any references {@code x} and {@code y}, multiple invocations
   *     of {@code equivalent(x, y)} consistently return {@code true} or consistently return {@code
   *     false} (provided that neither {@code x} nor {@code y} is modified).
   * 

   */
  public final boolean equivalent(@Nullable T a, @Nullable T b) {
    if (a == b) {
      return true;
    }
    if (a == null || b == null) {
      return false;
    }
    return doEquivalent(a, b);
  }

  /**
   * Returns {@code true} if {@code a} and {@code b} are considered equivalent.
   *
   * 
Called by {@link #equivalent}. {@code a} and {@code b} are not the same
   * object and are not nulls.
   *
   * @since 10.0 (previously, subclasses would override equivalent())
   */
  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 accross 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 accorss 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(@Nullable T t) {
    if (t == null) {
      return 0;
    }
    return doHash(t);
  }

  /**
   * Returns a hash code for non-null object {@code t}.
   *
   * 
Called by {@link #hash}.
   *
   * @since 10.0 (previously, subclasses would override hash())
   */
  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 = Equivalences.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 Equivalences.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(this, a).equals(wrap(this, b))} if and only if {@code this.equivalent(a, b)}.
   * 
   * @since 10.0
   */
  public final  Wrapper wrap(@Nullable 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
   */
  @Beta
  public static final class Wrapper implements Serializable {
    private final Equivalence equivalence;
    @Nullable private final T reference;

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

    /** Returns the (possibly null) reference wrapped by this instance. */
    @Nullable 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(@Nullable Object obj) {
      if (obj == this) {
        return true;
      } else if (obj instanceof Wrapper) {
        Wrapper that = (Wrapper) obj;
        /*
         * We cast to Equivalence here because we can't check the type of the reference held
         * by the other wrapper.  But, by checking that the Equivalences are equal, we know that
         * whatever type it is, it is assignable to the type handled by this wrapper's equivalence.
         */
        @SuppressWarnings("unchecked")
        Equivalence equivalence = (Equivalence) this.equivalence;
        return equivalence.equals(that.equivalence)
            && equivalence.equivalent(this.reference, that.reference);
      } else {
        return false;
      }
    }

    /**
     * Returns the result of {@link Equivalence#hash(Object)} applied to the 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(@Nullable T target) {
    return new EquivalentToPredicate(this, target);
  }

  private static final class EquivalentToPredicate implements Predicate, Serializable {

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

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

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

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

    

    

            

    

            



    
    






    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy