home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / util / Comparator.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  2.2 KB  |  61 lines
  1. /*
  2.  * @(#)Comparator.java    1.6 98/03/18
  3.  *
  4.  * Copyright 1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.util;
  16.  
  17. /**
  18.  * A comparison function, which imposes a total ordering on some collection
  19.  * of Objects.  Comparators can be passed to a sort method (such as
  20.  * Arrays.sort) to allow precise control over the sort order. Comparators can
  21.  * also be used to control the order of certain data structures (such as
  22.  * TreeMap).
  23.  *
  24.  * @author  Josh Bloch
  25.  * @version 1.4 09/22/97
  26.  * @see java.lang.Comparable
  27.  * @see Arrays#sort(Object[], Comparator)
  28.  * @see TreeMap
  29.  * @since   JDK1.2
  30.  */
  31.  
  32. public interface Comparator {
  33.     /**
  34.      * Compares its two arguments for order.  Returns a negative integer,
  35.      * zero, or a positive integer as the first argument is less than, equal
  36.      * to, or greater than the second.
  37.      * <p>
  38.      * The implementor must ensure that sgn(compare(x, y)) == -sgn(compare(y,
  39.      * x)) for all x and y.  (This implies that compare(x, y) must throw
  40.      * an exception if and only if compare(y, x) throws an exception.)
  41.      * <p>
  42.      * The implementor must also ensure that the relation is transitive:
  43.      * ((compare(x, y)>0) && (compare(y, z)>0)) implies
  44.      * compare(x, z)>0. 
  45.      * <p>
  46.      * The implementer must also ensure that x.equals(y) implies that 
  47.      * compare(x, y) == 0.  Note that the converse is not necessarily true.
  48.      * <p>
  49.      * Finally, the implementer must ensure that compare(x, y) == 0 implies
  50.      * that sgn(compare(x, z)) == sgn(compare(y, z)), for all z.
  51.      * 
  52.      * @return a negative integer, zero, or a positive integer as the
  53.      *            first argument is less than, equal to, or greater than the
  54.      *           second. 
  55.      * @exception ClassCastException the arguments' types prevent them from
  56.      *           being compared by this Comparator.
  57.      * @since   JDK1.2
  58.      */
  59.     public int compare(Object o1, Object o2);
  60. }
  61.