/[classpath]/classpath/java/util/Comparator.java
ViewVC logotype

Diff of /classpath/java/util/Comparator.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.5 by tromey, Fri Aug 31 22:05:51 2001 UTC revision 1.6 by ericb, Mon Oct 15 14:53:51 2001 UTC
# Line 29  package java.util; Line 29  package java.util;
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) &lt; 0 then compare(b, a) &gt; 0</LI>     * <ul>
71     *   <LI>if compare(a, b) throws an exception, so does compare(b, a)</LI>     *   <li>if compare(a, b) &lt; 0 then compare(b, a) &gt; 0</li>
72     *   <LI>if compare(a, b) &lt; 0 and compare(b, c) &lt; 0 then compare(a, c)     *   <li>if compare(a, b) throws an exception, so does compare(b, a)</li>
73     *       &lt; 0</LI>     *   <li>if compare(a, b) &lt; 0 and compare(b, c) &lt; 0 then compare(a, c)
74     *   <LI>if a.equals(b) or both a and b are null, then compare(a, b) == 0.     *       &lt; 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    
# Line 66  public interface Comparator Line 97  public interface Comparator
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  }  }

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26