67  * {@code java.math.BigDecimal}, whose natural ordering equates
  68  * {@code BigDecimal} objects with equal values and different precisions
  69  * (such as 4.0 and 4.00).<p>
  70  *
  71  * For the mathematically inclined, the <i>relation</i> that defines
  72  * the natural ordering on a given class C is:<pre>{@code
  73  *       {(x, y) such that x.compareTo(y) <= 0}.
  74  * }</pre> The <i>quotient</i> for this total order is: <pre>{@code
  75  *       {(x, y) such that x.compareTo(y) == 0}.
  76  * }</pre>
  77  *
  78  * It follows immediately from the contract for {@code compareTo} that the
  79  * quotient is an <i>equivalence relation</i> on {@code C}, and that the
  80  * natural ordering is a <i>total order</i> on {@code C}.  When we say that a
  81  * class's natural ordering is <i>consistent with equals</i>, we mean that the
  82  * quotient for the natural ordering is the equivalence relation defined by
  83  * the class's {@link Object#equals(Object) equals(Object)} method:<pre>
  84  *     {(x, y) such that x.equals(y)}. </pre><p>
  85  *
  86  * This interface is a member of the
  87  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
  88  * Java Collections Framework</a>.
  89  *
  90  * @param <T> the type of objects that this object may be compared to
  91  *
  92  * @author  Josh Bloch
  93  * @see java.util.Comparator
  94  * @since 1.2
  95  */
  96 public interface Comparable<T> {
  97     /**
  98      * Compares this object with the specified object for order.  Returns a
  99      * negative integer, zero, or a positive integer as this object is less
 100      * than, equal to, or greater than the specified object.
 101      *
 102      * <p>The implementor must ensure
 103      * {@code sgn(x.compareTo(y)) == -sgn(y.compareTo(x))}
 104      * for all {@code x} and {@code y}.  (This
 105      * implies that {@code x.compareTo(y)} must throw an exception iff
 106      * {@code y.compareTo(x)} throws an exception.)
 107      *

  67  * {@code java.math.BigDecimal}, whose natural ordering equates
  68  * {@code BigDecimal} objects with equal values and different precisions
  69  * (such as 4.0 and 4.00).<p>
  70  *
  71  * For the mathematically inclined, the <i>relation</i> that defines
  72  * the natural ordering on a given class C is:<pre>{@code
  73  *       {(x, y) such that x.compareTo(y) <= 0}.
  74  * }</pre> The <i>quotient</i> for this total order is: <pre>{@code
  75  *       {(x, y) such that x.compareTo(y) == 0}.
  76  * }</pre>
  77  *
  78  * It follows immediately from the contract for {@code compareTo} that the
  79  * quotient is an <i>equivalence relation</i> on {@code C}, and that the
  80  * natural ordering is a <i>total order</i> on {@code C}.  When we say that a
  81  * class's natural ordering is <i>consistent with equals</i>, we mean that the
  82  * quotient for the natural ordering is the equivalence relation defined by
  83  * the class's {@link Object#equals(Object) equals(Object)} method:<pre>
  84  *     {(x, y) such that x.equals(y)}. </pre><p>
  85  *
  86  * This interface is a member of the
  87  * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
  88  * Java Collections Framework</a>.
  89  *
  90  * @param <T> the type of objects that this object may be compared to
  91  *
  92  * @author  Josh Bloch
  93  * @see java.util.Comparator
  94  * @since 1.2
  95  */
  96 public interface Comparable<T> {
  97     /**
  98      * Compares this object with the specified object for order.  Returns a
  99      * negative integer, zero, or a positive integer as this object is less
 100      * than, equal to, or greater than the specified object.
 101      *
 102      * <p>The implementor must ensure
 103      * {@code sgn(x.compareTo(y)) == -sgn(y.compareTo(x))}
 104      * for all {@code x} and {@code y}.  (This
 105      * implies that {@code x.compareTo(y)} must throw an exception iff
 106      * {@code y.compareTo(x)} throws an exception.)
 107      *