sample/java.util.Comparator.txt

   1 *java.util.Comparator* *Comparator* A comparison function, which imposes a total
   2
   3 public interface interface Comparator<T>
   4
   5
   6 |java.util.Comparator_Description|
   7 |java.util.Comparator_Fields|
   8 |java.util.Comparator_Constructors|
   9 |java.util.Comparator_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.Comparator_Methods*
  14 |java.util.Comparator.compare(T,T)|Compares its two arguments for order.
  15 |java.util.Comparator.equals(Object)|Indicates whether some other object is equ
  16
  17 *java.util.Comparator_Description*
  18
  19 A comparison function, which imposes a total ordering on some collection of
  20 objects. Comparators can be passed to a sort method (such as
  21 Collections.sort(|java.util.Collections|) or Arrays.sort(|java.util.Arrays|) )
  22 to allow precise control over the sort order. Comparators can also be used to
  23 control the order of certain data structures (such as sorted
  24 sets(|java.util.SortedSet|) or sorted maps(|java.util.SortedMap|) ), or to
  25 provide an ordering for collections of objects that don't have a natural
  26 ordering(|java.lang.Comparable|) .
  27
  28 The ordering imposed by a comparator c on a set of elements S is said to be
  29 consistent with equals if and only if c.compare(e1, e2)==0 has the same boolean
  30 value as e1.equals(e2) for every e1 and e2 in S.
  31
  32 Caution should be exercised when using a comparator capable of imposing an
  33 ordering inconsistent with equals to order a sorted set (or sorted map).
  34 Suppose a sorted set (or sorted map) with an explicit comparator c is used with
  35 elements (or keys) drawn from a set S. If the ordering imposed by c on S is
  36 inconsistent with equals, the sorted set (or sorted map) will behave
  37 "strangely." In particular the sorted set (or sorted map) will violate the
  38 general contract for set (or map), which is defined in terms of equals.
  39
  40 For example, suppose one adds two elementsaandbsuch that(a.equals(b)
  41 c.compare(a, b) != 0)to an emptyTreeSetwith comparatorc. The secondaddoperation
  42 will return true (and the size of the tree set will increase) becauseaandbare
  43 not equivalent from the tree set's perspective, even though this is contrary to
  44 the specification of the Set.add(|java.util.Set|) method.
  45
  46 Note: It is generally a good idea for comparators to also implement
  47 java.io.Serializable, as they may be used as ordering methods in serializable
  48 data structures (like (|java.util.TreeSet|) , (|java.util.TreeMap|) ). In order
  49 for the data structure to serialize successfully, the comparator (if provided)
  50 must implement Serializable.
  51
  52 For the mathematically inclined, the relation that defines the imposed ordering
  53 that a given comparator c imposes on a given set of objects S is:
  54
  55 {(x, y) such that c.compare(x, y) <= 0}.
  56
  57 The quotient for this total order is:
  58
  59 {(x, y) such that c.compare(x, y) == 0}.
  60
  61 It follows immediately from the contract for compare that the quotient is an
  62 equivalence relation on S, and that the imposed ordering is a total order on S.
  63 When we say that the ordering imposed by c on S is consistent with equals, we
  64 mean that the quotient for the ordering is the equivalence relation defined by
  65 the objects' equals(Object)(|java.lang.Object|) method(s):
  66
  67 {(x, y) such that x.equals(y)}.
  68
  69 This interface is a member of the <a
  70 href="/../technotes/guides/collections/index.html"> Java Collections Framework.
  71
  72
  73
  74 *java.util.Comparator.compare(T,T)*
  75
  76 public int compare(
  77   T o1,
  78   T o2)
  79
  80 Compares its two arguments for order. Returns a negative integer, zero, or a
  81 positive integer as the first argument is less than, equal to, or greater than
  82 the second.
  83
  84 In the foregoing description, the notation sgn(expression) designates the
  85 mathematical signum function, which is defined to return one of -1, 0, or 1
  86 according to whether the value of expression is negative, zero or positive.
  87
  88 The implementor must ensure that sgn(compare(x, y)) == -sgn(compare(y, x)) for
  89 all x and y. (This implies that compare(x, y) must throw an exception if and
  90 only if compare(y, x) throws an exception.)
  91
  92 The implementor must also ensure that the relation is transitive: ((compare(x,
  93 y)>0) and and (compare(y, z)>0)) implies compare(x, z)>0.
  94
  95 Finally, the implementor must ensure that compare(x, y)==0 implies that
  96 sgn(compare(x, z))==sgn(compare(y, z)) for all z.
  97
  98 It is generally the case, but not strictly required that (compare(x, y)==0) ==
  99 (x.equals(y)). Generally speaking, any comparator that violates this condition
 100 should clearly indicate this fact. The recommended language is "Note: this
 101 comparator imposes orderings that are inconsistent with equals."
 102
 103
 104     o1 - the first object to be compared.
 105     o2 - the second object to be compared.
 106
 107     Returns: a negative integer, zero, or a positive integer as the first argument is less
 108              than, equal to, or greater than the second.
 109
 110 *java.util.Comparator.equals(Object)*
 111
 112 public boolean equals(java.lang.Object obj)
 113
 114 Indicates whether some other object is equal to this comparator. This method
 115 must obey the general contract of (|java.lang.Object|) . Additionally, this
 116 method can return true only if the specified object is also a comparator and it
 117 imposes the same ordering as this comparator. Thus, comp1.equals(comp2) implies
 118 that sgn(comp1.compare(o1, o2))==sgn(comp2.compare(o1, o2)) for every object
 119 reference o1 and o2.
 120
 121 Note that it is always safe not to override Object.equals(Object). However,
 122 overriding this method may, in some cases, improve performance by allowing
 123 programs to determine that two distinct comparators impose the same order.
 124
 125
 126     obj - the reference object with which to compare.
 127
 128     Returns: true only if the specified object is also a comparator and it imposes the same
 129              ordering as this comparator.
 130
 131