jaroslav@62: /* jaroslav@62: * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights reserved. jaroslav@62: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@62: * jaroslav@62: * This code is free software; you can redistribute it and/or modify it jaroslav@62: * under the terms of the GNU General Public License version 2 only, as jaroslav@62: * published by the Free Software Foundation. Oracle designates this jaroslav@62: * particular file as subject to the "Classpath" exception as provided jaroslav@62: * by Oracle in the LICENSE file that accompanied this code. jaroslav@62: * jaroslav@62: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@62: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@62: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@62: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@62: * accompanied this code). jaroslav@62: * jaroslav@62: * You should have received a copy of the GNU General Public License version jaroslav@62: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@62: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@62: * jaroslav@62: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@62: * or visit www.oracle.com if you need additional information or have any jaroslav@62: * questions. jaroslav@62: */ jaroslav@62: jaroslav@62: package java.util; jaroslav@62: jaroslav@62: /** jaroslav@62: * A comparison function, which imposes a total ordering on some jaroslav@62: * collection of objects. Comparators can be passed to a sort method (such jaroslav@62: * as {@link Collections#sort(List,Comparator) Collections.sort} or {@link jaroslav@62: * Arrays#sort(Object[],Comparator) Arrays.sort}) to allow precise control jaroslav@62: * over the sort order. Comparators can also be used to control the order of jaroslav@62: * certain data structures (such as {@link SortedSet sorted sets} or {@link jaroslav@62: * SortedMap sorted maps}), or to provide an ordering for collections of jaroslav@62: * objects that don't have a {@link Comparable natural ordering}.
jaroslav@62: * jaroslav@62: * The ordering imposed by a comparator c on a set of elements jaroslav@62: * S is said to be consistent with equals if and only if jaroslav@62: * c.compare(e1, e2)==0 has the same boolean value as jaroslav@62: * e1.equals(e2) for every e1 and e2 in jaroslav@62: * S.
jaroslav@62: * jaroslav@62: * Caution should be exercised when using a comparator capable of imposing an jaroslav@62: * ordering inconsistent with equals to order a sorted set (or sorted map). jaroslav@62: * Suppose a sorted set (or sorted map) with an explicit comparator c jaroslav@62: * is used with elements (or keys) drawn from a set S. If the jaroslav@62: * ordering imposed by c on S is inconsistent with equals, jaroslav@62: * the sorted set (or sorted map) will behave "strangely." In particular the jaroslav@62: * sorted set (or sorted map) will violate the general contract for set (or jaroslav@62: * map), which is defined in terms of equals.
jaroslav@62: * jaroslav@62: * For example, suppose one adds two elements {@code a} and {@code b} such that jaroslav@62: * {@code (a.equals(b) && c.compare(a, b) != 0)} jaroslav@62: * to an empty {@code TreeSet} with comparator {@code c}. jaroslav@62: * The second {@code add} operation will return jaroslav@62: * true (and the size of the tree set will increase) because {@code a} and jaroslav@62: * {@code b} are not equivalent from the tree set's perspective, even though jaroslav@62: * this is contrary to the specification of the jaroslav@62: * {@link Set#add Set.add} method.
jaroslav@62: * jaroslav@62: * Note: It is generally a good idea for comparators to also implement jaroslav@62: * java.io.Serializable, as they may be used as ordering methods in jaroslav@62: * serializable data structures (like {@link TreeSet}, {@link TreeMap}). In jaroslav@62: * order for the data structure to serialize successfully, the comparator (if jaroslav@62: * provided) must implement Serializable.
jaroslav@62: * jaroslav@62: * For the mathematically inclined, the relation that defines the jaroslav@62: * imposed ordering that a given comparator c imposes on a jaroslav@62: * given set of objects S is:
jaroslav@62: * {(x, y) such that c.compare(x, y) <= 0}. jaroslav@62: *The quotient for this total order is:
jaroslav@62: * {(x, y) such that c.compare(x, y) == 0}. jaroslav@62: *jaroslav@62: * jaroslav@62: * It follows immediately from the contract for compare that the jaroslav@62: * quotient is an equivalence relation on S, and that the jaroslav@62: * imposed ordering is a total order on S. When we say that jaroslav@62: * the ordering imposed by c on S is consistent with jaroslav@62: * equals, we mean that the quotient for the ordering is the equivalence jaroslav@62: * relation defined by the objects' {@link Object#equals(Object) jaroslav@62: * equals(Object)} method(s):
jaroslav@62: * {(x, y) such that x.equals(y)}.jaroslav@62: * jaroslav@62: *
Unlike {@code Comparable}, a comparator may optionally permit jaroslav@62: * comparison of null arguments, while maintaining the requirements for jaroslav@62: * an equivalence relation. jaroslav@62: * jaroslav@62: *
This interface is a member of the
jaroslav@62: *
jaroslav@62: * Java Collections Framework.
jaroslav@62: *
jaroslav@62: * @param
jaroslav@62: *
jaroslav@62: * In the foregoing description, the notation
jaroslav@62: * sgn(expression) designates the mathematical
jaroslav@62: * signum function, which is defined to return one of -1,
jaroslav@62: * 0, or 1 according to whether the value of
jaroslav@62: * expression is negative, zero or positive.
jaroslav@62: *
jaroslav@62: * The implementor must ensure that sgn(compare(x, y)) ==
jaroslav@62: * -sgn(compare(y, x)) for all x and y. (This
jaroslav@62: * implies that compare(x, y) must throw an exception if and only
jaroslav@62: * if compare(y, x) throws an exception.)
jaroslav@62: *
jaroslav@62: * The implementor must also ensure that the relation is transitive:
jaroslav@62: * ((compare(x, y)>0) && (compare(y, z)>0)) implies
jaroslav@62: * compare(x, z)>0.
jaroslav@62: *
jaroslav@62: * Finally, the implementor must ensure that compare(x, y)==0
jaroslav@62: * implies that sgn(compare(x, z))==sgn(compare(y, z)) for all
jaroslav@62: * z.
jaroslav@62: *
jaroslav@62: * It is generally the case, but not strictly required that
jaroslav@62: * (compare(x, y)==0) == (x.equals(y)). Generally speaking,
jaroslav@62: * any comparator that violates this condition should clearly indicate
jaroslav@62: * this fact. The recommended language is "Note: this comparator
jaroslav@62: * imposes orderings that are inconsistent with equals."
jaroslav@62: *
jaroslav@62: * @param o1 the first object to be compared.
jaroslav@62: * @param o2 the second object to be compared.
jaroslav@62: * @return a negative integer, zero, or a positive integer as the
jaroslav@62: * first argument is less than, equal to, or greater than the
jaroslav@62: * second.
jaroslav@62: * @throws NullPointerException if an argument is null and this
jaroslav@62: * comparator does not permit null arguments
jaroslav@62: * @throws ClassCastException if the arguments' types prevent them from
jaroslav@62: * being compared by this comparator.
jaroslav@62: */
jaroslav@62: int compare(T o1, T o2);
jaroslav@62:
jaroslav@62: /**
jaroslav@62: * Indicates whether some other object is "equal to" this
jaroslav@62: * comparator. This method must obey the general contract of
jaroslav@62: * {@link Object#equals(Object)}. Additionally, this method can return
jaroslav@62: * true only if the specified object is also a comparator
jaroslav@62: * and it imposes the same ordering as this comparator. Thus,
jaroslav@62: *
jaroslav@62: *
jaroslav@62: * Note that it is always safe not to override
jaroslav@62: * Object.equals(Object). However, overriding this method may,
jaroslav@62: * in some cases, improve performance by allowing programs to determine
jaroslav@62: * that two distinct comparators impose the same order.
jaroslav@62: *
jaroslav@62: * @param obj the reference object with which to compare.
jaroslav@62: * @return comp1.equals(comp2)
implies that sgn(comp1.compare(o1,
jaroslav@62: * o2))==sgn(comp2.compare(o1, o2)) for every object reference
jaroslav@62: * o1 and o2.true
only if the specified object is also
jaroslav@62: * a comparator and it imposes the same ordering as this
jaroslav@62: * comparator.
jaroslav@62: * @see Object#equals(Object)
jaroslav@62: * @see Object#hashCode()
jaroslav@62: */
jaroslav@62: boolean equals(Object obj);
jaroslav@62: }