29 |
|
|
30 |
/** |
/** |
31 |
* Interface for objects that specify an ordering between objects. The ordering |
* Interface for objects that specify an ordering between objects. The ordering |
32 |
* can be <EM>total</EM>, such that two objects only compare equal if they are |
* should be <em>total</em>, such that any two objects of the correct type |
33 |
* equal by the equals method, or <EM>partial</EM> such that this is not |
* can be compared, and the comparison is reflexive, anti-symmetric, and |
34 |
* necessarily true. For example, a case-sensitive dictionary order comparison |
* transitive. It is also recommended that the comparator be <em>consistent |
35 |
* of Strings is total, but if it is case-insensitive it is partial, because |
* with equals</em>, although this is not a strict requirement. A relation |
36 |
* "abc" and "ABC" compare as equal even though "abc".equals("ABC") returns |
* is consistent with equals if these two statements always have the same |
37 |
* false. |
* results (if no exceptions occur):<br> |
38 |
|
* <code>compare((Object) e1, (Object) e2) == 0</code> and |
39 |
|
* <code>e1.equals((Object) e2)</code><br> |
40 |
|
* Comparators that violate consistency with equals may cause strange behavior |
41 |
|
* in sorted lists and sets. For example, a case-sensitive dictionary order |
42 |
|
* comparison of Strings is consistent with equals, but if it is |
43 |
|
* case-insensitive it is not, because "abc" and "ABC" compare as equal even |
44 |
|
* though "abc".equals("ABC") returns false. |
45 |
* <P> |
* <P> |
46 |
* In general, Comparators should be Serializable, because when they are passed |
* In general, Comparators should be Serializable, because when they are passed |
47 |
* to Serializable data structures such as SortedMap or SortedSet, the entire |
* to Serializable data structures such as SortedMap or SortedSet, the entire |
48 |
* data structure will only serialize correctly if the comparator is |
* data structure will only serialize correctly if the comparator is |
49 |
* Serializable. |
* Serializable. |
50 |
|
* |
51 |
|
* @author Original author unknown |
52 |
|
* @author Eric Blake <ebb9@email.byu.edu> |
53 |
|
* @see Comparable |
54 |
|
* @see TreeMap |
55 |
|
* @see TreeSet |
56 |
|
* @see SortedMap |
57 |
|
* @see SortedSet |
58 |
|
* @see Arrays#sort(Object[], Comparator) |
59 |
|
* @see java.io.Serializable |
60 |
|
* @since 1.2 |
61 |
|
* @status updated to 1.4 |
62 |
*/ |
*/ |
63 |
public interface Comparator |
public interface Comparator |
64 |
{ |
{ |
65 |
/** |
/** |
66 |
* Return an integer that is negative, zero or positive depending on whether |
* Return an integer that is negative, zero or positive depending on whether |
67 |
* the first argument is less than, equal to or greater than the second |
* the first argument is less than, equal to or greater than the second |
68 |
* according to this ordering. This method should obey the following contract: |
* according to this ordering. This method should obey the following |
69 |
* <UL> |
* contract: |
70 |
* <LI>if compare(a, b) < 0 then compare(b, a) > 0</LI> |
* <ul> |
71 |
* <LI>if compare(a, b) throws an exception, so does compare(b, a)</LI> |
* <li>if compare(a, b) < 0 then compare(b, a) > 0</li> |
72 |
* <LI>if compare(a, b) < 0 and compare(b, c) < 0 then compare(a, c) |
* <li>if compare(a, b) throws an exception, so does compare(b, a)</li> |
73 |
* < 0</LI> |
* <li>if compare(a, b) < 0 and compare(b, c) < 0 then compare(a, c) |
74 |
* <LI>if a.equals(b) or both a and b are null, then compare(a, b) == 0. |
* < 0</li> |
75 |
* The converse need not be true, but if it is, this Comparator |
* <li>if compare(a, b) == 0 then compare(a, c) and compare(b, c) must |
76 |
* specifies a <EM>total</EM> ordering.</LI> |
* have the same sign</li |
77 |
* </UL> |
* </ul> |
78 |
|
* To be consistent with equals, the following additional constraint is |
79 |
|
* in place: |
80 |
|
* <ul> |
81 |
|
* <li>if a.equals(b) or both a and b are null, then |
82 |
|
* compare(a, b) == 0.</li> |
83 |
|
* </ul><p> |
84 |
* |
* |
85 |
|
* Although it is permissible for a comparator to provide an order |
86 |
|
* inconsistent with equals, that should be documented. |
87 |
|
* |
88 |
|
* @param o1 the first object |
89 |
|
* @param o2 the second object |
90 |
|
* @return the comparison |
91 |
* @throws ClassCastException if the elements are not of types that can be |
* @throws ClassCastException if the elements are not of types that can be |
92 |
* compared by this ordering. |
* compared by this ordering. |
93 |
*/ |
*/ |
94 |
int compare(Object o1, Object o2); |
int compare(Object o1, Object o2); |
95 |
|
|
97 |
* Return true if the object is equal to this object. To be |
* Return true if the object is equal to this object. To be |
98 |
* considered equal, the argument object must satisfy the constraints |
* considered equal, the argument object must satisfy the constraints |
99 |
* of <code>Object.equals()</code>, be a Comparator, and impose the |
* of <code>Object.equals()</code>, be a Comparator, and impose the |
100 |
* same ordering as this Comparator. |
* same ordering as this Comparator. The default implementation |
101 |
|
* inherited from Object is usually adequate. |
102 |
|
* |
103 |
* @param obj The object |
* @param obj The object |
104 |
|
* @return true if it is a Comparator that imposes the same order |
105 |
|
* @see Object#equals(Object) |
106 |
*/ |
*/ |
107 |
boolean equals(Object obj); |
boolean equals(Object obj); |
108 |
} |
} |