+ * + * The ordering imposed by a comparator c on a set of elements + * S is said to be consistent with equals if and only if + * c.compare(e1, e2)==0 has the same boolean value as + * e1.equals(e2) for every e1 and e2 in + * S.
+ * + * Caution should be exercised when using a comparator capable of imposing an + * ordering inconsistent with equals to order a sorted set (or sorted map). + * Suppose a sorted set (or sorted map) with an explicit comparator c + * is used with elements (or keys) drawn from a set S. If the + * ordering imposed by c on S is inconsistent with equals, + * the sorted set (or sorted map) will behave "strangely." In particular the + * sorted set (or sorted map) will violate the general contract for set (or + * map), which is defined in terms of equals.
+ * + * For example, suppose one adds two elements {@code a} and {@code b} such that + * {@code (a.equals(b) && c.compare(a, b) != 0)} + * to an empty {@code TreeSet} with comparator {@code c}. + * The second {@code add} operation will return + * true (and the size of the tree set will increase) because {@code a} and + * {@code b} are not equivalent from the tree set's perspective, even though + * this is contrary to the specification of the + * {@link Set#add Set.add} method.
+ * + * Note: It is generally a good idea for comparators to also implement + * java.io.Serializable, as they may be used as ordering methods in + * serializable data structures (like {@link TreeSet}, {@link TreeMap}). In + * order for the data structure to serialize successfully, the comparator (if + * provided) must implement Serializable.
+ * + * For the mathematically inclined, the relation that defines the + * imposed ordering that a given comparator c imposes on a + * given set of objects S is:
+ * {(x, y) such that c.compare(x, y) <= 0}.
+ * The quotient for this total order is:
+ * {(x, y) such that c.compare(x, y) == 0}.
+ *
+ *
+ * It follows immediately from the contract for compare that the
+ * quotient is an equivalence relation on S, and that the
+ * imposed ordering is a total order on S. When we say that
+ * the ordering imposed by c on S is consistent with
+ * equals, we mean that the quotient for the ordering is the equivalence
+ * relation defined by the objects' {@link Object#equals(Object)
+ * equals(Object)} method(s):
+ * {(x, y) such that x.equals(y)}.
+ *
+ * Unlike {@code Comparable}, a comparator may optionally permit + * comparison of null arguments, while maintaining the requirements for + * an equivalence relation. + * + *
This interface is a member of the
+ *
+ * Java Collections Framework.
+ *
+ * @param
+ *
+ * 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
+ * expression is negative, zero or positive.
+ *
+ * The implementor must ensure that sgn(compare(x, y)) ==
+ * -sgn(compare(y, x)) for all x and y. (This
+ * implies that compare(x, y) must throw an exception if and only
+ * if compare(y, x) throws an exception.)
+ *
+ * The implementor must also ensure that the relation is transitive:
+ * ((compare(x, y)>0) && (compare(y, z)>0)) implies
+ * compare(x, z)>0.
+ *
+ * Finally, the implementor must ensure that compare(x, y)==0
+ * implies that sgn(compare(x, z))==sgn(compare(y, z)) for all
+ * z.
+ *
+ * It is generally the case, but not strictly required that
+ * (compare(x, y)==0) == (x.equals(y)). Generally speaking,
+ * any comparator that violates this condition should clearly indicate
+ * this fact. The recommended language is "Note: this comparator
+ * imposes orderings that are inconsistent with equals."
+ *
+ * @param o1 the first object to be compared.
+ * @param o2 the second object to be compared.
+ * @return a negative integer, zero, or a positive integer as the
+ * first argument is less than, equal to, or greater than the
+ * second.
+ * @throws NullPointerException if an argument is null and this
+ * comparator does not permit null arguments
+ * @throws ClassCastException if the arguments' types prevent them from
+ * being compared by this comparator.
+ */
+ int compare(T o1, T o2);
+
+ /**
+ * Indicates whether some other object is "equal to" this
+ * comparator. This method must obey the general contract of
+ * {@link Object#equals(Object)}. Additionally, this method can return
+ * true only if the specified object is also a comparator
+ * and it imposes the same ordering as this comparator. Thus,
+ *
+ *
+ * Note that it is always safe not to override
+ * Object.equals(Object). However, overriding this method may,
+ * in some cases, improve performance by allowing programs to determine
+ * that two distinct comparators impose the same order.
+ *
+ * @param obj the reference object with which to compare.
+ * @return comp1.equals(comp2) implies that sgn(comp1.compare(o1,
+ * o2))==sgn(comp2.compare(o1, o2)) for every object reference
+ * o1 and o2.true only if the specified object is also
+ * a comparator and it imposes the same ordering as this
+ * comparator.
+ * @see Object#equals(Object)
+ * @see Object#hashCode()
+ */
+ boolean equals(Object obj);
+}