com.google.common.base.Equivalence Maven / Gradle / Ivy
/**
* Copyright (C) 2010 Google Inc.
*
* 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 com.google.common.annotations.Beta;
/**
* 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
* @since 4
*/
@Beta
public interface Equivalence {
/**
* Returns {@code true} if the given objects are considered equivalent.
*
* The equivalent method implements an equivalence relation
* on non-null object references:
*
* - It is reflexive: for any non-null reference value
*
x, x.equals(x) should return
* true.
* - It is symmetric: for any non-null reference values
*
x and y, x.equals(y)
* should return true if and only if
* y.equals(x) returns true.
* - It is transitive: for any non-null reference values
*
x, y, and z, if
* x.equals(y) returns true and
* y.equals(z) returns true, then
* x.equals(z) should return true.
* - It is consistent: for any non-null reference values
*
x and y, multiple invocations of
* x.equals(y) consistently return true
* or consistently return false, provided no
* information used in equals comparisons on the
* objects is modified.
* - For any non-null reference value
x,
* x.equals(null) should return false.
*
*/
boolean equivalent(T a, T b);
/**
* Returns a hash code for {@code object}. This function must return
* the same value for any two instances which are {@link #equivalent}, and
* should as often as possible return a distinct value for instances which
* are not equivalent.
*
* @see Object#hashCode the same contractual obligations apply here
* @throws NullPointerException if t is null
*/
int hash(T t);
}