27 import java.util.*; |
27 import java.util.*; |
28 |
28 |
29 /** |
29 /** |
30 * This interface imposes a total ordering on the objects of each class that |
30 * This interface imposes a total ordering on the objects of each class that |
31 * implements it. This ordering is referred to as the class's <i>natural |
31 * implements it. This ordering is referred to as the class's <i>natural |
32 * ordering</i>, and the class's <tt>compareTo</tt> method is referred to as |
32 * ordering</i>, and the class's {@code compareTo} method is referred to as |
33 * its <i>natural comparison method</i>.<p> |
33 * its <i>natural comparison method</i>.<p> |
34 * |
34 * |
35 * Lists (and arrays) of objects that implement this interface can be sorted |
35 * Lists (and arrays) of objects that implement this interface can be sorted |
36 * automatically by {@link Collections#sort(List) Collections.sort} (and |
36 * automatically by {@link Collections#sort(List) Collections.sort} (and |
37 * {@link Arrays#sort(Object[]) Arrays.sort}). Objects that implement this |
37 * {@link Arrays#sort(Object[]) Arrays.sort}). Objects that implement this |
38 * interface can be used as keys in a {@linkplain SortedMap sorted map} or as |
38 * interface can be used as keys in a {@linkplain SortedMap sorted map} or as |
39 * elements in a {@linkplain SortedSet sorted set}, without the need to |
39 * elements in a {@linkplain SortedSet sorted set}, without the need to |
40 * specify a {@linkplain Comparator comparator}.<p> |
40 * specify a {@linkplain Comparator comparator}.<p> |
41 * |
41 * |
42 * The natural ordering for a class <tt>C</tt> is said to be <i>consistent |
42 * The natural ordering for a class {@code C} is said to be <i>consistent |
43 * with equals</i> if and only if <tt>e1.compareTo(e2) == 0</tt> has |
43 * with equals</i> if and only if {@code e1.compareTo(e2) == 0} has |
44 * the same boolean value as <tt>e1.equals(e2)</tt> for every |
44 * the same boolean value as {@code e1.equals(e2)} for every |
45 * <tt>e1</tt> and <tt>e2</tt> of class <tt>C</tt>. Note that <tt>null</tt> |
45 * {@code e1} and {@code e2} of class {@code C}. Note that {@code null} |
46 * is not an instance of any class, and <tt>e.compareTo(null)</tt> should |
46 * is not an instance of any class, and {@code e.compareTo(null)} should |
47 * throw a <tt>NullPointerException</tt> even though <tt>e.equals(null)</tt> |
47 * throw a {@code NullPointerException} even though {@code e.equals(null)} |
48 * returns <tt>false</tt>.<p> |
48 * returns {@code false}.<p> |
49 * |
49 * |
50 * It is strongly recommended (though not required) that natural orderings be |
50 * It is strongly recommended (though not required) that natural orderings be |
51 * consistent with equals. This is so because sorted sets (and sorted maps) |
51 * consistent with equals. This is so because sorted sets (and sorted maps) |
52 * without explicit comparators behave "strangely" when they are used with |
52 * without explicit comparators behave "strangely" when they are used with |
53 * elements (or keys) whose natural ordering is inconsistent with equals. In |
53 * elements (or keys) whose natural ordering is inconsistent with equals. In |
54 * particular, such a sorted set (or sorted map) violates the general contract |
54 * particular, such a sorted set (or sorted map) violates the general contract |
55 * for set (or map), which is defined in terms of the <tt>equals</tt> |
55 * for set (or map), which is defined in terms of the {@code equals} |
56 * method.<p> |
56 * method.<p> |
57 * |
57 * |
58 * For example, if one adds two keys <tt>a</tt> and <tt>b</tt> such that |
58 * For example, if one adds two keys {@code a} and {@code b} such that |
59 * {@code (!a.equals(b) && a.compareTo(b) == 0)} to a sorted |
59 * {@code (!a.equals(b) && a.compareTo(b) == 0)} to a sorted |
60 * set that does not use an explicit comparator, the second <tt>add</tt> |
60 * set that does not use an explicit comparator, the second {@code add} |
61 * operation returns false (and the size of the sorted set does not increase) |
61 * operation returns false (and the size of the sorted set does not increase) |
62 * because <tt>a</tt> and <tt>b</tt> are equivalent from the sorted set's |
62 * because {@code a} and {@code b} are equivalent from the sorted set's |
63 * perspective.<p> |
63 * perspective.<p> |
64 * |
64 * |
65 * Virtually all Java core classes that implement <tt>Comparable</tt> have natural |
65 * Virtually all Java core classes that implement {@code Comparable} have natural |
66 * orderings that are consistent with equals. One exception is |
66 * orderings that are consistent with equals. One exception is |
67 * <tt>java.math.BigDecimal</tt>, whose natural ordering equates |
67 * {@code java.math.BigDecimal}, whose natural ordering equates |
68 * <tt>BigDecimal</tt> objects with equal values and different precisions |
68 * {@code BigDecimal} objects with equal values and different precisions |
69 * (such as 4.0 and 4.00).<p> |
69 * (such as 4.0 and 4.00).<p> |
70 * |
70 * |
71 * For the mathematically inclined, the <i>relation</i> that defines |
71 * For the mathematically inclined, the <i>relation</i> that defines |
72 * the natural ordering on a given class C is:<pre> |
72 * the natural ordering on a given class C is:<pre>{@code |
73 * {(x, y) such that x.compareTo(y) <= 0}. |
73 * {(x, y) such that x.compareTo(y) <= 0}. |
74 * </pre> The <i>quotient</i> for this total order is: <pre> |
74 * }</pre> The <i>quotient</i> for this total order is: <pre>{@code |
75 * {(x, y) such that x.compareTo(y) == 0}. |
75 * {(x, y) such that x.compareTo(y) == 0}. |
76 * </pre> |
76 * }</pre> |
77 * |
77 * |
78 * It follows immediately from the contract for <tt>compareTo</tt> that the |
78 * It follows immediately from the contract for {@code compareTo} that the |
79 * quotient is an <i>equivalence relation</i> on <tt>C</tt>, and 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 <tt>C</tt>. When we say that a |
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 |
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 |
82 * quotient for the natural ordering is the equivalence relation defined by |
83 * the class's {@link Object#equals(Object) equals(Object)} method:<pre> |
83 * the class's {@link Object#equals(Object) equals(Object)} method:<pre> |
84 * {(x, y) such that x.equals(y)}. </pre><p> |
84 * {(x, y) such that x.equals(y)}. </pre><p> |
85 * |
85 * |
97 /** |
97 /** |
98 * Compares this object with the specified object for order. Returns a |
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 |
99 * negative integer, zero, or a positive integer as this object is less |
100 * than, equal to, or greater than the specified object. |
100 * than, equal to, or greater than the specified object. |
101 * |
101 * |
102 * <p>The implementor must ensure <tt>sgn(x.compareTo(y)) == |
102 * <p>The implementor must ensure |
103 * -sgn(y.compareTo(x))</tt> for all <tt>x</tt> and <tt>y</tt>. (This |
103 * {@code sgn(x.compareTo(y)) == -sgn(y.compareTo(x))} |
104 * implies that <tt>x.compareTo(y)</tt> must throw an exception iff |
104 * for all {@code x} and {@code y}. (This |
105 * <tt>y.compareTo(x)</tt> throws an exception.) |
105 * implies that {@code x.compareTo(y)} must throw an exception iff |
|
106 * {@code y.compareTo(x)} throws an exception.) |
106 * |
107 * |
107 * <p>The implementor must also ensure that the relation is transitive: |
108 * <p>The implementor must also ensure that the relation is transitive: |
108 * <tt>(x.compareTo(y)>0 && y.compareTo(z)>0)</tt> implies |
109 * {@code (x.compareTo(y) > 0 && y.compareTo(z) > 0)} implies |
109 * <tt>x.compareTo(z)>0</tt>. |
110 * {@code x.compareTo(z) > 0}. |
110 * |
111 * |
111 * <p>Finally, the implementor must ensure that <tt>x.compareTo(y)==0</tt> |
112 * <p>Finally, the implementor must ensure that {@code x.compareTo(y)==0} |
112 * implies that <tt>sgn(x.compareTo(z)) == sgn(y.compareTo(z))</tt>, for |
113 * implies that {@code sgn(x.compareTo(z)) == sgn(y.compareTo(z))}, for |
113 * all <tt>z</tt>. |
114 * all {@code z}. |
114 * |
115 * |
115 * <p>It is strongly recommended, but <i>not</i> strictly required that |
116 * <p>It is strongly recommended, but <i>not</i> strictly required that |
116 * <tt>(x.compareTo(y)==0) == (x.equals(y))</tt>. Generally speaking, any |
117 * {@code (x.compareTo(y)==0) == (x.equals(y))}. Generally speaking, any |
117 * class that implements the <tt>Comparable</tt> interface and violates |
118 * class that implements the {@code Comparable} interface and violates |
118 * this condition should clearly indicate this fact. The recommended |
119 * this condition should clearly indicate this fact. The recommended |
119 * language is "Note: this class has a natural ordering that is |
120 * language is "Note: this class has a natural ordering that is |
120 * inconsistent with equals." |
121 * inconsistent with equals." |
121 * |
122 * |
122 * <p>In the foregoing description, the notation |
123 * <p>In the foregoing description, the notation |
123 * <tt>sgn(</tt><i>expression</i><tt>)</tt> designates the mathematical |
124 * {@code sgn(}<i>expression</i>{@code )} designates the mathematical |
124 * <i>signum</i> function, which is defined to return one of <tt>-1</tt>, |
125 * <i>signum</i> function, which is defined to return one of {@code -1}, |
125 * <tt>0</tt>, or <tt>1</tt> according to whether the value of |
126 * {@code 0}, or {@code 1} according to whether the value of |
126 * <i>expression</i> is negative, zero or positive. |
127 * <i>expression</i> is negative, zero or positive. |
127 * |
128 * |
128 * @param o the object to be compared. |
129 * @param o the object to be compared. |
129 * @return a negative integer, zero, or a positive integer as this object |
130 * @return a negative integer, zero, or a positive integer as this object |
130 * is less than, equal to, or greater than the specified object. |
131 * is less than, equal to, or greater than the specified object. |