ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/TreeSet.java
(Generate patch)

Comparing jsr166/src/main/java/util/TreeSet.java (file contents):
Revision 1.13 by jsr166, Tue May 17 07:29:01 2005 UTC vs.
Revision 1.18 by jsr166, Mon Jul 18 01:14:34 2005 UTC

# Line 6 | Line 6
6   */
7  
8   package java.util;
9 + import java.util.*; // for javadoc (till 6280605 is fixed)
10  
11   /**
12   * A {@link NavigableSet} implementation based on a {@link TreeMap}.
# Line 28 | Line 29 | package java.util;
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.
31   *
32 < * <p><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>
32 > * <p><strong>Note that this implementation is not synchronized.</strong>
33 > * If multiple threads access a tree set concurrently, and at least one
34 > * of the threads modifies the set, it <i>must</i> be synchronized
35 > * externally.  This is typically accomplished by synchronizing on some
36 > * object that naturally encapsulates the set.
37 > * If no such object exists, the set should be "wrapped" using the
38 > * {@link Collections#synchronizedSortedSet Collections.synchronizedSortedSet}
39 > * method.  This is best done at creation time, to prevent accidental
40 > * unsynchronized access to the set: <pre>
41 > *   SortedSet s = Collections.synchronizedSortedSet(new TreeSet(...));</pre>
42   *
43   * <p>The iterators returned by this class's <tt>iterator</tt> method are
44   * <i>fail-fast</i>: if the set is modified at any time after the iterator is
# Line 67 | Line 69 | package java.util;
69   * @see     HashSet
70   * @see     Comparable
71   * @see     Comparator
70 – * @see     Collections#synchronizedSortedSet(SortedSet)
72   * @see     TreeMap
73   * @since   1.2
74   */
# Line 166 | Line 167 | public class TreeSet<E>
167       * Returns an iterator over the elements in this set in descending order.
168       *
169       * @return an iterator over the elements in this set in descending order
170 +     * @since 1.6
171       */
172      public Iterator<E> descendingIterator() {
173          return m.descendingKeySet().iterator();
# Line 191 | Line 193 | public class TreeSet<E>
193  
194      /**
195       * Returns <tt>true</tt> if this set contains the specified element.
196 +     * More formally, returns <tt>true</tt> if and only if this set
197 +     * contains an element <tt>e</tt> such that
198 +     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
199       *
200 <     * @param o the object to be checked for containment in this set
200 >     * @param o object to be checked for containment in this set
201       * @return <tt>true</tt> if this set contains the specified element
202       * @throws ClassCastException if the specified object cannot be compared
203       *         with the elements currently in the set
204 <     * @throws NullPointerException if the specified element is null and
205 <     *         this set uses natural ordering and is non-empty, or its
206 <     *         comparator does not permit null elements
204 >     * @throws NullPointerException if the specified element is null
205 >     *         and this set uses natural ordering, or its comparator
206 >     *         does not permit null elements
207       */
208      public boolean contains(Object o) {
209          return m.containsKey(o);
# Line 206 | Line 211 | public class TreeSet<E>
211  
212      /**
213       * Adds the specified element to this set if it is not already present.
214 +     * More formally, adds the specified element <tt>e</tt> to this set if
215 +     * the set contains no element <tt>e2</tt> such that
216 +     * <tt>(e==null&nbsp;?&nbsp;e2==null&nbsp;:&nbsp;e.equals(e2))</tt>.
217 +     * If this set already contains the element, the call leaves the set
218 +     * unchanged and returns <tt>false</tt>.
219       *
220       * @param e element to be added to this set
221 <     * @return <tt>true</tt> if the set did not already contain the specified
221 >     * @return <tt>true</tt> if this set did not already contain the specified
222       *         element
223       * @throws ClassCastException if the specified object cannot be compared
224 <     *         with the elements currently in the set
225 <     * @throws NullPointerException if the specified element is null and
226 <     *         this set uses natural ordering and is non-empty, or its
227 <     *         comparator does not permit null elements
224 >     *         with the elements currently in this set
225 >     * @throws NullPointerException if the specified element is null
226 >     *         and this set uses natural ordering, or its comparator
227 >     *         does not permit null elements
228       */
229      public boolean add(E e) {
230          return m.put(e, PRESENT)==null;
# Line 222 | Line 232 | public class TreeSet<E>
232  
233      /**
234       * Removes the specified element from this set if it is present.
235 +     * More formally, removes an element <tt>e</tt> such that
236 +     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>,
237 +     * if this set contains such an element.  Returns <tt>true</tt> if
238 +     * this set contained the element (or equivalently, if this set
239 +     * changed as a result of the call).  (This set will not contain the
240 +     * element once the call returns.)
241       *
242       * @param o object to be removed from this set, if present
243 <     * @return <tt>true</tt> if the set contained the specified element
243 >     * @return <tt>true</tt> if this set contained the specified element
244       * @throws ClassCastException if the specified object cannot be compared
245 <     *         with the elements currently in the set
246 <     * @throws NullPointerException if the specified element is null and
247 <     *         this set uses natural ordering and is non-empty, or its
248 <     *         comparator does not permit null elements
245 >     *         with the elements currently in this set
246 >     * @throws NullPointerException if the specified element is null
247 >     *         and this set uses natural ordering, or its comparator
248 >     *         does not permit null elements
249       */
250      public boolean remove(Object o) {
251          return m.remove(o)==PRESENT;
# Line 246 | Line 262 | public class TreeSet<E>
262      /**
263       * Adds all of the elements in the specified collection to this set.
264       *
265 <     * @param c elements to be added
265 >     * @param c collection containing elements to be added to this set
266       * @return <tt>true</tt> if this set changed as a result of the call
267       * @throws ClassCastException if the elements provided cannot be compared
268       *         with the elements currently in the set
# Line 277 | Line 293 | public class TreeSet<E>
293       *         <tt>toElement</tt> is null and this set uses natural ordering,
294       *         or its comparator does not permit null elements
295       * @throws IllegalArgumentException {@inheritDoc}
296 +     * @since 1.6
297       */
298      public NavigableSet<E> navigableSubSet(E fromElement, E toElement) {
299          return new TreeSet<E>(m.navigableSubMap(fromElement, toElement));
# Line 288 | Line 305 | public class TreeSet<E>
305       *         this set uses natural ordering, or its comparator does
306       *         not permit null elements
307       * @throws IllegalArgumentException {@inheritDoc}
308 +     * @since 1.6
309       */
310      public NavigableSet<E> navigableHeadSet(E toElement) {
311          return new TreeSet<E>(m.navigableHeadMap(toElement));
# Line 299 | Line 317 | public class TreeSet<E>
317       *         this set uses natural ordering, or its comparator does
318       *         not permit null elements
319       * @throws IllegalArgumentException {@inheritDoc}
320 +     * @since 1.6
321       */
322      public NavigableSet<E> navigableTailSet(E fromElement) {
323          return new TreeSet<E>(m.navigableTailMap(fromElement));
# Line 374 | Line 393 | public class TreeSet<E>
393  
394      /**
395       * @throws ClassCastException {@inheritDoc}
396 <     * @throws NullPointerException if the specified element is null and
397 <     *         this set uses natural ordering and is non-empty,
398 <     *         or its comparator does not permit null elements
396 >     * @throws NullPointerException if the specified element is null
397 >     *         and this set uses natural ordering, or its comparator
398 >     *         does not permit null elements
399 >     * @since 1.6
400       */
401      public E lower(E e) {
402          return m.lowerKey(e);
# Line 384 | Line 404 | public class TreeSet<E>
404  
405      /**
406       * @throws ClassCastException {@inheritDoc}
407 <     * @throws NullPointerException if the specified element is null and
408 <     *         this set uses natural ordering and is non-empty,
409 <     *         or its comparator does not permit null elements
407 >     * @throws NullPointerException if the specified element is null
408 >     *         and this set uses natural ordering, or its comparator
409 >     *         does not permit null elements
410 >     * @since 1.6
411       */
412      public E floor(E e) {
413          return m.floorKey(e);
# Line 394 | Line 415 | public class TreeSet<E>
415  
416      /**
417       * @throws ClassCastException {@inheritDoc}
418 <     * @throws NullPointerException if the specified element is null and
419 <     *         this set uses natural ordering and is non-empty,
420 <     *         or its comparator does not permit null elements
418 >     * @throws NullPointerException if the specified element is null
419 >     *         and this set uses natural ordering, or its comparator
420 >     *         does not permit null elements
421 >     * @since 1.6
422       */
423      public E ceiling(E e) {
424          return m.ceilingKey(e);
# Line 404 | Line 426 | public class TreeSet<E>
426  
427      /**
428       * @throws ClassCastException {@inheritDoc}
429 <     * @throws NullPointerException if the specified element is null and
430 <     *         this set uses natural ordering and is non-empty,
431 <     *         or its comparator does not permit null elements
429 >     * @throws NullPointerException if the specified element is null
430 >     *         and this set uses natural ordering, or its comparator
431 >     *         does not permit null elements
432 >     * @since 1.6
433       */
434      public E higher(E e) {
435          return m.higherKey(e);
436      }
437  
438 +    /**
439 +     * @since 1.6
440 +     */
441      public E pollFirst() {
442          Map.Entry<E,?> e = m.pollFirstEntry();
443          return (e == null)? null : e.getKey();
444      }
445  
446 +    /**
447 +     * @since 1.6
448 +     */
449      public E pollLast() {
450          Map.Entry<E,?> e = m.pollLastEntry();
451          return (e == null)? null : e.getKey();

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines