public interface Comparator<T>
A comparison function, which imposes a
total ordering
on some collection of objects. Comparators can be passed to a sort method (such as
Collections.sort
or
Arrays.sort
Collections.sort
) to allow precise control over the sort order. Comparators can also be used to control the order of certain data structures (such as
sorted sets
TreeSet
or
sorted maps
), or to provide an ordering for collections of objects that don't have a
natural ordering
.
TreeMap
).
The ordering imposed by a
comparator
Comparator
c
on a set of elements
S
is said to be
consistent with equals
if and only if
c.compare(e1, e2)==0
(compare((Object)e1, (Object)e2)==0)
has the same boolean value as
e1.equals(e2)
e1.equals((Object)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
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, if one adds two keys
a
and
b
such that
(a.equals(b)
(a.equals((Object)b)
&&
c.compare(a, b)
c.compare((Object)a, (Object)b)
!= 0)
to a sorted set with comparator
c
, the second
add
operation will return false (and the size of the sorted set will not increase) because
a
and
b
are equivalent from the sorted set's perspective.
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
TreeSet
,
TreeMap
). In order for the data structure to serialize successfully, the comparator (if provided) must implement
TreeSet
,
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
total order
that a given comparator
c
imposes on a given set of objects
S
is:
{(x, y) such thatThe quotient for this total order is:c.compare(x, y)
c.compare((Object)x, (Object)y)<= 0}.
{(x, y) such thatIt follows immediately from the contract for compare that the quotient is an equivalence relation on S , and that thec.compare(x, y)
c.compare((Object)x, (Object)y)== 0}.
{(x, y) such thatx.equals(y)}.
x.equals((Object)y)}.
This interface is a member of the Java Collections Framework .
Method Summary | |
---|---|
int |
compare
(
T
o1,
T
o2) Compares its two arguments for order. |
boolean |
equals
(
Object
Indicates whether some other object is "equal to" this ![]() ![]() |
Method Detail |
---|
int compare(T o1, T o2)
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
implementer
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."
boolean equals(Object obj)
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
Comparators
impose the same order.