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.2 by dl, Sun Mar 6 12:06:17 2005 UTC vs.
Revision 1.7 by jsr166, Mon May 2 08:35:49 2005 UTC

# Line 1 | Line 1
1   /*
2   * %W% %E%
3   *
4 < * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
4 > * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
5   * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6   */
7  
# Line 210 | Line 210 | public class TreeSet<E>
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.
213 >     * @param e 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 <     * @throws NullPointerException if o is <tt>null</tt> and this map
219 >     * @throws NullPointerException if e is <tt>null</tt> and this map
220       * 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;
223 >    public boolean add(E e) {
224 >        return m.put(e, PRESENT)==null;
225      }
226  
227      /**
# Line 255 | Line 255 | public class TreeSet<E>
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
258 >     * @throws NullPointerException if 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.
# Line 278 | Line 278 | public class TreeSet<E>
278      }
279  
280      /**
281 <     * Returns a view of the portion of this set whose elements range from
282 <     * <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>, exclusive.  (If
283 <     * <tt>fromElement</tt> and <tt>toElement</tt> are equal, the returned
284 <     * sorted set is empty.)  The returned sorted set is backed by this set,
285 <     * so changes in the returned sorted set are reflected in this set, and
286 <     * vice-versa.  The returned sorted set supports all optional Set
287 <     * operations.<p>
281 >     * 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       *
289 <     * The sorted set returned by this method will throw an
289 >     * The navigable set returned by this method will throw an
290       * <tt>IllegalArgumentException</tt> if the user attempts to insert an
291       * element outside the specified range.<p>
292       *
293 <     * Note: this method always returns a <i>half-open range</i> (which
294 <     * includes its low endpoint but not its high endpoint).  If you need a
295 <     * <i>closed range</i> (which includes both endpoints), and the element
296 <     * type allows for calculation of the successor of a specified value,
297 <     * merely request the subrange from <tt>lowEndpoint</tt> to
298 <     * <tt>successor(highEndpoint)</tt>.  For example, suppose that <tt>s</tt>
299 <     * is a sorted set of strings.  The following idiom obtains a view
300 <     * containing all of the strings in <tt>s</tt> from <tt>low</tt> to
301 <     * <tt>high</tt>, inclusive: <pre>
302 <     *     NavigableSet sub = s.subSet(low, high+"\0");
293 >     * 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:
303 >     * <pre> NavigableSet sub = s.navigableSubSet(low, high+"\0");
304       * </pre>
305       *
306       * A similar technique can be used to generate an <i>open range</i> (which
307       * contains neither endpoint).  The following idiom obtains a view
308       * containing all of the strings in <tt>s</tt> from <tt>low</tt> to
309       * <tt>high</tt>, exclusive: <pre>
310 <     *     NavigableSet sub = s.subSet(low+"\0", high);
310 >     *     NavigableSet sub = s.navigableSubSet(low+"\0", high);
311       * </pre>
312       *
313 <     * @param fromElement low endpoint (inclusive) of the subSet.
314 <     * @param toElement high endpoint (exclusive) of the subSet.
313 >     * @param fromElement low endpoint (inclusive) of the range.
314 >     * @param toElement high endpoint (exclusive) of the range.
315       * @return a view of the portion of this set whose elements range from
316       *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
317       *         exclusive.
# Line 325 | Line 326 | public class TreeSet<E>
326       *         order, or its comparator does not tolerate <tt>null</tt>
327       *         elements.
328       */
329 <    public NavigableSet<E> subSet(E fromElement, E toElement) {
330 <        return new TreeSet<E>(m.subMap(fromElement, toElement));
329 >    public NavigableSet<E> navigableSubSet(E fromElement, E toElement) {
330 >        return new TreeSet<E>(m.navigableSubMap(fromElement, toElement));
331      }
332  
333      /**
334 <     * Returns a view of the portion of this set whose elements are strictly
335 <     * less than <tt>toElement</tt>.  The returned sorted set is backed by
336 <     * this set, so changes in the returned sorted set are reflected in this
337 <     * set, and vice-versa.  The returned sorted set supports all optional set
338 <     * operations.<p>
339 <     *
340 <     * The sorted set returned by this method will throw an
341 <     * <tt>IllegalArgumentException</tt> if the user attempts to insert an
342 <     * element greater than or equal to <tt>toElement</tt>.<p>
343 <     *
344 <     * Note: this method always returns a view that does not contain its
345 <     * (high) endpoint.  If you need a view that does contain this endpoint,
346 <     * and the element type allows for calculation of the successor of a
347 <     * specified value, merely request a headSet bounded by
348 <     * <tt>successor(highEndpoint)</tt>.  For example, suppose that <tt>s</tt>
349 <     * is a sorted set of strings.  The following idiom obtains a view
350 <     * containing all of the strings in <tt>s</tt> that are less than or equal
351 <     * to <tt>high</tt>: <pre> NavigableSet head = s.headSet(high+"\0");</pre>
334 >     * Returns a view of the portion of this set whose elements are
335 >     * strictly less than <tt>toElement</tt>.  The returned navigable
336 >     * set is backed by this set, so changes in the returned navigable
337 >     * set are reflected in this set, and vice-versa.  The returned
338 >     * navigable set supports all optional set operations.<p>
339 >     *
340 >     * The navigable set returned by this method will throw an
341 >     * <tt>IllegalArgumentException</tt> if the user attempts to
342 >     * insert an element greater than or equal to
343 >     * <tt>toElement</tt>.<p>
344 >     *
345 >     * Note: this method always returns a view that does not contain
346 >     * its (high) endpoint.  If you need a view that does contain this
347 >     * endpoint, and the element type allows for calculation of the
348 >     * successor of a specified value, merely request a headSet
349 >     * bounded by <tt>successor(highEndpoint)</tt>.  For example,
350 >     * suppose that <tt>s</tt> is a navigable set of strings.  The
351 >     * following idiom obtains a view containing all of the strings in
352 >     * <tt>s</tt> that are less than or equal to <tt>high</tt>:
353 >     * <pre> NavigableSet head = s.navigableHeadSet(high+"\0");</pre>
354       *
355       * @param toElement high endpoint (exclusive) of the headSet.
356       * @return a view of the portion of this set whose elements are strictly
357 <     *         less than toElement.
357 >     *         less than <tt>toElement</tt>.
358       * @throws ClassCastException if <tt>toElement</tt> is not compatible
359       *         with this set's comparator (or, if the set has no comparator,
360       *         if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
361 <     * @throws IllegalArgumentException if this set is itself a subSet,
362 <     *         headSet, or tailSet, and <tt>toElement</tt> is not within the
363 <     *         specified range of the subSet, headSet, or tailSet.
361 >     * @throws IllegalArgumentException if this set is itself a subset,
362 >     *         and <tt>toElement</tt> is not within the
363 >     *         specified range of the subset.
364       * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt> and
365       *         this set uses natural ordering, or its comparator does
366       *         not tolerate <tt>null</tt> elements.
367       */
368 <    public NavigableSet<E> headSet(E toElement) {
369 <        return new TreeSet<E>(m.headMap(toElement));
368 >    public NavigableSet<E> navigableHeadSet(E toElement) {
369 >        return new TreeSet<E>(m.navigableHeadMap(toElement));
370      }
371  
372      /**
373       * Returns a view of the portion of this set whose elements are
374 <     * greater than or equal to <tt>fromElement</tt>.  The returned sorted set
375 <     * is backed by this set, so changes in the returned sorted set are
376 <     * reflected in this set, and vice-versa.  The returned sorted set
377 <     * supports all optional set operations.<p>
374 >     * greater than or equal to <tt>fromElement</tt>.  The returned
375 >     * navigable set is backed by this set, so changes in the returned
376 >     * navigable set are reflected in this set, and vice-versa.  The
377 >     * returned navigable set supports all optional set operations.<p>
378       *
379 <     * The sorted set returned by this method will throw an
379 >     * The navigable set returned by this method will throw an
380       * <tt>IllegalArgumentException</tt> if the user attempts to insert an
381       * element less than <tt>fromElement</tt>.
382       *
383       * Note: this method always returns a view that contains its (low)
384 <     * endpoint.  If you need a view that does not contain this endpoint, and
385 <     * the element type allows for calculation of the successor of a specified
386 <     * value, merely request a tailSet bounded by
387 <     * <tt>successor(lowEndpoint)</tt>.  For example, suppose that <tt>s</tt>
388 <     * is a sorted set of strings.  The following idiom obtains a view
389 <     * containing all of the strings in <tt>s</tt> that are strictly greater
390 <     * than <tt>low</tt>: <pre>
391 <     *     NavigableSet tail = s.tailSet(low+"\0");
384 >     * endpoint.  If you need a view that does not contain this
385 >     * endpoint, and the element type allows for calculation of the
386 >     * successor of a specified value, merely request a tailSet
387 >     * bounded by <tt>successor(lowEndpoint)</tt>.  For example,
388 >     * suppose that <tt>s</tt> is a navigable set of strings.  The
389 >     * following idiom obtains a view containing all of the strings in
390 >     * <tt>s</tt> that are strictly greater than <tt>low</tt>:
391 >     * <pre>  NavigableSet tail = s.navigableTailSet(low+"\0");
392       * </pre>
393       *
394       * @param fromElement low endpoint (inclusive) of the tailSet.
# Line 394 | Line 397 | public class TreeSet<E>
397       * @throws ClassCastException if <tt>fromElement</tt> is not compatible
398       *         with this set's comparator (or, if the set has no comparator,
399       *         if <tt>fromElement</tt> does not implement <tt>Comparable</tt>).
400 <     * @throws IllegalArgumentException if this set is itself a subSet,
401 <     *         headSet, or tailSet, and <tt>fromElement</tt> is not within the
402 <     *         specified range of the subSet, headSet, or tailSet.
400 >     * @throws IllegalArgumentException if this set is itself a subset,
401 >     *         and <tt>fromElement</tt> is not within the
402 >     *         specified range of the subset.
403 >     * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
404 >     *         and this set uses natural ordering, or its comparator does
405 >     *         not tolerate <tt>null</tt> elements.
406 >     */
407 >    public NavigableSet<E> navigableTailSet(E fromElement) {
408 >        return new TreeSet<E>(m.navigableTailMap(fromElement));
409 >    }
410 >
411 >
412 >    /**
413 >     * Equivalent to <tt>navigableSubSet</tt> but with a return
414 >     * type conforming to the <tt>SortedSet</tt> interface.
415 >     * @param fromElement low endpoint (inclusive) of the range.
416 >     * @param toElement high endpoint (exclusive) of the range.
417 >     * @return a view of the portion of this set whose elements range from
418 >     *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
419 >     *         exclusive.
420 >     * @throws ClassCastException if <tt>fromElement</tt> and
421 >     *         <tt>toElement</tt> cannot be compared to one another using
422 >     *         this set's comparator (or, if the set has no comparator,
423 >     *         using natural ordering).
424 >     * @throws IllegalArgumentException if <tt>fromElement</tt> is greater than
425 >     *         <tt>toElement</tt>.
426 >     * @throws NullPointerException if <tt>fromElement</tt> or
427 >     *         <tt>toElement</tt> is <tt>null</tt> and this set uses natural
428 >     *         order, or its comparator does not tolerate <tt>null</tt>
429 >     *         elements.
430 >     */
431 >    public SortedSet<E> subSet(E fromElement, E toElement) {
432 >        return new TreeSet<E>(m.navigableSubMap(fromElement, toElement));
433 >    }
434 >
435 >    /**
436 >     * Equivalent to <tt>navigableHeadSet</tt> but with a return
437 >     * type conforming to the <tt>SortedSet</tt> interface.
438 >     *
439 >     * @param toElement high endpoint (exclusive) of the headSet.
440 >     * @return a view of the portion of this set whose elements are strictly
441 >     *         less than <tt>toElement</tt>.
442 >     * @throws ClassCastException if <tt>toElement</tt> is not compatible
443 >     *         with this set's comparator (or, if the set has no comparator,
444 >     *         if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
445 >     * @throws IllegalArgumentException if this set is itself a subset,
446 >     *         and <tt>toElement</tt> is not within the
447 >     *         specified range of the subset.
448 >     * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt> and
449 >     *         this set uses natural ordering, or its comparator does
450 >     *         not tolerate <tt>null</tt> elements.
451 >     */
452 >    public SortedSet<E> headSet(E toElement) {
453 >        return new TreeSet<E>(m.navigableHeadMap(toElement));
454 >    }
455 >
456 >    /**
457 >     * Equivalent to <tt>navigableTailSet</tt> but with a return
458 >     * type conforming to the <tt>SortedSet</tt> interface.
459 >     * @param fromElement low endpoint (inclusive) of the tailSet.
460 >     * @return a view of the portion of this set whose elements are
461 >     *         greater than or equal to <tt>fromElement</tt>.
462 >     * @throws ClassCastException if <tt>fromElement</tt> is not compatible
463 >     *         with this set's comparator (or, if the set has no comparator,
464 >     *         if <tt>fromElement</tt> does not implement <tt>Comparable</tt>).
465 >     * @throws IllegalArgumentException if this set is itself a subset,
466 >     *         and <tt>fromElement</tt> is not within the
467 >     *         specified range of the subset.
468       * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
469       *         and this set uses natural ordering, or its comparator does
470       *         not tolerate <tt>null</tt> elements.
471       */
472 <    public NavigableSet<E> tailSet(E fromElement) {
473 <        return new TreeSet<E>(m.tailMap(fromElement));
472 >    public SortedSet<E> tailSet(E fromElement) {
473 >        return new TreeSet<E>(m.navigableTailMap(fromElement));
474      }
475  
476      /**
# Line 443 | Line 511 | public class TreeSet<E>
511       * Returns an element greater than or equal to the given element, or
512       * <tt>null</tt> if there is no such element.
513       *
514 <     * @param o the value to match
514 >     * @param e the value to match
515       * @return an element greater than or equal to given element, or
516       * <tt>null</tt> if there is no such element.
517 <     * @throws ClassCastException if o cannot be compared with the elements
517 >     * @throws ClassCastException if e cannot be compared with the elements
518       *            currently in the set.
519 <     * @throws NullPointerException if o is <tt>null</tt> and this map
519 >     * @throws NullPointerException if e is <tt>null</tt> and this map
520       * uses natural ordering and is non-empty, or its comparator does
521       * not tolerate <tt>null</tt> keys.
522       */
523 <    public E ceiling(E o) {
524 <        return m.ceilingKey(o);
523 >    public E ceiling(E e) {
524 >        return m.ceilingKey(e);
525      }
526  
527      /**
528       * Returns an element strictly less than the given element, or
529       * <tt>null</tt> if there is no such element.
530       *
531 <     * @param o the value to match
531 >     * @param e the value to match
532       * @return the greatest element less than the given element, or
533       * <tt>null</tt> if there is no such element.
534 <     * @throws ClassCastException if o cannot be compared with the elements
534 >     * @throws ClassCastException if e cannot be compared with the elements
535       *            currently in the set.
536 <     * @throws NullPointerException if o is <tt>null</tt> and this map
536 >     * @throws NullPointerException if e is <tt>null</tt> and this map
537       * uses natural ordering and is non-empty, or its comparator does
538       * not tolerate <tt>null</tt> keys.
539       */
540 <    public E lower(E o) {
541 <        return m.lowerKey(o);
540 >    public E lower(E e) {
541 >        return m.lowerKey(e);
542      }
543  
544      /**
545       * Returns an element less than or equal to the given element, or
546       * <tt>null</tt> if there is no such element.
547       *
548 <     * @param o the value to match
548 >     * @param e the value to match
549       * @return the greatest element less than or equal to given
550       * element, or <tt>null</tt> if there is no such element.
551 <     * @throws ClassCastException if o cannot be compared with the elements
551 >     * @throws ClassCastException if e cannot be compared with the elements
552       *            currently in the set.
553 <     * @throws NullPointerException if o is <tt>null</tt> and this map
553 >     * @throws NullPointerException if e is <tt>null</tt> and this map
554       * uses natural ordering and is non-empty, or its comparator does
555       * not tolerate <tt>null</tt> keys.
556       */
557 <    public E floor(E o) {
558 <        return m.floorKey(o);
557 >    public E floor(E e) {
558 >        return m.floorKey(e);
559      }
560  
561      /**
562       * Returns an element strictly greater than the given element, or
563       * <tt>null</tt> if there is no such element.
564       *
565 <     * @param o the value to match
565 >     * @param e the value to match
566       * @return the least element greater than the given element, or
567       * <tt>null</tt> if there is no such element.
568 <     * @throws ClassCastException if o cannot be compared with the elements
568 >     * @throws ClassCastException if e cannot be compared with the elements
569       *            currently in the set.
570 <     * @throws NullPointerException if o is <tt>null</tt> and this map
570 >     * @throws NullPointerException if e is <tt>null</tt> and this map
571       * uses natural ordering and is non-empty, or its comparator does
572       * not tolerate <tt>null</tt> keys.
573       */
574 <    public E higher(E o) {
575 <        return m.higherKey(o);
574 >    public E higher(E e) {
575 >        return m.higherKey(e);
576      }
577  
578      /**

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines