home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / lang / Comparable.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  2.6 KB  |  68 lines
  1. /*
  2.  * @(#)Comparable.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.lang;
  16.  
  17. /**
  18.  * This interface imposes a total ordering on the objects of each class
  19.  * that implements it.  This ordering is referred to as the class's
  20.  * <i>natural ordering</i>, and the class's compareTo function is
  21.  * referred to as its <i>natural comparison method</i>.
  22.  * <p>
  23.  * Arrays of Objects that implement this interface can be sorted automatically
  24.  * by List.sort.  Objects of these classes can also be used as keys in
  25.  * TreeTables without the need to specify a Comparator.
  26.  * <p>
  27.  * Classes that implement this interface include String, Byte, Character,
  28.  * Short, Integer, Long, Float, Double, BigInteger, BigDecimal, File, URL,
  29.  * Date.
  30.  * <p>
  31.  * @author  Josh Bloch
  32.  * @version 1.4 09/21/97
  33.  * @see java.util.Comparator
  34.  * @see java.util.Arrays#sort(Object[], Comparator)
  35.  * @see TreeTable
  36.  */
  37.  
  38. public interface Comparable {
  39.     /**
  40.      * Compares this Object with the specified Object for order.  Returns a
  41.      * negative integer, zero, or a positive integer as this Object is less
  42.      * than, equal to, or greater than the given Object.
  43.      * <p>
  44.      * The implementor must ensure sgn(x.compareTo(y)) == -sgn(y.compareTo(x))
  45.      * for all x and y.  (This implies that x.compareTo(y) must throw an
  46.      * exception iff y.compareTo(x) throws an exception.)
  47.      * <p>
  48.      * The implementor must also ensure that the relation is transitive:
  49.      * (x.compareTo(y)>0 && y.compareTo(z)>0) implies
  50.      * x.compareTo(z)>0.
  51.      * <p>
  52.      * The implementer must also ensure that x.equals(y) implies that 
  53.      * x.compareTo(y)==0.  Note that the converse is not necessarily true
  54.      * (e.g., BigDecimal).
  55.      * <p>
  56.      * Finally, the implementer must ensure that x.compareTo(y)==0 implies
  57.      * that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for all z.
  58.      * 
  59.      * @param   o the <code>Object</code> to be compared.
  60.      * @return  a negative integer, zero, or a positive integer as this Object
  61.      *        is less than, equal to, or greater than the given Object.
  62.      * @exception ClassCastException the specified Object's type prevents it
  63.      *          from being compared to this Object. 
  64.      * @since JDK1.2
  65.      */
  66.     public int compareTo(Object o);
  67. }
  68.