sample/java.util.SortedSet.txt

   1 *java.util.SortedSet* *SortedSet* A set that further guarantees that its iterato
   2
   3 public interface interface SortedSet
   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 associated with this s
  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 sorted se
  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 sorted s
  20 |java.util.SortedSet.tailSet(E)|Returns a view of the portion of this sorted se
  21
  22 *java.util.SortedSet_Description*
  23
  24 A set that further guarantees that its iterator will traverse the set in
  25 ascending element order, sorted according to the natural ordering of its
  26 elements (see Comparable), or by a Comparator provided at sorted set creation
  27 time. Several additional operations are provided to take advantage of the
  28 ordering. (This interface is the set analogue of SortedMap.)
  29
  30 All elements inserted into an sorted set must implement the Comparable
  31 interface (or be accepted by the specified Comparator). Furthermore, all such
  32 elements must be mutually comparable: e1.compareTo(e2) (or
  33 comparator.compare(e1, e2)) must not throw a ClassCastException for any
  34 elements e1 and e2 in the sorted set. Attempts to violate this restriction will
  35 cause the offending method or constructor invocation to throw a
  36 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 order 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 elements' natural
  56 ordering. 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) but the JDK implementation (the TreeSet class)
  60 complies.
  61
  62 This interface is a member of the <a href="/../guide/collections/index.html">
  63 Java Collections Framework.
  64
  65
  66 *java.util.SortedSet.comparator()*
  67
  68 public |java.util.Comparator| comparator()
  69
  70 Returns the comparator associated with this sorted set, or null if it uses its
  71 elements' natural ordering.
  72
  73
  74     Returns: the comparator associated with this sorted set, or null if it uses its
  75              elements' natural ordering.
  76 *java.util.SortedSet.first()*
  77
  78 public |java.lang.Object| first()
  79
  80 Returns the first (lowest) element currently in this sorted set.
  81
  82
  83     Returns: the first (lowest) element currently in this sorted set.
  84 *java.util.SortedSet.headSet(E)*
  85
  86 public |java.util.SortedSet| headSet(java.lang.Object toElement)
  87
  88 Returns a view of the portion of this sorted set whose elements are strictly
  89 less than toElement. The returned sorted set is backed by this sorted set, so
  90 changes in the returned sorted set are reflected in this sorted set, and
  91 vice-versa. The returned sorted set supports all optional set operations.
  92
  93 The sorted set returned by this method will throw an IllegalArgumentException
  94 if the user attempts to insert a element outside the specified range.
  95
  96 Note: this method always returns a view that does not contain its (high)
  97 endpoint. If you need a view that does contain this endpoint, and the element
  98 type allows for calculation of the successor a given value, merely request a
  99 headSet bounded by successor(highEndpoint). For example, suppose that s is a
 100 sorted set of strings. The following idiom obtains a view containing all of the
 101 strings in s that are less than or equal to high: SortedSet head =
 102 s.headSet(high+"\0");
 103
 104     toElement - high endpoint (exclusive) of the headSet.
 105
 106     Returns: a view of the specified initial range of this sorted set.
 107 *java.util.SortedSet.last()*
 108
 109 public |java.lang.Object| last()
 110
 111 Returns the last (highest) element currently in this sorted set.
 112
 113
 114     Returns: the last (highest) element currently in this sorted set.
 115 *java.util.SortedSet.subSet(E,E)*
 116
 117 public |java.util.SortedSet| subSet(
 118   java.lang.Object fromElement,
 119   java.lang.Object toElement)
 120
 121 Returns a view of the portion of this sorted set whose elements range from
 122 fromElement, inclusive, to toElement, exclusive. (If fromElement and toElement
 123 are equal, the returned sorted set is empty.) The returned sorted set is backed
 124 by this sorted set, so changes in the returned sorted set are reflected in this
 125 sorted set, and vice-versa. The returned sorted set supports all optional set
 126 operations that this sorted set supports.
 127
 128 The sorted set returned by this method will throw an IllegalArgumentException
 129 if the user attempts to insert a element outside the specified range.
 130
 131 Note: this method always returns a half-open range (which includes its low
 132 endpoint but not its high endpoint). If you need a closed range (which includes
 133 both endpoints), and the element type allows for calculation of the successor a
 134 given value, merely request the subrange from lowEndpoint to
 135 successor(highEndpoint). For example, suppose that s is a sorted set of
 136 strings. The following idiom obtains a view containing all of the strings in s
 137 from low to high, inclusive:
 138
 139 SortedSet sub = s.subSet(low, high+"\0");
 140
 141 A similar technique can be used to generate an open range (which contains
 142 neither endpoint). The following idiom obtains a view containing all of the
 143 Strings in s from low to high, exclusive:
 144
 145 SortedSet sub = s.subSet(low+"\0", high);
 146
 147     fromElement - low endpoint (inclusive) of the subSet.
 148     toElement - high endpoint (exclusive) of the subSet.
 149
 150     Returns: a view of the specified range within this sorted set.
 151 *java.util.SortedSet.tailSet(E)*
 152
 153 public |java.util.SortedSet| tailSet(java.lang.Object fromElement)
 154
 155 Returns a view of the portion of this sorted set whose elements are greater
 156 than or equal to fromElement. The returned sorted set is backed by this sorted
 157 set, so changes in the returned sorted set are reflected in this sorted set,
 158 and vice-versa. The returned sorted set supports all optional set operations.
 159
 160 The sorted set returned by this method will throw an IllegalArgumentException
 161 if the user attempts to insert a element outside the specified range.
 162
 163 Note: this method always returns a view that contains its (low) endpoint. If
 164 you need a view that does not contain this endpoint, and the element type
 165 allows for calculation of the successor a given value, merely request a tailSet
 166 bounded by successor(lowEndpoint). For example, suppose that s is a sorted set
 167 of strings. The following idiom obtains a view containing all of the strings in
 168 s that are strictly greater than low:
 169
 170 SortedSet tail = s.tailSet(low+"\0");
 171
 172     fromElement - low endpoint (inclusive) of the tailSet.
 173
 174     Returns: a view of the specified final range of this sorted set.
 175