javolution.util.function.Equality Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of javolution-core-java-msftbx Show documentation

Only the Java Core part of Javolution library, with slight modifications for use in MSFTBX.

There is a newer version: 6.11.8

Show newest version

/*
 * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
 * Copyright (C) 2012 - Javolution (http://javolution.org/)
 * All rights reserved.
 * 
 * Permission to use, copy, modify, and distribute this software is
 * freely granted, provided that this notice is preserved.
 */
package javolution.util.function;

import java.io.Serializable;
import java.util.Comparator;

/**
 *  A comparator to be used for element equality as well as for 
 *     ordering. Implementing classes should ensure that:
 *     

 *         The {@link #compare compare} function is consistent with 
 *             {@link #equal(Object, Object) equal}. If two objects 
 *             {@link #compare compare} to {@code 0} then they are 
 *             {@link #equal(Object, Object) equal} and the 
 *             reciprocal is true (this ensures that sorted collections/maps
 *             do not break the general contract of their parent class based on
 *             object equal).
 *         The {@link #hashOf hash} function is consistent with
 *             {@link #equal(Object, Object) equal}: If two objects are equal, 
 *             they have the same hashcode (the reciprocal is not true).
 *         The {@code null} value is supported (even for 
 *             {@link #compare comparisons}) and the {@link #hashOf(Object)
 *             hashcode} value of {@code null} is {@code 0}.
 *     
 * 
 * 
 * @param  the type of objects that may be compared for equality or order.
 * 
 * @author Jean-Marie Dautelle
 * @version 6.0, July 21, 2013
 * @see Equalities
 */
public interface Equality extends EqualityComparer, Comparator, Serializable {

    /**
     * Returns the hash code for the specified object (consistent with 
     * {@link #equal(Object, Object)}). 
     * Two objects considered equal have the same hash code. 
     * The hash code of null is always 0.
     * 
     * @param  object the object to return the hashcode for.
     * @return the hashcode for the specified object.
     */
    int hashOf(T object);

    /**
     * Indicates if the specified objects can be considered equal.
     * This methods is equivalent to {@code (compare(o1, o2) == 0)} but 
     * usually faster.
     * 
     * @param left the first object (or null).
     * @param right the second object (or null).
     * @return true if both objects are considered equal;
     *         false otherwise. 
     */
    boolean equal(T left, T right);

    /**
     * Compares the specified objects for order. Returns a negative integer, 
     * zero, or a positive integer as the first argument is less than, possibly 
     * equal to, or greater than the second. Implementation classes should 
     * ensure that comparisons with {@code null} is supported.
     * 
     * @param left the first object.
     * @param right the second object.
     * @return a negative integer, zero, or a positive integer as the first
     *         argument is less than, possibly equal to, or greater than the second.
     */
    int compare(T left, T right);

}