* * Lists (and arrays) of objects that implement this interface can be sorted @@ -39,45 +39,45 @@ * elements in a {@linkplain SortedSet sorted set}, without the need to * specify a {@linkplain Comparator comparator}.
* - * The natural ordering for a class C is said to be consistent - * with equals if and only if e1.compareTo(e2) == 0 has - * the same boolean value as e1.equals(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.
+ * The natural ordering for a class {@code C} is said to be consistent + * with equals if and only if {@code e1.compareTo(e2) == 0} has + * the same boolean value as {@code e1.equals(e2)} for every + * {@code e1} and {@code e2} of class {@code C}. Note that {@code null} + * is not an instance of any class, and {@code e.compareTo(null)} should + * throw a {@code NullPointerException} even though {@code e.equals(null)} + * returns {@code 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 + * for set (or map), which is defined in terms of the {@code equals} * method.
* - * For example, if one adds two keys a and b such that + * For example, if one adds two keys {@code a} and {@code b} such that * {@code (!a.equals(b) && a.compareTo(b) == 0)} to a sorted - * set that does not use an explicit comparator, the second add + * set that does not use an explicit comparator, the second {@code 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 + * because {@code a} and {@code b} are equivalent from the sorted set's * perspective.
* - * Virtually all Java core classes that implement Comparable have natural + * Virtually all Java core classes that implement {@code 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 + * {@code java.math.BigDecimal}, whose natural ordering equates + * {@code BigDecimal} objects with equal values and different precisions * (such as 4.0 and 4.00).
* * For the mathematically inclined, the relation that defines - * the natural ordering on a given class C is:
- * {(x, y) such that x.compareTo(y) <= 0}.
- * The quotient for this total order is: + * the natural ordering on a given class C is:* - * It follows immediately from the contract for compareTo that the - * quotient is an equivalence relation on C, and that the - * natural ordering is a total order on C. When we say that a + * It follows immediately from the contract for {@code compareTo} that the + * quotient is an equivalence relation on {@code C}, and that the + * natural ordering is a total order on {@code C}. When we say that a * class's natural ordering is consistent with equals, we mean that the * quotient for the natural ordering is the equivalence relation defined by * the class's {@link Object#equals(Object) equals(Object)} method:{@code + * {(x, y) such that x.compareTo(y) <= 0}. + * }The quotient for this total order is:{@code * {(x, y) such that x.compareTo(y) == 0}. - *+ * }
@@ -99,30 +99,31 @@
* negative integer, zero, or a positive integer as this object is less
* than, equal to, or greater than the specified object.
*
- * The implementor must ensure sgn(x.compareTo(y)) ==
- * -sgn(y.compareTo(x)) for all x and y. (This
- * implies that x.compareTo(y) must throw an exception iff
- * y.compareTo(x) throws an exception.)
+ *
The implementor must ensure
+ * {@code sgn(x.compareTo(y)) == -sgn(y.compareTo(x))}
+ * for all {@code x} and {@code y}. (This
+ * implies that {@code x.compareTo(y)} must throw an exception iff
+ * {@code y.compareTo(x)} throws an exception.)
*
*
The implementor must also ensure that the relation is transitive:
- * (x.compareTo(y)>0 && y.compareTo(z)>0) implies
- * x.compareTo(z)>0.
+ * {@code (x.compareTo(y) > 0 && y.compareTo(z) > 0)} implies
+ * {@code x.compareTo(z) > 0}.
*
- *
Finally, the implementor must ensure that x.compareTo(y)==0
- * implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for
- * all z.
+ *
Finally, the implementor must ensure that {@code x.compareTo(y)==0}
+ * implies that {@code sgn(x.compareTo(z)) == sgn(y.compareTo(z))}, for
+ * all {@code z}.
*
*
It is strongly recommended, but not strictly required that
- * (x.compareTo(y)==0) == (x.equals(y)). Generally speaking, any
- * class that implements the Comparable interface and violates
+ * {@code (x.compareTo(y)==0) == (x.equals(y))}. Generally speaking, any
+ * class that implements the {@code Comparable} interface and violates
* this condition should clearly indicate this fact. The recommended
* language is "Note: this class has a natural ordering that is
* inconsistent with equals."
*
*
In the foregoing description, the notation
- * sgn(expression) designates the mathematical
- * signum function, which is defined to return one of -1,
- * 0, or 1 according to whether the value of
+ * {@code sgn(}expression{@code )} designates the mathematical
+ * signum function, which is defined to return one of {@code -1},
+ * {@code 0}, or {@code 1} according to whether the value of
* expression is negative, zero or positive.
*
* @param o the object to be compared.