1. /*
  2. * @(#)Comparable.java 1.20 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.lang;
  8. /**
  9. * This interface imposes a total ordering on the objects of each class that
  10. * implements it. This ordering is referred to as the class's <i>natural
  11. * ordering</i>, and the class's <tt>compareTo</tt> method is referred to as
  12. * its <i>natural comparison method</i>.<p>
  13. *
  14. * Lists (and arrays) of objects that implement this interface can be sorted
  15. * automatically by <tt>Collections.sort</tt> (and <tt>Arrays.sort</tt>).
  16. * Objects that implement this interface can be used as keys in a sorted map
  17. * or elements in a sorted set, without the need to specify a comparator.<p>
  18. *
  19. * The natural ordering for a class <tt>C</tt> is said to be <i>consistent
  20. * with equals</i> if and only if <tt>(e1.compareTo((Object)e2) == 0)</tt> has
  21. * the same boolean value as <tt>e1.equals((Object)e2)</tt> for every
  22. * <tt>e1</tt> and <tt>e2</tt> of class <tt>C</tt>. Note that <tt>null</tt>
  23. * is not an instance of any class, and <tt>e.compareTo(null)</tt> should
  24. * throw a <tt>NullPointerException</tt> even though <tt>e.equals(null)</tt>
  25. * returns <tt>false</tt>.<p>
  26. *
  27. * It is strongly recommended (though not required) that natural orderings be
  28. * consistent with equals. This is so because sorted sets (and sorted maps)
  29. * without explicit comparators behave "strangely" when they are used with
  30. * elements (or keys) whose natural ordering is inconsistent with equals. In
  31. * particular, such a sorted set (or sorted map) violates the general contract
  32. * for set (or map), which is defined in terms of the <tt>equals</tt>
  33. * method.<p>
  34. *
  35. * For example, if one adds two keys <tt>a</tt> and <tt>b</tt> such that
  36. * <tt>(!a.equals((Object)b) && a.compareTo((Object)b) == 0)</tt> to a sorted
  37. * set that does not use an explicit comparator, the second <tt>add</tt>
  38. * operation returns false (and the size of the sorted set does not increase)
  39. * because <tt>a</tt> and <tt>b</tt> are equivalent from the sorted set's
  40. * perspective.<p>
  41. *
  42. * Virtually all Java core classes that implement comparable have natural
  43. * orderings that are consistent with equals. One exception is
  44. * <tt>java.math.BigDecimal</tt>, whose natural ordering equates
  45. * <tt>BigDecimal</tt> objects with equal values and different precisions
  46. * (such as 4.0 and 4.00).<p>
  47. *
  48. * For the mathematically inclined, the <i>relation</i> that defines
  49. * the natural ordering on a given class C is:<pre>
  50. * {(x, y) such that x.compareTo((Object)y) <= 0}.
  51. * </pre> The <i>quotient</i> for this total order is: <pre>
  52. * {(x, y) such that x.compareTo((Object)y) == 0}.
  53. * </pre>
  54. *
  55. * It follows immediately from the contract for <tt>compareTo</tt> that the
  56. * quotient is an <i>equivalence relation</i> on <tt>C</tt>, and that the
  57. * natural ordering is a <i>total order</i> on <tt>C</tt>. When we say that a
  58. * class's natural ordering is <i>consistent with equals</i>, we mean that the
  59. * quotient for the natural ordering is the equivalence relation defined by
  60. * the class's <tt>equals(Object)</tt> method:<pre>
  61. * {(x, y) such that x.equals((Object)y)}.
  62. * </pre><p>
  63. *
  64. * This interface is a member of the
  65. * <a href="{@docRoot}/../guide/collections/index.html">
  66. * Java Collections Framework</a>.
  67. *
  68. * @author Josh Bloch
  69. * @version 1.20, 01/23/03
  70. * @see java.util.Comparator
  71. * @see java.util.Collections#sort(java.util.List)
  72. * @see java.util.Arrays#sort(Object[])
  73. * @see java.util.SortedSet
  74. * @see java.util.SortedMap
  75. * @see java.util.TreeSet
  76. * @see java.util.TreeMap
  77. * @since 1.2
  78. */
  79. public interface Comparable {
  80. /**
  81. * Compares this object with the specified object for order. Returns a
  82. * negative integer, zero, or a positive integer as this object is less
  83. * than, equal to, or greater than the specified object.<p>
  84. *
  85. * In the foregoing description, the notation
  86. * <tt>sgn(</tt><i>expression</i><tt>)</tt> designates the mathematical
  87. * <i>signum</i> function, which is defined to return one of <tt>-1</tt>,
  88. * <tt>0</tt>, or <tt>1</tt> according to whether the value of <i>expression</i>
  89. * is negative, zero or positive.
  90. *
  91. * The implementor must ensure <tt>sgn(x.compareTo(y)) ==
  92. * -sgn(y.compareTo(x))</tt> for all <tt>x</tt> and <tt>y</tt>. (This
  93. * implies that <tt>x.compareTo(y)</tt> must throw an exception iff
  94. * <tt>y.compareTo(x)</tt> throws an exception.)<p>
  95. *
  96. * The implementor must also ensure that the relation is transitive:
  97. * <tt>(x.compareTo(y)>0 && y.compareTo(z)>0)</tt> implies
  98. * <tt>x.compareTo(z)>0</tt>.<p>
  99. *
  100. * Finally, the implementer must ensure that <tt>x.compareTo(y)==0</tt>
  101. * implies that <tt>sgn(x.compareTo(z)) == sgn(y.compareTo(z))</tt>, for
  102. * all <tt>z</tt>.<p>
  103. *
  104. * It is strongly recommended, but <i>not</i> strictly required that
  105. * <tt>(x.compareTo(y)==0) == (x.equals(y))</tt>. Generally speaking, any
  106. * class that implements the <tt>Comparable</tt> interface and violates
  107. * this condition should clearly indicate this fact. The recommended
  108. * language is "Note: this class has a natural ordering that is
  109. * inconsistent with equals."
  110. *
  111. * @param o the Object to be compared.
  112. * @return a negative integer, zero, or a positive integer as this object
  113. * is less than, equal to, or greater than the specified object.
  114. *
  115. * @throws ClassCastException if the specified object's type prevents it
  116. * from being compared to this Object.
  117. */
  118. public int compareTo(Object o);
  119. }