java.lang.Comparable Maven / Gradle / Ivy

Neither this file nor any files generated from it describe a complete specification, and they may only be used as described below. For example, no permission is given for you to incorporate this file, in whole or in part, in an implementation of a Java specification.

Sun Microsystems Inc. owns the copyright in this file and it is provided to you for informative, as opposed to normative, use. The file and any files generated from it may be used to generate other informative documentation, such as a unified set of documents of API signatures for a platform that includes technologies expressed as Java APIs. The file may also be used to produce "compilation stubs," which allow applications to be compiled and validated for such platforms.

Any work generated from this file, such as unified javadocs or compiled stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 219: Foundation Profile 1.1. In the event of a discrepency between this work and the JSR 219 specification, which is available at http://www.jcp.org/en/jsr/detail?id=219, the latter takes precedence. */ package java.lang; /** * This interface imposes a total ordering on the objects of each class that * implements it. This ordering is referred to as the class's natural * ordering, and the class's compareTo method is referred to as * its natural comparison method.

* * Lists (and arrays) of objects that implement this interface can be sorted * automatically by Collections.sort (and Arrays.sort). * Objects that implement this interface can be used as keys in a sorted map * or elements in a sorted set, without the need to specify a comparator.

* * The natural ordering for a class C is said to be consistent * with equals if and only if (e1.compareTo((Object)e2) == 0) has * the same boolean value as e1.equals((Object)e2) for every * e1 and e2 of class C. Note that null * is not an instance of any class, and e.compareTo(null) should * throw a NullPointerException even though e.equals(null) * returns false.

* * It is strongly recommended (though not required) that natural orderings be * consistent with equals. This is so because sorted sets (and sorted maps) * without explicit comparators behave "strangely" when they are used with * elements (or keys) whose natural ordering is inconsistent with equals. In * particular, such a sorted set (or sorted map) violates the general contract * for set (or map), which is defined in terms of the equals * method.

* * For example, if one adds two keys a and b such that * (!a.equals((Object)b) && a.compareTo((Object)b) == 0) to a sorted * set that does not use an explicit comparator, the second add * operation returns false (and the size of the sorted set does not increase) * because a and b are equivalent from the sorted set's * perspective.

* * Virtually all Java core classes that implement comparable have natural * orderings that are consistent with equals. One exception is * java.math.BigDecimal, whose natural ordering equates * BigDecimal objects with equal values and different precisions * (such as 4.0 and 4.00). * NOTE: java.math.BigDecimal is found in J2ME CDC profiles such as * J2ME Foundation Profile.

* * For the mathematically inclined, the relation that defines * the natural ordering on a given class C is:

 *       {(x, y) such that x.compareTo((Object)y) <= 0}.
 * 

 *       {(x, y) such that x.compareTo((Object)y) == 0}.
 * 

 *     {(x, y) such that x.equals((Object)y)}.
 *