1 *java.util.TreeSet* *TreeSet* This class implements the Set interface, backed by
4 extends |java.util.AbstractSet|
5 implements |java.util.SortedSet|
9 |java.util.TreeSet_Description|
10 |java.util.TreeSet_Fields|
11 |java.util.TreeSet_Constructors|
12 |java.util.TreeSet_Methods|
14 ================================================================================
16 *java.util.TreeSet_Constructors*
17 |java.util.TreeSet()|Constructs a new, empty set, sorted according to the eleme
18 |java.util.TreeSet(Collection)|Constructs a new set containing the elements in
19 |java.util.TreeSet(Comparator)|Constructs a new, empty set, sorted according to
20 |java.util.TreeSet(SortedSet)|Constructs a new set containing the same elements
22 *java.util.TreeSet_Methods*
23 |java.util.TreeSet.add(E)|Adds the specified element to this set if it is not a
24 |java.util.TreeSet.addAll(Collection)|Adds all of the elements in the specified
25 |java.util.TreeSet.clear()|Removes all of the elements from this set.
26 |java.util.TreeSet.clone()|Returns a shallow copy of this TreeSet instance.
27 |java.util.TreeSet.comparator()|Returns the comparator used to order this sorte
28 |java.util.TreeSet.contains(Object)|Returns true if this set contains the speci
29 |java.util.TreeSet.first()|Returns the first (lowest) element currently in this
30 |java.util.TreeSet.headSet(E)|Returns a view of the portion of this set whose e
31 |java.util.TreeSet.isEmpty()|Returns true if this set contains no elements.
32 |java.util.TreeSet.iterator()|Returns an iterator over the elements in this set
33 |java.util.TreeSet.last()|Returns the last (highest) element currently in this
34 |java.util.TreeSet.remove(Object)|Removes the specified element from this set i
35 |java.util.TreeSet.size()|Returns the number of elements in this set (its cardi
36 |java.util.TreeSet.subSet(E,E)|Returns a view of the portion of this set whose
37 |java.util.TreeSet.tailSet(E)|Returns a view of the portion of this set whose e
39 *java.util.TreeSet_Description*
41 This class implements the Set interface, backed by a TreeMap instance. This
42 class guarantees that the sorted set will be in ascending element order, sorted
43 according to the natural order of the elements (see Comparable), or by the
44 comparator provided at set creation time, depending on which constructor is
47 This implementation provides guaranteed log(n) time cost for the basic
48 operations (add, remove and contains).
50 Note that the ordering maintained by a set (whether or not an explicit
51 comparator is provided) must be consistent with equals if it is to correctly
52 implement the Set interface. (See Comparable or Comparator for a precise
53 definition of consistent with equals.) This is so because the Set interface is
54 defined in terms of the equals operation, but a TreeSet instance performs all
55 key comparisons using its compareTo (or compare) method, so two keys that are
56 deemed equal by this method are, from the standpoint of the set, equal. The
57 behavior of a set is well-defined even if its ordering is inconsistent with
58 equals; it just fails to obey the general contract of the Set interface.
60 Note that this implementation is not synchronized. If multiple threads access a
61 set concurrently, and at least one of the threads modifies the set, it must be
62 synchronized externally. This is typically accomplished by synchronizing on
63 some object that naturally encapsulates the set. If no such object exists, the
64 set should be "wrapped" using the Collections.synchronizedSet method. This is
65 best done at creation time, to prevent accidental unsynchronized access to the
68 SortedSet s = Collections.synchronizedSortedSet(new TreeSet(...));
70 The Iterators returned by this class's iterator method are fail-fast: if the
71 set is modified at any time after the iterator is created, in any way except
72 through the iterator's own remove method, the iterator will throw a
73 ConcurrentModificationException. Thus, in the face of concurrent modification,
74 the iterator fails quickly and cleanly, rather than risking arbitrary,
75 non-deterministic behavior at an undetermined time in the future.
77 Note that the fail-fast behavior of an iterator cannot be guaranteed as it is,
78 generally speaking, impossible to make any hard guarantees in the presence of
79 unsynchronized concurrent modification. Fail-fast iterators throw
80 ConcurrentModificationException on a best-effort basis. Therefore, it would be
81 wrong to write a program that depended on this exception for its correctness:
82 the fail-fast behavior of iterators should be used only to detect bugs.
84 This class is a member of the <a href="/../guide/collections/index.html"> Java
85 Collections Framework.
92 Constructs a new, empty set, sorted according to the elements' natural order.
93 All elements inserted into the set must implement the Comparable interface.
94 Furthermore, all such elements must be mutually comparable: e1.compareTo(e2)
95 must not throw a ClassCastException for any elements e1 and e2 in the set. If
96 the user attempts to add an element to the set that violates this constraint
97 (for example, the user attempts to add a string element to a set whose elements
98 are integers), the add(Object) call will throw a ClassCastException.
101 *java.util.TreeSet(Collection)*
103 public TreeSet(java.util.Collection c)
105 Constructs a new set containing the elements in the specified collection,
106 sorted according to the elements' natural order. All keys inserted into the set
107 must implement the Comparable interface. Furthermore, all such keys must be
108 mutually comparable: k1.compareTo(k2) must not throw a ClassCastException for
109 any elements k1 and k2 in the set.
111 c - The elements that will comprise the new set.
113 *java.util.TreeSet(Comparator)*
115 public TreeSet(java.util.Comparator c)
117 Constructs a new, empty set, sorted according to the specified comparator. All
118 elements inserted into the set must be mutually comparable by the specified
119 comparator: comparator.compare(e1, e2) must not throw a ClassCastException for
120 any elements e1 and e2 in the set. If the user attempts to add an element to
121 the set that violates this constraint, the add(Object) call will throw a
124 c - the comparator that will be used to sort this set. A null value indicates that
125 the elements' natural ordering should be used.
127 *java.util.TreeSet(SortedSet)*
129 public TreeSet(java.util.SortedSet s)
131 Constructs a new set containing the same elements as the specified sorted set,
132 sorted according to the same ordering.
134 s - sorted set whose elements will comprise the new set.
136 *java.util.TreeSet.add(E)*
138 public boolean add(java.lang.Object o)
140 Adds the specified element to this set if it is not already present.
142 o - element to be added to this set.
144 Returns: true if the set did not already contain the specified element.
145 *java.util.TreeSet.addAll(Collection)*
147 public boolean addAll(java.util.Collection c)
149 Adds all of the elements in the specified collection to this set.
151 c - elements to be added
153 Returns: true if this set changed as a result of the call.
154 *java.util.TreeSet.clear()*
158 Removes all of the elements from this set.
161 *java.util.TreeSet.clone()*
163 public |java.lang.Object| clone()
165 Returns a shallow copy of this TreeSet instance. (The elements themselves are
169 Returns: a shallow copy of this set.
170 *java.util.TreeSet.comparator()*
172 public |java.util.Comparator| comparator()
174 Returns the comparator used to order this sorted set, or null if this tree set
175 uses its elements natural ordering.
178 Returns: the comparator used to order this sorted set, or null if this tree set uses its
179 elements natural ordering.
180 *java.util.TreeSet.contains(Object)*
182 public boolean contains(java.lang.Object o)
184 Returns true if this set contains the specified element.
186 o - the object to be checked for containment in this set.
188 Returns: true if this set contains the specified element.
189 *java.util.TreeSet.first()*
191 public |java.lang.Object| first()
193 Returns the first (lowest) element currently in this sorted set.
196 Returns: the first (lowest) element currently in this sorted set.
197 *java.util.TreeSet.headSet(E)*
199 public |java.util.SortedSet| headSet(java.lang.Object toElement)
201 Returns a view of the portion of this set whose elements are strictly less than
202 toElement. The returned sorted set is backed by this set, so changes in the
203 returned sorted set are reflected in this set, and vice-versa. The returned
204 sorted set supports all optional set operations.
206 The sorted set returned by this method will throw an IllegalArgumentException
207 if the user attempts to insert an element greater than or equal to toElement.
209 Note: this method always returns a view that does not contain its (high)
210 endpoint. If you need a view that does contain this endpoint, and the element
211 type allows for calculation of the successor of a specified value, merely
212 request a headSet bounded by successor(highEndpoint). For example, suppose that
213 s is a sorted set of strings. The following idiom obtains a view containing all
214 of the strings in s that are less than or equal to high: SortedSet head =
215 s.headSet(high+"\0");
217 toElement - high endpoint (exclusive) of the headSet.
219 Returns: a view of the portion of this set whose elements are strictly less than
221 *java.util.TreeSet.isEmpty()*
223 public boolean isEmpty()
225 Returns true if this set contains no elements.
228 Returns: true if this set contains no elements.
229 *java.util.TreeSet.iterator()*
231 public |java.util.Iterator| iterator()
233 Returns an iterator over the elements in this set. The elements are returned in
237 Returns: an iterator over the elements in this set.
238 *java.util.TreeSet.last()*
240 public |java.lang.Object| last()
242 Returns the last (highest) element currently in this sorted set.
245 Returns: the last (highest) element currently in this sorted set.
246 *java.util.TreeSet.remove(Object)*
248 public boolean remove(java.lang.Object o)
250 Removes the specified element from this set if it is present.
252 o - object to be removed from this set, if present.
254 Returns: true if the set contained the specified element.
255 *java.util.TreeSet.size()*
259 Returns the number of elements in this set (its cardinality).
262 Returns: the number of elements in this set (its cardinality).
263 *java.util.TreeSet.subSet(E,E)*
265 public |java.util.SortedSet| subSet(
266 java.lang.Object fromElement,
267 java.lang.Object toElement)
269 Returns a view of the portion of this set whose elements range from
270 fromElement, inclusive, to toElement, exclusive. (If fromElement and toElement
271 are equal, the returned sorted set is empty.) The returned sorted set is backed
272 by this set, so changes in the returned sorted set are reflected in this set,
273 and vice-versa. The returned sorted set supports all optional Set operations.
275 The sorted set returned by this method will throw an IllegalArgumentException
276 if the user attempts to insert an element outside the specified range.
278 Note: this method always returns a half-open range (which includes its low
279 endpoint but not its high endpoint). If you need a closed range (which includes
280 both endpoints), and the element type allows for calculation of the successor
281 of a specified value, merely request the subrange from lowEndpoint to
282 successor(highEndpoint). For example, suppose that s is a sorted set of
283 strings. The following idiom obtains a view containing all of the strings in s
284 from low to high, inclusive:
286 SortedSet sub = s.subSet(low, high+"\0");
288 A similar technique can be used to generate an open range (which contains
289 neither endpoint). The following idiom obtains a view containing all of the
290 strings in s from low to high, exclusive:
292 SortedSet sub = s.subSet(low+"\0", high);
294 fromElement - low endpoint (inclusive) of the subSet.
295 toElement - high endpoint (exclusive) of the subSet.
297 Returns: a view of the portion of this set whose elements range from fromElement,
298 inclusive, to toElement, exclusive.
299 *java.util.TreeSet.tailSet(E)*
301 public |java.util.SortedSet| tailSet(java.lang.Object fromElement)
303 Returns a view of the portion of this set whose elements are greater than or
304 equal to fromElement. The returned sorted set is backed by this set, so changes
305 in the returned sorted set are reflected in this set, and vice-versa. The
306 returned sorted set supports all optional set operations.
308 The sorted set returned by this method will throw an IllegalArgumentException
309 if the user attempts to insert an element less than fromElement.
311 Note: this method always returns a view that contains its (low) endpoint. If
312 you need a view that does not contain this endpoint, and the element type
313 allows for calculation of the successor of a specified value, merely request a
314 tailSet bounded by successor(lowEndpoint). For example, suppose that s is a
315 sorted set of strings. The following idiom obtains a view containing all of the
316 strings in s that are strictly greater than low:
318 SortedSet tail = s.tailSet(low+"\0");
320 fromElement - low endpoint (inclusive) of the tailSet.
322 Returns: a view of the portion of this set whose elements are greater than or equal to