totalcross.util

Interface Comparator4D<T>

public interface Comparator4D<T>

Interface for objects that specify an ordering between objects. The ordering should be total, such that any two objects of the correct type can be compared, and the comparison is reflexive, anti-symmetric, and transitive. It is also recommended that the comparator be consistent with equals, although this is not a strict requirement. A relation is consistent with equals if these two statements always have the same results (if no exceptions occur):
compare((Object) e1, (Object) e2) == 0 and e1.equals((Object) e2)
Comparators that violate consistency with equals may cause strange behavior in sorted lists and sets. For example, a case-sensitive dictionary order comparison of Strings is consistent with equals, but if it is case-insensitive it is not, because "abc" and "ABC" compare as equal even though "abc".equals("ABC") returns false.

In general, Comparators should be Serializable, because when they are passed to Serializable data structures such as SortedMap or SortedSet, the entire data structure will only serialize correctly if the comparator is Serializable.

Since:

1.2

See Also:

Comparable, TreeMap, TreeSet, SortedMap, SortedSet, Arrays#sort(Object[], Comparator)

Method Summary

Modifier and Type	Method and Description
int	compare(T o1, T o2) Return an integer that is negative, zero or positive depending on whether the first argument is less than, equal to or greater than the second according to this ordering.
boolean	equals(java.lang.Object obj) Return true if the object is equal to this object.

Method Detail

compare

int compare(T o1,
            T o2)

Return an integer that is negative, zero or positive depending on whether the first argument is less than, equal to or greater than the second according to this ordering. This method should obey the following contract:

• if compare(a, b) < 0 then compare(b, a) > 0
• if compare(a, b) throws an exception, so does compare(b, a)
• if compare(a, b) < 0 and compare(b, c) < 0 then compare(a, c) < 0
• if compare(a, b) == 0 then compare(a, c) and compare(b, c) must have the same sign

To be consistent with equals, the following additional constraint is in place:

• if a.equals(b) or both a and b are null, then compare(a, b) == 0.

Although it is permissible for a comparator to provide an order inconsistent with equals, that should be documented.

Parameters:

o1 - the first object

o2 - the second object

Returns:

the comparison

Throws:

java.lang.ClassCastException - if the elements are not of types that can be compared by this ordering.

equals

boolean equals(java.lang.Object obj)

Return true if the object is equal to this object. To be considered equal, the argument object must satisfy the constraints of Object.equals(), be a Comparator, and impose the same ordering as this Comparator. The default implementation inherited from Object is usually adequate.

Overrides:

equals in class java.lang.Object

Parameters:

obj - The object

Returns:

true if it is a Comparator that imposes the same order

See Also:

Object.equals(Object)