[cvs] / jsr166 / src / main / java / util / NavigableSet.java Repository:
ViewVC logotype

Diff of /jsr166/src/main/java/util/NavigableSet.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.22, Fri Apr 21 23:11:14 2006 UTC revision 1.28, Sat Mar 9 01:51:15 2013 UTC
# Line 1  Line 1 
1  /*  /*
2   * Written by Doug Lea and Josh Bloch with assistance from members of JCP   * Written by Doug Lea and Josh Bloch with assistance from members of JCP
3   * JSR-166 Expert Group and released to the public domain, as explained at   * JSR-166 Expert Group and released to the public domain, as explained at
4   * http://creativecommons.org/licenses/publicdomain   * http://creativecommons.org/publicdomain/zero/1.0/
5   */   */
6    
7  package java.util;  package java.util;
8    
9  /**  /**
10   * A {@link SortedSet} extended with navigation methods reporting   * A {@link SortedSet} extended with navigation methods reporting
11   * closest matches for given search targets. Methods {@code lower},   * closest matches for given search targets. Methods {@link #lower},
12   * {@code floor}, {@code ceiling}, and {@code higher} return elements   * {@link #floor}, {@link #ceiling}, and {@link #higher} return elements
13   * respectively less than, less than or equal, greater than or equal,   * respectively less than, less than or equal, greater than or equal,
14   * and greater than a given element, returning {@code null} if there   * and greater than a given element, returning {@code null} if there
15   * is no such element.  A {@code NavigableSet} may be accessed and   * is no such element.  A {@code NavigableSet} may be accessed and
# Line 18  Line 18 
18   * all relational and directional methods inverted. The performance of   * all relational and directional methods inverted. The performance of
19   * ascending operations and views is likely to be faster than that of   * ascending operations and views is likely to be faster than that of
20   * descending ones.  This interface additionally defines methods   * descending ones.  This interface additionally defines methods
21   * {@code pollFirst} and {@code pollLast} that return and remove the   * {@link #pollFirst} and {@link #pollLast} that return and remove the
22   * lowest and highest element, if one exists, else returning {@code   * lowest and highest element, if one exists, else returning {@code
23   * null}.  Methods {@code subSet}, {@code headSet},   * null}.  Methods {@code subSet}, {@code headSet},
24   * and {@code tailSet} differ from the like-named {@code   * and {@code tailSet} differ from the like-named {@code
# Line 35  Line 35 
35   * {@code null} elements. (Note that sorted sets of {@link   * {@code null} elements. (Note that sorted sets of {@link
36   * Comparable} elements intrinsically do not permit {@code null}.)   * Comparable} elements intrinsically do not permit {@code null}.)
37   *   *
38     * <p>Methods
39     * {@link #subSet(Object, Object) subSet(E, E)},
40     * {@link #headSet(Object) headSet(E)}, and
41     * {@link #tailSet(Object) tailSet(E)}
42     * are specified to return {@code SortedSet} to allow existing
43     * implementations of {@code SortedSet} to be compatibly retrofitted to
44     * implement {@code NavigableSet}, but extensions and implementations
45     * of this interface are encouraged to override these methods to return
46     * {@code NavigableSet}.
47     *
48   * <p>This interface is a member of the   * <p>This interface is a member of the
49   * <a href="{@docRoot}/../guide/collections/index.html">   * <a href="{@docRoot}/../technotes/guides/collections/index.html">
50   * Java Collections Framework</a>.   * Java Collections Framework</a>.
51   *   *
52   * @author Doug Lea   * @author Doug Lea
# Line 125  Line 135 
135      Iterator<E> iterator();      Iterator<E> iterator();
136    
137      /**      /**
138       * Returns a {@link NavigableSet} view of the elements contained in this       * Returns a reverse order view of the elements contained in this set.
139       * set in descending order.  The descending set is backed by this set, so       * The descending set is backed by this set, so changes to the set are
140       * changes to the set are reflected in the descending set, and vice-versa.       * reflected in the descending set, and vice-versa.  If either set is
141       * If either set is modified while an iteration over the other set is in       * modified while an iteration over either set is in progress (except
142       * progress (except through the iterator's own {@code remove} operation),       * through the iterator's own {@code remove} operation), the results of
143       * the results of the iteration are undefined.       * the iteration are undefined.
144         *
145         * <p>The returned set has an ordering equivalent to
146         * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
147         * The expression {@code s.descendingSet().descendingSet()} returns a
148         * view of {@code s} essentially equivalent to {@code s}.
149       *       *
150       * @return a navigable set view of the elements contained in this set,       * @return a reverse order view of this set
      *         sorted in descending order  
151       */       */
152      NavigableSet<E> descendingSet();      NavigableSet<E> descendingSet();
153    
# Line 242  Line 256 
256      NavigableSet<E> tailSet(E fromElement, boolean inclusive);      NavigableSet<E> tailSet(E fromElement, boolean inclusive);
257    
258      /**      /**
259       * Equivalent to {@code subSet(fromElement, true, toElement, false)}       * {@inheritDoc}
      * but with a return type conforming to the {@code SortedSet} interface.  
260       *       *
261       * <p>{@inheritDoc}       * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
262       *       *
263       * @throws ClassCastException       {@inheritDoc}       * @throws ClassCastException       {@inheritDoc}
264       * @throws NullPointerException     {@inheritDoc}       * @throws NullPointerException     {@inheritDoc}
# Line 254  Line 267 
267      SortedSet<E> subSet(E fromElement, E toElement);      SortedSet<E> subSet(E fromElement, E toElement);
268    
269      /**      /**
270       * Equivalent to {@code headSet(toElement, false)}       * {@inheritDoc}
      * but with a return type conforming to the {@code SortedSet} interface.  
271       *       *
272       * <p>{@inheritDoc}       * <p>Equivalent to {@code headSet(toElement, false)}.
273       *       *
274       * @throws ClassCastException       {@inheritDoc}       * @throws ClassCastException       {@inheritDoc}
275       * @throws NullPointerException     {@inheritDoc}       * @throws NullPointerException     {@inheritDoc}
276       * @throws IllegalArgumentException {@inheritDoc}       * @throws IllegalArgumentException {@inheritDoc}
277       */  na     */
278      SortedSet<E> headSet(E toElement);      SortedSet<E> headSet(E toElement);
279    
280      /**      /**
281       * Equivalent to {@code tailSet(fromElement, true)}       * {@inheritDoc}
      * but with a return type conforming to the {@code SortedSet} interface.  
282       *       *
283       * <p>{@inheritDoc}       * <p>Equivalent to {@code tailSet(fromElement, true)}.
284       *       *
285       * @throws ClassCastException       {@inheritDoc}       * @throws ClassCastException       {@inheritDoc}
286       * @throws NullPointerException     {@inheritDoc}       * @throws NullPointerException     {@inheritDoc}

Legend:
Removed from v.1.22  
changed lines
  Added in v.1.28

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8