ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/TreeSet.java
Revision: 1.3
Committed: Tue Mar 22 01:30:10 2005 UTC (19 years, 2 months ago) by dl
Branch: MAIN
Changes since 1.2: +123 -56 lines
Log Message:
NavigableMap.subMap -> NavigableMap.navigableSubMap, and associated changes

File Contents

# User Rev Content
1 dl 1.1 /*
2     * %W% %E%
3     *
4     * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5     * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6     */
7    
8     package java.util;
9    
10     /**
11     * This class implements the <tt>Set</tt> interface, backed by a
12     * <tt>TreeMap</tt> instance. This class guarantees that the sorted set will
13     * be in ascending element order, sorted according to the <i>natural order</i>
14     * of the elements (see <tt>Comparable</tt>), or by the comparator provided at
15     * set creation time, depending on which constructor is used.<p>
16     *
17     * This implementation provides guaranteed log(n) time cost for the basic
18     * operations (<tt>add</tt>, <tt>remove</tt> and <tt>contains</tt>).<p>
19     *
20     * Note that the ordering maintained by a set (whether or not an explicit
21     * comparator is provided) must be <i>consistent with equals</i> if it is to
22     * correctly implement the <tt>Set</tt> interface. (See <tt>Comparable</tt>
23     * or <tt>Comparator</tt> for a precise definition of <i>consistent with
24     * equals</i>.) This is so because the <tt>Set</tt> interface is defined in
25     * terms of the <tt>equals</tt> operation, but a <tt>TreeSet</tt> instance
26     * performs all key comparisons using its <tt>compareTo</tt> (or
27     * <tt>compare</tt>) method, so two keys that are deemed equal by this method
28     * are, from the standpoint of the set, equal. The behavior of a set
29     * <i>is</i> well-defined even if its ordering is inconsistent with equals; it
30     * just fails to obey the general contract of the <tt>Set</tt> interface.<p>
31     *
32     * <b>Note that this implementation is not synchronized.</b> If multiple
33     * threads access a set concurrently, and at least one of the threads modifies
34     * the set, it <i>must</i> be synchronized externally. This is typically
35     * accomplished by synchronizing on some object that naturally encapsulates
36     * the set. If no such object exists, the set should be "wrapped" using the
37     * <tt>Collections.synchronizedSet</tt> method. This is best done at creation
38     * time, to prevent accidental unsynchronized access to the set: <pre>
39     * SortedSet s = Collections.synchronizedSortedSet(new TreeSet(...));
40     * </pre><p>
41     *
42     * The Iterators returned by this class's <tt>iterator</tt> method are
43     * <i>fail-fast</i>: if the set is modified at any time after the iterator is
44     * created, in any way except through the iterator's own <tt>remove</tt>
45     * method, the iterator will throw a <tt>ConcurrentModificationException</tt>.
46     * Thus, in the face of concurrent modification, the iterator fails quickly
47     * and cleanly, rather than risking arbitrary, non-deterministic behavior at
48     * an undetermined time in the future.
49     *
50     * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
51     * as it is, generally speaking, impossible to make any hard guarantees in the
52     * presence of unsynchronized concurrent modification. Fail-fast iterators
53     * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
54     * Therefore, it would be wrong to write a program that depended on this
55     * exception for its correctness: <i>the fail-fast behavior of iterators
56     * should be used only to detect bugs.</i><p>
57     *
58     * This class is a member of the
59     * <a href="{@docRoot}/../guide/collections/index.html">
60     * Java Collections Framework</a>.
61     *
62     * @author Josh Bloch
63     * @version %I%, %G%
64     * @see Collection
65     * @see Set
66     * @see HashSet
67     * @see Comparable
68     * @see Comparator
69     * @see Collections#synchronizedSortedSet(SortedSet)
70     * @see TreeMap
71     * @since 1.2
72     */
73    
74     public class TreeSet<E>
75     extends AbstractSet<E>
76     implements NavigableSet<E>, Cloneable, java.io.Serializable
77     {
78     private transient NavigableMap<E,Object> m; // The backing Map
79    
80     // Dummy value to associate with an Object in the backing Map
81     private static final Object PRESENT = new Object();
82    
83     /**
84     * Constructs a set backed by the specified sorted map.
85     */
86     private TreeSet(NavigableMap<E,Object> m) {
87     this.m = m;
88     }
89    
90     /**
91     * Constructs a new, empty set, sorted according to the elements' natural
92     * order. All elements inserted into the set must implement the
93     * <tt>Comparable</tt> interface. Furthermore, all such elements must be
94     * <i>mutually comparable</i>: <tt>e1.compareTo(e2)</tt> must not throw a
95     * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
96     * <tt>e2</tt> in the set. If the user attempts to add an element to the
97     * set that violates this constraint (for example, the user attempts to
98     * add a string element to a set whose elements are integers), the
99     * <tt>add(Object)</tt> call will throw a <tt>ClassCastException</tt>.
100     *
101     * @see Comparable
102     */
103     public TreeSet() {
104     this(new TreeMap<E,Object>());
105     }
106    
107     /**
108     * Constructs a new, empty set, sorted according to the specified
109     * comparator. All elements inserted into the set must be <i>mutually
110     * comparable</i> by the specified comparator: <tt>comparator.compare(e1,
111     * e2)</tt> must not throw a <tt>ClassCastException</tt> for any elements
112     * <tt>e1</tt> and <tt>e2</tt> in the set. If the user attempts to add
113     * an element to the set that violates this constraint, the
114     * <tt>add(Object)</tt> call will throw a <tt>ClassCastException</tt>.
115     *
116     * @param c the comparator that will be used to sort this set. A
117     * <tt>null</tt> value indicates that the elements' <i>natural
118     * ordering</i> should be used.
119     */
120     public TreeSet(Comparator<? super E> c) {
121     this(new TreeMap<E,Object>(c));
122     }
123    
124     /**
125     * Constructs a new set containing the elements in the specified
126     * collection, sorted according to the elements' <i>natural order</i>.
127     * All keys inserted into the set must implement the <tt>Comparable</tt>
128     * interface. Furthermore, all such keys must be <i>mutually
129     * comparable</i>: <tt>k1.compareTo(k2)</tt> must not throw a
130     * <tt>ClassCastException</tt> for any elements <tt>k1</tt> and
131     * <tt>k2</tt> in the set.
132     *
133     * @param c The elements that will comprise the new set.
134     *
135     * @throws ClassCastException if the keys in the specified collection are
136     * not comparable, or are not mutually comparable.
137     * @throws NullPointerException if the specified collection is null.
138     */
139     public TreeSet(Collection<? extends E> c) {
140     this();
141     addAll(c);
142     }
143    
144     /**
145     * Constructs a new set containing the same elements as the specified
146     * sorted set, sorted according to the same ordering.
147     *
148     * @param s sorted set whose elements will comprise the new set.
149     * @throws NullPointerException if the specified sorted set is null.
150     */
151     public TreeSet(SortedSet<E> s) {
152     this(s.comparator());
153     addAll(s);
154     }
155    
156     /**
157     * Returns an iterator over the elements in this set. The elements
158     * are returned in ascending order.
159     *
160     * @return an iterator over the elements in this set.
161     */
162     public Iterator<E> iterator() {
163     return m.keySet().iterator();
164     }
165    
166     /**
167     * Returns an iterator over the elements in this set. The elements
168     * are returned in descending order.
169     *
170     * @return an iterator over the elements in this set.
171     */
172     public Iterator<E> descendingIterator() {
173     return m.descendingKeySet().iterator();
174     }
175    
176     /**
177     * Returns the number of elements in this set (its cardinality).
178     *
179     * @return the number of elements in this set (its cardinality).
180     */
181     public int size() {
182     return m.size();
183     }
184    
185     /**
186     * Returns <tt>true</tt> if this set contains no elements.
187     *
188     * @return <tt>true</tt> if this set contains no elements.
189     */
190     public boolean isEmpty() {
191     return m.isEmpty();
192     }
193    
194     /**
195     * Returns <tt>true</tt> if this set contains the specified element.
196     *
197     * @param o the object to be checked for containment in this set.
198     * @return <tt>true</tt> if this set contains the specified element.
199     *
200     * @throws ClassCastException if the specified object cannot be compared
201     * with the elements currently in the set.
202 dl 1.2 * @throws NullPointerException if o is <tt>null</tt> and this map
203 dl 1.1 * uses natural ordering and is non-empty, or its comparator does
204     * not tolerate <tt>null</tt> keys.
205     */
206     public boolean contains(Object o) {
207     return m.containsKey(o);
208     }
209    
210     /**
211     * Adds the specified element to this set if it is not already present.
212     *
213     * @param o element to be added to this set.
214     * @return <tt>true</tt> if the set did not already contain the specified
215     * element.
216     *
217     * @throws ClassCastException if the specified object cannot be compared
218     * with the elements currently in the set.
219 dl 1.2 * @throws NullPointerException if o is <tt>null</tt> and this map
220 dl 1.1 * uses natural ordering and is non-empty, or its comparator does
221     * not tolerate <tt>null</tt> keys.
222     */
223     public boolean add(E o) {
224     return m.put(o, PRESENT)==null;
225     }
226    
227     /**
228     * Removes the specified element from this set if it is present.
229     *
230     * @param o object to be removed from this set, if present.
231     * @return <tt>true</tt> if the set contained the specified element.
232     *
233     * @throws ClassCastException if the specified object cannot be compared
234     * with the elements currently in the set.
235 dl 1.2 * @throws NullPointerException if o is <tt>null</tt> and this map
236 dl 1.1 * uses natural ordering and is non-empty, or its comparator does
237     * not tolerate <tt>null</tt> keys.
238     */
239     public boolean remove(Object o) {
240     return m.remove(o)==PRESENT;
241     }
242    
243     /**
244     * Removes all of the elements from this set.
245     */
246     public void clear() {
247     m.clear();
248     }
249    
250     /**
251     * Adds all of the elements in the specified collection to this set.
252     *
253     * @param c elements to be added
254     * @return <tt>true</tt> if this set changed as a result of the call.
255     *
256     * @throws ClassCastException if the elements provided cannot be compared
257     * with the elements currently in the set.
258     * @throws NullPointerException of the specified collection is
259     * <tt>null</tt> or if any element is <tt>null</tt> and this map
260     * uses natural ordering, or its comparator does not tolerate
261     * <tt>null</tt> keys.
262     */
263     public boolean addAll(Collection<? extends E> c) {
264     // Use linear-time version if applicable
265     if (m.size()==0 && c.size() > 0 &&
266     c instanceof SortedSet &&
267     m instanceof TreeMap) {
268     SortedSet<Map.Entry<E, Object>> set = (SortedSet<Map.Entry<E, Object>>) (SortedSet) c;
269     TreeMap<E,Object> map = (TreeMap<E, Object>) m;
270     Comparator<? super E> cc = (Comparator<E>) set.comparator();
271     Comparator<? super E> mc = map.comparator();
272     if (cc==mc || (cc != null && cc.equals(mc))) {
273     map.addAllForTreeSet(set, PRESENT);
274     return true;
275     }
276     }
277     return super.addAll(c);
278     }
279    
280     /**
281 dl 1.3 * Returns a view of the portion of this set whose elements range
282     * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
283     * exclusive. (If <tt>fromElement</tt> and <tt>toElement</tt> are
284     * equal, the returned navigable set is empty.) The returned
285     * navigable set is backed by this set, so changes in the returned
286     * navigable set are reflected in this set, and vice-versa. The
287     * returned navigable set supports all optional Set operations.<p>
288 dl 1.1 *
289 dl 1.3 * The navigable set returned by this method will throw an
290 dl 1.1 * <tt>IllegalArgumentException</tt> if the user attempts to insert an
291     * element outside the specified range.<p>
292     *
293 dl 1.3 * Note: this method always returns a <i>half-open range</i>
294     * (which includes its low endpoint but not its high endpoint).
295     * If you need a <i>closed range</i> (which includes both
296     * endpoints), and the element type allows for calculation of the
297     * successor of a specified value, merely request the subrange
298     * from <tt>lowEndpoint</tt> to <tt>successor(highEndpoint)</tt>.
299     * For example, suppose that <tt>s</tt> is a navigable set of
300     * strings. The following idiom obtains a view containing all of
301     * the strings in <tt>s</tt> from <tt>low</tt> to <tt>high</tt>,
302     * inclusive: <pre> NavigableSet sub = s.subSet(low, high+"\0");
303 dl 1.1 * </pre>
304     *
305     * A similar technique can be used to generate an <i>open range</i> (which
306     * contains neither endpoint). The following idiom obtains a view
307     * containing all of the strings in <tt>s</tt> from <tt>low</tt> to
308     * <tt>high</tt>, exclusive: <pre>
309 dl 1.3 * NavigableSet sub = s.navigableSubSet(low+"\0", high);
310 dl 1.1 * </pre>
311     *
312     * @param fromElement low endpoint (inclusive) of the subSet.
313     * @param toElement high endpoint (exclusive) of the subSet.
314     * @return a view of the portion of this set whose elements range from
315     * <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
316     * exclusive.
317     * @throws ClassCastException if <tt>fromElement</tt> and
318     * <tt>toElement</tt> cannot be compared to one another using
319     * this set's comparator (or, if the set has no comparator,
320     * using natural ordering).
321     * @throws IllegalArgumentException if <tt>fromElement</tt> is greater than
322     * <tt>toElement</tt>.
323     * @throws NullPointerException if <tt>fromElement</tt> or
324     * <tt>toElement</tt> is <tt>null</tt> and this set uses natural
325     * order, or its comparator does not tolerate <tt>null</tt>
326     * elements.
327     */
328 dl 1.3 public NavigableSet<E> navigableSubSet(E fromElement, E toElement) {
329     return new TreeSet<E>(m.navigableSubMap(fromElement, toElement));
330 dl 1.1 }
331    
332     /**
333 dl 1.3 * Returns a view of the portion of this set whose elements are
334     * strictly less than <tt>toElement</tt>. The returned navigable
335     * set is backed by this set, so changes in the returned navigable
336     * set are reflected in this set, and vice-versa. The returned
337     * navigable set supports all optional set operations.<p>
338     *
339     * The navigable set returned by this method will throw an
340     * <tt>IllegalArgumentException</tt> if the user attempts to
341     * insert an element greater than or equal to
342     * <tt>toElement</tt>.<p>
343     *
344     * Note: this method always returns a view that does not contain
345     * its (high) endpoint. If you need a view that does contain this
346     * endpoint, and the element type allows for calculation of the
347     * successor of a specified value, merely request a headSet
348     * bounded by <tt>successor(highEndpoint)</tt>. For example,
349     * suppose that <tt>s</tt> is a navigable set of strings. The
350     * following idiom obtains a view containing all of the strings in
351     * <tt>s</tt> that are less than or equal to <tt>high</tt>:
352     * <pre> NavigableSet head = s.navigableHeadSet(high+"\0");</pre>
353 dl 1.1 *
354     * @param toElement high endpoint (exclusive) of the headSet.
355     * @return a view of the portion of this set whose elements are strictly
356     * less than toElement.
357     * @throws ClassCastException if <tt>toElement</tt> is not compatible
358     * with this set's comparator (or, if the set has no comparator,
359     * if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
360     * @throws IllegalArgumentException if this set is itself a subSet,
361     * headSet, or tailSet, and <tt>toElement</tt> is not within the
362     * specified range of the subSet, headSet, or tailSet.
363     * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt> and
364     * this set uses natural ordering, or its comparator does
365     * not tolerate <tt>null</tt> elements.
366     */
367 dl 1.3 public NavigableSet<E> navigableHeadSet(E toElement) {
368     return new TreeSet<E>(m.navigableHeadMap(toElement));
369 dl 1.1 }
370    
371     /**
372     * Returns a view of the portion of this set whose elements are
373 dl 1.3 * greater than or equal to <tt>fromElement</tt>. The returned
374     * navigable set is backed by this set, so changes in the returned
375     * navigable set are reflected in this set, and vice-versa. The
376     * returned navigable set supports all optional set operations.<p>
377 dl 1.1 *
378 dl 1.3 * The navigable set returned by this method will throw an
379 dl 1.1 * <tt>IllegalArgumentException</tt> if the user attempts to insert an
380     * element less than <tt>fromElement</tt>.
381     *
382     * Note: this method always returns a view that contains its (low)
383 dl 1.3 * endpoint. If you need a view that does not contain this
384     * endpoint, and the element type allows for calculation of the
385     * successor of a specified value, merely request a tailSet
386     * bounded by <tt>successor(lowEndpoint)</tt>. For example,
387     * suppose that <tt>s</tt> is a navigable set of strings. The
388     * following idiom obtains a view containing all of the strings in
389     * <tt>s</tt> that are strictly greater than <tt>low</tt>:
390     * <pre> NavigableSet tail = s.navigableTailSet(low+"\0");
391 dl 1.1 * </pre>
392     *
393     * @param fromElement low endpoint (inclusive) of the tailSet.
394     * @return a view of the portion of this set whose elements are
395     * greater than or equal to <tt>fromElement</tt>.
396     * @throws ClassCastException if <tt>fromElement</tt> is not compatible
397     * with this set's comparator (or, if the set has no comparator,
398     * if <tt>fromElement</tt> does not implement <tt>Comparable</tt>).
399     * @throws IllegalArgumentException if this set is itself a subSet,
400     * headSet, or tailSet, and <tt>fromElement</tt> is not within the
401     * specified range of the subSet, headSet, or tailSet.
402     * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
403     * and this set uses natural ordering, or its comparator does
404     * not tolerate <tt>null</tt> elements.
405     */
406 dl 1.3 public NavigableSet<E> navigableTailSet(E fromElement) {
407     return new TreeSet<E>(m.navigableTailMap(fromElement));
408     }
409    
410    
411     /**
412     * Equivalent to <tt>navigableSubSet</tt> but with a return
413     * type conforming to the <tt>SortedSet</tt> interface.
414     * @param fromElement low endpoint (inclusive) of the subSet.
415     * @param toElement high endpoint (exclusive) of the subSet.
416     * @return a view of the portion of this set whose elements range from
417     * <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
418     * exclusive.
419     * @throws ClassCastException if <tt>fromElement</tt> and
420     * <tt>toElement</tt> cannot be compared to one another using
421     * this set's comparator (or, if the set has no comparator,
422     * using natural ordering).
423     * @throws IllegalArgumentException if <tt>fromElement</tt> is greater than
424     * <tt>toElement</tt>.
425     * @throws NullPointerException if <tt>fromElement</tt> or
426     * <tt>toElement</tt> is <tt>null</tt> and this set uses natural
427     * order, or its comparator does not tolerate <tt>null</tt>
428     * elements.
429     */
430     public SortedSet<E> subSet(E fromElement, E toElement) {
431     return new TreeSet<E>(m.navigableSubMap(fromElement, toElement));
432     }
433    
434     /**
435     * Equivalent to <tt>navigableHeadSet</tt> but with a return
436     * type conforming to the <tt>SortedSet</tt> interface.
437     *
438     * @param toElement high endpoint (exclusive) of the headSet.
439     * @return a view of the portion of this set whose elements are strictly
440     * less than toElement.
441     * @throws ClassCastException if <tt>toElement</tt> is not compatible
442     * with this set's comparator (or, if the set has no comparator,
443     * if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
444     * @throws IllegalArgumentException if this set is itself a subSet,
445     * headSet, or tailSet, and <tt>toElement</tt> is not within the
446     * specified range of the subSet, headSet, or tailSet.
447     * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt> and
448     * this set uses natural ordering, or its comparator does
449     * not tolerate <tt>null</tt> elements.
450     */
451     public SortedSet<E> headSet(E toElement) {
452     return new TreeSet<E>(m.navigableHeadMap(toElement));
453     }
454    
455     /**
456     * Equivalent to <tt>navigableTailSet</tt> but with a return
457     * type conforming to the <tt>SortedSet</tt> interface.
458     * @param fromElement low endpoint (inclusive) of the tailSet.
459     * @return a view of the portion of this set whose elements are
460     * greater than or equal to <tt>fromElement</tt>.
461     * @throws ClassCastException if <tt>fromElement</tt> is not compatible
462     * with this set's comparator (or, if the set has no comparator,
463     * if <tt>fromElement</tt> does not implement <tt>Comparable</tt>).
464     * @throws IllegalArgumentException if this set is itself a subSet,
465     * headSet, or tailSet, and <tt>fromElement</tt> is not within the
466     * specified range of the subSet, headSet, or tailSet.
467     * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
468     * and this set uses natural ordering, or its comparator does
469     * not tolerate <tt>null</tt> elements.
470     */
471     public SortedSet<E> tailSet(E fromElement) {
472     return new TreeSet<E>(m.navigableTailMap(fromElement));
473 dl 1.1 }
474    
475     /**
476     * Returns the comparator used to order this sorted set, or <tt>null</tt>
477     * if this tree set uses its elements natural ordering.
478     *
479     * @return the comparator used to order this sorted set, or <tt>null</tt>
480     * if this tree set uses its elements natural ordering.
481     */
482     public Comparator<? super E> comparator() {
483     return m.comparator();
484     }
485    
486     /**
487     * Returns the first (lowest) element currently in this sorted set.
488     *
489     * @return the first (lowest) element currently in this sorted set.
490     * @throws NoSuchElementException sorted set is empty.
491     */
492     public E first() {
493     return m.firstKey();
494     }
495    
496     /**
497     * Returns the last (highest) element currently in this sorted set.
498     *
499     * @return the last (highest) element currently in this sorted set.
500     * @throws NoSuchElementException sorted set is empty.
501     */
502     public E last() {
503     return m.lastKey();
504     }
505    
506     // NavigableSet API methods
507    
508    
509     /**
510     * Returns an element greater than or equal to the given element, or
511     * <tt>null</tt> if there is no such element.
512     *
513     * @param o the value to match
514     * @return an element greater than or equal to given element, or
515     * <tt>null</tt> if there is no such element.
516     * @throws ClassCastException if o cannot be compared with the elements
517     * currently in the set.
518 dl 1.2 * @throws NullPointerException if o is <tt>null</tt> and this map
519 dl 1.1 * uses natural ordering and is non-empty, or its comparator does
520     * not tolerate <tt>null</tt> keys.
521     */
522     public E ceiling(E o) {
523     return m.ceilingKey(o);
524     }
525    
526     /**
527     * Returns an element strictly less than the given element, or
528     * <tt>null</tt> if there is no such element.
529     *
530     * @param o the value to match
531     * @return the greatest element less than the given element, or
532     * <tt>null</tt> if there is no such element.
533     * @throws ClassCastException if o cannot be compared with the elements
534     * currently in the set.
535 dl 1.2 * @throws NullPointerException if o is <tt>null</tt> and this map
536 dl 1.1 * uses natural ordering and is non-empty, or its comparator does
537     * not tolerate <tt>null</tt> keys.
538     */
539     public E lower(E o) {
540     return m.lowerKey(o);
541     }
542    
543     /**
544     * Returns an element less than or equal to the given element, or
545     * <tt>null</tt> if there is no such element.
546     *
547     * @param o the value to match
548     * @return the greatest element less than or equal to given
549     * element, or <tt>null</tt> if there is no such element.
550     * @throws ClassCastException if o cannot be compared with the elements
551     * currently in the set.
552 dl 1.2 * @throws NullPointerException if o is <tt>null</tt> and this map
553 dl 1.1 * uses natural ordering and is non-empty, or its comparator does
554     * not tolerate <tt>null</tt> keys.
555     */
556     public E floor(E o) {
557     return m.floorKey(o);
558     }
559    
560     /**
561     * Returns an element strictly greater than the given element, or
562     * <tt>null</tt> if there is no such element.
563     *
564     * @param o the value to match
565     * @return the least element greater than the given element, or
566     * <tt>null</tt> if there is no such element.
567     * @throws ClassCastException if o cannot be compared with the elements
568     * currently in the set.
569 dl 1.2 * @throws NullPointerException if o is <tt>null</tt> and this map
570 dl 1.1 * uses natural ordering and is non-empty, or its comparator does
571     * not tolerate <tt>null</tt> keys.
572     */
573     public E higher(E o) {
574     return m.higherKey(o);
575     }
576    
577     /**
578     * Retrieves and removes the first (lowest) element.
579     *
580     * @return the least element, or <tt>null</tt> if empty.
581     */
582     public E pollFirst() {
583     Map.Entry<E,?> e = m.pollFirstEntry();
584     return (e == null)? null : e.getKey();
585     }
586    
587     /**
588     * Retrieves and removes the last (highest) element.
589     *
590     * @return the last element, or <tt>null</tt> if empty.
591     */
592     public E pollLast() {
593     Map.Entry<E,?> e = m.pollLastEntry();
594     return (e == null)? null : e.getKey();
595     }
596    
597     /**
598     * Returns a shallow copy of this <tt>TreeSet</tt> instance. (The elements
599     * themselves are not cloned.)
600     *
601     * @return a shallow copy of this set.
602     */
603     public Object clone() {
604     TreeSet<E> clone = null;
605     try {
606     clone = (TreeSet<E>) super.clone();
607     } catch (CloneNotSupportedException e) {
608     throw new InternalError();
609     }
610    
611     clone.m = new TreeMap<E,Object>(m);
612    
613     return clone;
614     }
615    
616     /**
617     * Save the state of the <tt>TreeSet</tt> instance to a stream (that is,
618     * serialize it).
619     *
620     * @serialData Emits the comparator used to order this set, or
621     * <tt>null</tt> if it obeys its elements' natural ordering
622     * (Object), followed by the size of the set (the number of
623     * elements it contains) (int), followed by all of its
624     * elements (each an Object) in order (as determined by the
625     * set's Comparator, or by the elements' natural ordering if
626     * the set has no Comparator).
627     */
628     private void writeObject(java.io.ObjectOutputStream s)
629     throws java.io.IOException {
630     // Write out any hidden stuff
631     s.defaultWriteObject();
632    
633     // Write out Comparator
634     s.writeObject(m.comparator());
635    
636     // Write out size
637     s.writeInt(m.size());
638    
639     // Write out all elements in the proper order.
640     for (Iterator i=m.keySet().iterator(); i.hasNext(); )
641     s.writeObject(i.next());
642     }
643    
644     /**
645     * Reconstitute the <tt>TreeSet</tt> instance from a stream (that is,
646     * deserialize it).
647     */
648     private void readObject(java.io.ObjectInputStream s)
649     throws java.io.IOException, ClassNotFoundException {
650     // Read in any hidden stuff
651     s.defaultReadObject();
652    
653     // Read in Comparator
654     Comparator<E> c = (Comparator<E>) s.readObject();
655    
656     // Create backing TreeMap
657     TreeMap<E,Object> tm;
658     if (c==null)
659     tm = new TreeMap<E,Object>();
660     else
661     tm = new TreeMap<E,Object>(c);
662     m = tm;
663    
664     // Read in size
665     int size = s.readInt();
666    
667     tm.readTreeSet(size, s, PRESENT);
668     }
669    
670     private static final long serialVersionUID = -2479143000061671589L;
671     }