/* * @(#)Comparator.java 1.24 06/10/10 * * Copyright 1990-2008 Sun Microsystems, Inc. All Rights Reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License version * 2 only, as published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License version 2 for more details (a copy is * included at /legal/license.txt). * * You should have received a copy of the GNU General Public License * version 2 along with this work; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA * 02110-1301 USA * * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa * Clara, CA 95054 or visit www.sun.com if you need additional * information or have any questions. * */ package java.util; /** * A comparison function, which imposes a total ordering on some * collection of objects. Comparators can be passed to a sort method (such as * Collections.sort) to allow precise control over the sort order. * Comparators can also be used to control the order of certain data * structures (such as TreeSet or TreeMap). * * The ordering imposed by a Comparator c on a set of elements * S is said to be consistent with equals if and only if * (compare((Object)e1, (Object)e2)==0) has the same boolean value as * e1.equals((Object)e2) for every e1 and e2 in * S. * * Caution should be exercised when using a comparator capable of imposing an * ordering inconsistent with equals to order a sorted set (or sorted map). * Suppose a sorted set (or sorted map) with an explicit Comparator c * is used with elements (or keys) drawn from a set S. If the * ordering imposed by c on S is inconsistent with equals, * the sorted set (or sorted map) will behave "strangely." In particular the * sorted set (or sorted map) will violate the general contract for set (or * map), which is defined in terms of equals. * * For example, if one adds two keys a and b such that * (a.equals((Object)b) && c.compare((Object)a, (Object)b) != 0) to a * sorted set with comparator c, the second add operation * will return false (and the size of the sorted set will not increase) * because a and b are equivalent from the sorted set's * perspective. * * Note: It is generally a good idea for comparators to implement * java.io.Serializable, as they may be used as ordering methods in * serializable data structures (like TreeSet, TreeMap). In * order for the data structure to serialize successfully, the comparator (if * provided) must implement Serializable. * * For the mathematically inclined, the relation that defines * the total order that a given comparator c imposes on a * given set of objects S is: * {(x, y) such that c.compare((Object)x, (Object)y) <= 0}. * The quotient for this total order is: * {(x, y) such that c.compare((Object)x, (Object)y) == 0}. * * * It follows immediately from the contract for compare that the * quotient is an equivalence relation on S, and that the * natural ordering is a total order on S. When we say that * the ordering imposed by c on S is consistent with * equals, we mean that the quotient for the natural ordering is the * equivalence relation defined by the objects' equals(Object) * method(s): * {(x, y) such that x.equals((Object)y)}. * * * This interface is a member of the * * Java Collections Framework. * * @author Josh Bloch * @version 1.15, 02/02/00 * @see Comparable * @see Arrays#sort(Object[], Comparator) * @see TreeMap * @see TreeSet * @see SortedMap * @see SortedSet * @see java.io.Serializable * @since 1.2 */ public interface Comparator { /** * Compares its two arguments for order. Returns a negative integer, * zero, or a positive integer as the first argument is less than, equal * to, or greater than the second. * * The implementor must ensure that sgn(compare(x, y)) == * -sgn(compare(y, x)) for all x and y. (This * implies that compare(x, y) must throw an exception if and only * if compare(y, x) throws an exception.) * * The implementor must also ensure that the relation is transitive: * ((compare(x, y)>0) && (compare(y, z)>0)) implies * compare(x, z)>0. * * Finally, the implementer must ensure that compare(x, y)==0 * implies that sgn(compare(x, z))==sgn(compare(y, z)) for all * z. * * It is generally the case, but not strictly required that * (compare(x, y)==0) == (x.equals(y)). Generally speaking, * any comparator that violates this condition should clearly indicate * this fact. The recommended language is "Note: this comparator * imposes orderings that are inconsistent with equals." * * @param o1 the first object to be compared. * @param o2 the second object to be compared. * @return a negative integer, zero, or a positive integer as the * first argument is less than, equal to, or greater than the * second. * @throws ClassCastException if the arguments' types prevent them from * being compared by this Comparator. */ int compare(Object o1, Object o2); /** * * Indicates whether some other object is "equal to" this * Comparator. This method must obey the general contract of * Object.equals(Object). Additionally, this method can return * true only if the specified Object is also a comparator * and it imposes the same ordering as this comparator. Thus, * comp1.equals(comp2) implies that sgn(comp1.compare(o1, * o2))==sgn(comp2.compare(o1, o2)) for every object reference * o1 and o2. * * Note that it is always safe not to override * Object.equals(Object). However, overriding this method may, * in some cases, improve performance by allowing programs to determine * that two distinct Comparators impose the same order. * * @param obj the reference object with which to compare. * @return true only if the specified object is also * a comparator and it imposes the same ordering as this * comparator. * @see java.lang.Object#equals(java.lang.Object) * @see java.lang.Object#hashCode() */ boolean equals(Object obj); }
