home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / lang / Comparable.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  5.2 KB  |  117 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Comparable.java    1.9 98/09/30
  3.  *
  4.  * Copyright 1997, 1998 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 that
  19.  * implements it.  This ordering is referred to as the class's <i>natural
  20.  * ordering</i>, and the class's <tt>compareTo</tt> method is referred to as
  21.  * its <i>natural comparison method</i>.<p>
  22.  *
  23.  * Lists (and arrays) of objects that implement this interface can be sorted
  24.  * automatically by <tt>Collections.sort</tt> (and <tt>Arrays.sort</tt>).
  25.  * Objects that implement this interface can be used as keys in a sorted map
  26.  * or elements in a sorted set, without the need to specify a comparator.<p>
  27.  *
  28.  * A class's natural ordering is said to be <i>consistent with equals</i> if
  29.  * and only if <tt>(e1.compareTo((Object)e2)==0)</tt> has the same boolean
  30.  * value as <tt>e1.equals((Object)e2)</tt> for every <tt>e1</tt> and
  31.  * <tt>e2</tt> of class <tt>C</tt>.<p>
  32.  *
  33.  * It is strongly recommended (though not required) that natural orderings be
  34.  * consistent with equals.  This is so because sorted sets (and sorted maps)
  35.  * without explicit comparators behave "strangely" when they are used with
  36.  * elements (or keys) whose natural ordering is inconsistent with equals.  In
  37.  * particular, such a sorted set (or sorted map) violates the general contract
  38.  * for set (or map), which is defined in terms of the <tt>equals</tt>
  39.  * operation.<p>
  40.  *
  41.  * For example, if one adds two keys <tt>a</tt> and <tt>b</tt> such that
  42.  * <tt>(a.equals((Object)b) && a.compareTo((Object)b) != 0)</tt> to a sorted
  43.  * set that does not use an explicit comparator, the second <tt>add</tt>
  44.  * operation returns false (and the size of the sorted set does not increase)
  45.  * because <tt>a</tt> and <tt>b</tt> are equivalent from the sorted set's
  46.  * perspective.<p>
  47.  *
  48.  * Virtually all Java core classes that implement comparable have natural
  49.  * orderings that are consistent with equals.  One exception is
  50.  * <tt>java.math.BigDecimal</tt>, whose natural ordering equates
  51.  * <tt>BigDecimals</tt> with equal values and different precisions (such as
  52.  * 4.0 and 4.00).<p>
  53.  *
  54.  * For the mathematically inclined, the <i>relation</i> that defines
  55.  * the natural ordering on a given class C is:<pre>
  56.  *       {(x, y) such that x.compareTo((Object)y) <= 0}.
  57.  * </pre> The <i>quotient</i> for this total order is: <pre>
  58.  *       {(x, y) such that x.compareTo((Object)y) == 0}.
  59.  * </pre>
  60.  *
  61.  * It follows immediately from the contract for <tt>compareTo</tt> that the
  62.  * quotient is an <i>equivalence relation</i> on <tt>C</tt>, and that the
  63.  * natural ordering is a <i>total order</i> on <tt>C</tt>.  When we say that a
  64.  * class's natural ordering is <i>consistent with equals</i>, we mean that the
  65.  * quotient for the natural ordering is the equivalence relation defined by
  66.  * the class's <tt>equals(Object)</tt> method:<pre>
  67.  *     {(x, y) such that x.equals((Object)y)}.
  68.  * </pre>
  69.  *
  70.  * @author  Josh Bloch
  71.  * @version 1.9 09/30/98
  72.  * @see java.util.Comparator
  73.  * @see java.util.Collections#sort(java.util.List)
  74.  * @see java.util.Arrays#sort(Object[])
  75.  * @see java.util.SortedSet
  76.  * @see java.util.SortedMap
  77.  * @see java.util.TreeSet
  78.  * @see java.util.TreeMap
  79.  * @since JDK1.2
  80.  */
  81.  
  82. public interface Comparable {
  83.     /**
  84.      * Compares this object with the specified object for order.  Returns a
  85.      * negative integer, zero, or a positive integer as this object is less
  86.      * than, equal to, or greater than the specified object.<p>
  87.      *
  88.      * The implementor must ensure <tt>sgn(x.compareTo(y)) ==
  89.      * -sgn(y.compareTo(x))</tt> for all <tt>x</tt> and <tt>y</tt>.  (This
  90.      * implies that <tt>x.compareTo(y)</tt> must throw an exception iff
  91.      * <tt>y.compareTo(x)</tt> throws an exception.)<p>
  92.      *
  93.      * The implementor must also ensure that the relation is transitive:
  94.      * <tt>(x.compareTo(y)>0 && y.compareTo(z)>0)</tt> implies
  95.      * <tt>x.compareTo(z)>0</tt>.<p>
  96.      *
  97.      * Finally, the implementer must ensure that <tt>x.compareTo(y)==0</tt>
  98.      * implies that <tt>sgn(x.compareTo(z)) == sgn(y.compareTo(z))</tt>, for
  99.      * all <tt>z</tt>.<p>
  100.      *
  101.      * It is strongly recommended, but <i>not</i> strictly required that
  102.      * <tt>(x.compareTo(y)==0) == (x.equals(y))</tt>.  Generally speaking, any
  103.      * class that implements the <tt>Comparable</tt> interface and violates
  104.      * this condition should clearly indicate this fact.  The recommended
  105.      * language is "Note: this class has a natural ordering that is
  106.      * inconsistent with equals."
  107.      * 
  108.      * @param   o the Object to be compared.
  109.      * @return  a negative integer, zero, or a positive integer as this object
  110.      *        is less than, equal to, or greater than the specified object.
  111.      * 
  112.      * @throws ClassCastException if the specified object's type prevents it
  113.      *         from being compared to this Object.
  114.      */
  115.     public int compareTo(Object o);
  116. }
  117.