sample/java.util.SortedSet.txt

   1 *java.util.SortedSet* *SortedSet* ASetthat further provides a total ordering on
   2
   3 public interface interface SortedSet<E>
   4
   5   implements |java.util.Set|
   6
   7 |java.util.SortedSet_Description|
   8 |java.util.SortedSet_Fields|
   9 |java.util.SortedSet_Constructors|
  10 |java.util.SortedSet_Methods|
  11
  12 ================================================================================
  13
  14 *java.util.SortedSet_Methods*
  15 |java.util.SortedSet.comparator()|Returns the comparator used to order the elem
  16 |java.util.SortedSet.first()|Returns the first (lowest) element currently in th
  17 |java.util.SortedSet.headSet(E)|Returns a view of the portion of this set whose
  18 |java.util.SortedSet.last()|Returns the last (highest) element currently in thi
  19 |java.util.SortedSet.subSet(E,E)|Returns a view of the portion of this set whos
  20 |java.util.SortedSet.tailSet(E)|Returns a view of the portion of this set whose
  21
  22 *java.util.SortedSet_Description*
  23
  24 A (|java.util.Set|) that further provides a total ordering on its elements. The
  25 elements are ordered using their natural ordering(|java.lang.Comparable|) , or
  26 by a (|java.util.Comparator|) typically provided at sorted set creation time.
  27 The set's iterator will traverse the set in ascending element order. Several
  28 additional operations are provided to take advantage of the ordering. (This
  29 interface is the set analogue of (|java.util.SortedMap|) .)
  30
  31 All elements inserted into a sorted set must implement the Comparable interface
  32 (or be accepted by the specified comparator). Furthermore, all such elements
  33 must be mutually comparable: e1.compareTo(e2) (or comparator.compare(e1, e2))
  34 must not throw a ClassCastException for any elements e1 and e2 in the sorted
  35 set. Attempts to violate this restriction will cause the offending method or
  36 constructor invocation to throw a ClassCastException.
  37
  38 Note that the ordering maintained by a sorted set (whether or not an explicit
  39 comparator is provided) must be consistent with equals if the sorted set is to
  40 correctly implement the Set interface. (See the Comparable interface or
  41 Comparator interface for a precise definition of consistent with equals.) This
  42 is so because the Set interface is defined in terms of the equals operation,
  43 but a sorted set performs all element comparisons using its compareTo (or
  44 compare) method, so two elements that are deemed equal by this method are, from
  45 the standpoint of the sorted set, equal. The behavior of a sorted set is
  46 well-defined even if its ordering is inconsistent with equals; it just fails to
  47 obey the general contract of the Set interface.
  48
  49 All general-purpose sorted set implementation classes should provide four
  50 "standard" constructors: 1) A void (no arguments) constructor, which creates an
  51 empty sorted set sorted according to the natural ordering of its elements. 2) A
  52 constructor with a single argument of type Comparator, which creates an empty
  53 sorted set sorted according to the specified comparator. 3) A constructor with
  54 a single argument of type Collection, which creates a new sorted set with the
  55 same elements as its argument, sorted according to the natural ordering of the
  56 elements. 4) A constructor with a single argument of type SortedSet, which
  57 creates a new sorted set with the same elements and the same ordering as the
  58 input sorted set. There is no way to enforce this recommendation, as interfaces
  59 cannot contain constructors.
  60
  61 Note: several methods return subsets with restricted ranges. Such ranges are
  62 half-open, that is, they include their low endpoint but not their high endpoint
  63 (where applicable). If you need a closed range (which includes both endpoints),
  64 and the element type allows for calculation of the successor of a given value,
  65 merely request the subrange from lowEndpoint to successor(highEndpoint). For
  66 example, suppose that s is a sorted set of strings. The following idiom obtains
  67 a view containing all of the strings in s from low to high, inclusive:
  68
  69 SortedSet<String> sub = s.subSet(low, high+"\0");
  70
  71 A similar technique can be used to generate an open range (which contains
  72 neither endpoint). The following idiom obtains a view containing all of the
  73 Strings in s from low to high, exclusive:
  74
  75 SortedSet<String> sub = s.subSet(low+"\0", high);
  76
  77 This interface is a member of the <a
  78 href="/../technotes/guides/collections/index.html"> Java Collections Framework.
  79
  80
  81
  82 *java.util.SortedSet.comparator()*
  83
  84 public |java.util.Comparator|<? super E> comparator()
  85
  86 Returns the comparator used to order the elements in this set, or null if this
  87 set uses the natural ordering(|java.lang.Comparable|) of its elements.
  88
  89
  90
  91     Returns: the comparator used to order the elements in this set, or null if this set uses
  92              the natural ordering of its elements
  93
  94 *java.util.SortedSet.first()*
  95
  96 public |E| first()
  97
  98 Returns the first (lowest) element currently in this set.
  99
 100
 101
 102     Returns: the first (lowest) element currently in this set
 103
 104 *java.util.SortedSet.headSet(E)*
 105
 106 public |java.util.SortedSet|<E> headSet(E toElement)
 107
 108 Returns a view of the portion of this set whose elements are strictly less than
 109 toElement. The returned set is backed by this set, so changes in the returned
 110 set are reflected in this set, and vice-versa. The returned set supports all
 111 optional set operations that this set supports.
 112
 113 The returned set will throw an IllegalArgumentException on an attempt to insert
 114 an element outside its range.
 115
 116
 117     toElement - high endpoint (exclusive) of the returned set
 118
 119     Returns: a view of the portion of this set whose elements are strictly less than
 120              toElement
 121
 122 *java.util.SortedSet.last()*
 123
 124 public |E| last()
 125
 126 Returns the last (highest) element currently in this set.
 127
 128
 129
 130     Returns: the last (highest) element currently in this set
 131
 132 *java.util.SortedSet.subSet(E,E)*
 133
 134 public |java.util.SortedSet|<E> subSet(
 135   E fromElement,
 136   E toElement)
 137
 138 Returns a view of the portion of this set whose elements range from
 139 fromElement, inclusive, to toElement, exclusive. (If fromElement and toElement
 140 are equal, the returned set is empty.) The returned set is backed by this set,
 141 so changes in the returned set are reflected in this set, and vice-versa. The
 142 returned set supports all optional set operations that this set supports.
 143
 144 The returned set will throw an IllegalArgumentException on an attempt to insert
 145 an element outside its range.
 146
 147
 148     fromElement - low endpoint (inclusive) of the returned set
 149     toElement - high endpoint (exclusive) of the returned set
 150
 151     Returns: a view of the portion of this set whose elements range from fromElement,
 152              inclusive, to toElement, exclusive
 153
 154 *java.util.SortedSet.tailSet(E)*
 155
 156 public |java.util.SortedSet|<E> tailSet(E fromElement)
 157
 158 Returns a view of the portion of this set whose elements are greater than or
 159 equal to fromElement. The returned set is backed by this set, so changes in the
 160 returned set are reflected in this set, and vice-versa. The returned set
 161 supports all optional set operations that this set supports.
 162
 163 The returned set will throw an IllegalArgumentException on an attempt to insert
 164 an element outside its range.
 165
 166
 167     fromElement - low endpoint (inclusive) of the returned set
 168
 169     Returns: a view of the portion of this set whose elements are greater than or equal to
 170              fromElement
 171
 172