[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.14, Tue Feb 7 20:54:24 2006 UTC revision 1.15, Wed Apr 19 15:07:14 2006 UTC
# Line 1  Line 1 
1  /*  /*
2   * Written by Doug Lea with assistance from members of JCP JSR-166   * Written by Doug Lea and Josh Bloch with assistance from members of JCP
3   * 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/licenses/publicdomain
5   */   */
6    
# Line 8  Line 8 
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 <tt>lower</tt>,   * closest matches for given search targets. Methods <tt>lower},
12   * <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return elements   * {@code floor}, {@code ceiling}, and {@code 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 <tt>null</tt> if there is   * and greater than a given element, returning {@code null} if there
15   * no such element.  A <tt>NavigableSet</tt> may be viewed and traversed   * is no such element.  A {@code NavigableSet} may be accessed and
16   * in either ascending or descending order.  The <tt>Collection</tt>   * traversed in either ascending or descending order.  The {@code
17   * <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and   * descendingSet} method returns a view of the set with the senses of
18   * the additional method <tt>descendingIterator</tt> returns a   * all relational and directional methods inverted. The performance of
19   * descending iterator. The performance of ascending traversals is   * ascending operations and views is likely to be faster than that of
20   * likely to be faster than descending traversals.  This interface   * descending ones.  This interface additionally defines methods
21   * additionally defines methods <tt>pollFirst</tt> and   * {@code pollFirst} and {@code pollLast} that return and remove the
22   * <tt>pollLast</tt> that return and remove the lowest and highest   * lowest and highest element, if one exists, else returning {@code
23   * element, if one exists, else returning <tt>null</tt>.   * null}.  Methods {@code navigableSubSet}, {@code navigableHeadSet},
24   * Methods <tt>navigableSubSet</tt>, <tt>navigableHeadSet</tt>, and   * and {@code navigableTailSet} differ from the similarly named {@code
25   * <tt>navigableTailSet</tt> differ from the similarly named   * SortedSet} methods in accepting additional arguments describing
26   * <tt>SortedSet</tt> methods only in their declared return types.   * whether lower and upper bounds are inclusive versus exclusive.
27   * Subsets of any <tt>NavigableSet</tt> must implement the   * Subsets of any {@code NavigableSet} must implement the {@code
28   * <tt>NavigableSet</tt> interface.   * NavigableSet} interface.
29   *   *
30   * <p> The return values of navigation methods may be ambiguous in   * <p> The return values of navigation methods may be ambiguous in
31   * implementations that permit <tt>null</tt> elements. However, even   * implementations that permit {@code null} elements. However, even
32   * in this case the result can be disambiguated by checking   * in this case the result can be disambiguated by checking
33   * <tt>contains(null)</tt>. To avoid such issues, implementations of   * {@code contains(null)}. To avoid such issues, implementations of
34   * this interface are encouraged to <em>not</em> permit insertion of   * this interface are encouraged to <em>not</em> permit insertion of
35   * <tt>null</tt> elements. (Note that sorted sets of {@link   * {@code null} elements. (Note that sorted sets of {@link
36   * Comparable} elements intrinsically do not permit <tt>null</tt>.)   * Comparable} elements intrinsically do not permit {@code null}.)
37   *   *
38   * <p>This interface is a member of the   * <p>This interface is a member of the
39   * <a href="{@docRoot}/../guide/collections/index.html">   * <a href="{@docRoot}/../guide/collections/index.html">
40   * Java Collections Framework</a>.   * Java Collections Framework</a>.
41   *   *
42   * @author Doug Lea   * @author Doug Lea
43     * @author Josh Bloch
44   * @param <E> the type of elements maintained by this set   * @param <E> the type of elements maintained by this set
45   * @since 1.6   * @since 1.6
46   */   */
47  public interface NavigableSet<E> extends SortedSet<E> {  public interface NavigableSet<E> extends SortedSet<E> {
48      /**      /**
49       * Returns the greatest element in this set strictly less than the       * Returns the greatest element in this set strictly less than the
50       * given element, or <tt>null</tt> if there is no such element.       * given element, or {@code null} if there is no such element.
51       *       *
52       * @param e the value to match       * @param e the value to match
53       * @return the greatest element less than <tt>e</tt>,       * @return the greatest element less than {@code e},
54       *         or <tt>null</tt> if there is no such element       *         or {@code null} if there is no such element
55       * @throws ClassCastException if the specified element cannot be       * @throws ClassCastException if the specified element cannot be
56       *         compared with the elements currently in the set       *         compared with the elements currently in the set
57       * @throws NullPointerException if the specified element is null       * @throws NullPointerException if the specified element is null
# Line 60  Line 61 
61    
62      /**      /**
63       * Returns the greatest element in this set less than or equal to       * Returns the greatest element in this set less than or equal to
64       * the given element, or <tt>null</tt> if there is no such element.       * the given element, or {@code null} if there is no such element.
65       *       *
66       * @param e the value to match       * @param e the value to match
67       * @return the greatest element less than or equal to <tt>e</tt>,       * @return the greatest element less than or equal to {@code e},
68       *         or <tt>null</tt> if there is no such element       *         or {@code null} if there is no such element
69       * @throws ClassCastException if the specified element cannot be       * @throws ClassCastException if the specified element cannot be
70       *         compared with the elements currently in the set       *         compared with the elements currently in the set
71       * @throws NullPointerException if the specified element is null       * @throws NullPointerException if the specified element is null
# Line 74  Line 75 
75    
76      /**      /**
77       * Returns the least element in this set greater than or equal to       * Returns the least element in this set greater than or equal to
78       * the given element, or <tt>null</tt> if there is no such element.       * the given element, or {@code null} if there is no such element.
79       *       *
80       * @param e the value to match       * @param e the value to match
81       * @return the least element greater than or equal to <tt>e</tt>,       * @return the least element greater than or equal to {@code e},
82       *         or <tt>null</tt> if there is no such element       *         or {@code null} if there is no such element
83       * @throws ClassCastException if the specified element cannot be       * @throws ClassCastException if the specified element cannot be
84       *         compared with the elements currently in the set       *         compared with the elements currently in the set
85       * @throws NullPointerException if the specified element is null       * @throws NullPointerException if the specified element is null
# Line 88  Line 89 
89    
90      /**      /**
91       * Returns the least element in this set strictly greater than the       * Returns the least element in this set strictly greater than the
92       * given element, or <tt>null</tt> if there is no such element.       * given element, or {@code null} if there is no such element.
93       *       *
94       * @param e the value to match       * @param e the value to match
95       * @return the least element greater than <tt>e</tt>,       * @return the least element greater than {@code e},
96       *         or <tt>null</tt> if there is no such element       *         or {@code null} if there is no such element
97       * @throws ClassCastException if the specified element cannot be       * @throws ClassCastException if the specified element cannot be
98       *         compared with the elements currently in the set       *         compared with the elements currently in the set
99       * @throws NullPointerException if the specified element is null       * @throws NullPointerException if the specified element is null
# Line 102  Line 103 
103    
104      /**      /**
105       * Retrieves and removes the first (lowest) element,       * Retrieves and removes the first (lowest) element,
106       * or returns <tt>null</tt> if this set is empty.       * or returns {@code null} if this set is empty.
107       *       *
108       * @return the first element, or <tt>null</tt> if this set is empty       * @return the first element, or {@code null} if this set is empty
109       */       */
110      E pollFirst();      E pollFirst();
111    
112      /**      /**
113       * Retrieves and removes the last (highest) element,       * Retrieves and removes the last (highest) element,
114       * or returns <tt>null</tt> if this set is empty.       * or returns {@code null} if this set is empty.
115       *       *
116       * @return the last element, or <tt>null</tt> if this set is empty       * @return the last element, or {@code null} if this set is empty
117       */       */
118      E pollLast();      E pollLast();
119    
# Line 124  Line 125 
125      Iterator<E> iterator();      Iterator<E> iterator();
126    
127      /**      /**
128         * Returns a {@link NavigableSet} view of the elements contained in this
129         * set in descending order.  The descending set is backed by this set, so
130         * changes to the set are reflected in the descending set, and vice-versa.
131         * If either set is modified while an iteration over the other set is in
132         * in progress (except through the iterator's own {@code remove} operation),
133         * the results of the iteration are undefined.
134         *
135         * @return a navigable set view of the mappings contained in this set,
136         *     sorted in descending order
137         */
138        NavigableSet<E> descendingSet();
139    
140        /**
141       * Returns an iterator over the elements in this set, in descending order.       * Returns an iterator over the elements in this set, in descending order.
142         * Equivalent in effect to <tt>descendingSet().iterator()</tt>.
143       *       *
144       * @return an iterator over the elements in this set, in descending order       * @return an iterator over the elements in this set, in descending order
145       */       */
146      Iterator<E> descendingIterator();      Iterator<E> descendingIterator();
147    
148      /**      /**
149       * Returns a view of the portion of this set whose elements range       * Returns a view of the portion of this set whose elements range from
150       * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,       * {@code fromElement} to {@code toElement}.  If {@code fromElement} and
151       * exclusive.  (If <tt>fromElement</tt> and <tt>toElement</tt> are       * {@code toElement} are equal, the returned set is empty unless {@code
152       * equal, the returned set is empty.)  The returned set is backed       * fromExclusive} and {@code toExclusive} are both true.  The returned set
153       * by this set, so changes in the returned set are reflected in       * is backed by this set, so changes in the returned set are reflected in
154       * this set, and vice-versa.  The returned set supports all       * this set, and vice-versa.  The returned set supports all optional set
155       * optional set operations that this set supports.       * operations that this set supports.
156       *       *
157       * <p>The returned set will throw an <tt>IllegalArgumentException</tt>       * <p>The returned set will throw an {@code IllegalArgumentException}
158       * on an attempt to insert an element outside its range.       * on an attempt to insert an element outside its range.
159       *       *
160       * @param fromElement low endpoint (inclusive) of the returned set       * @param fromElement low endpoint of the returned set
161       * @param toElement high endpoint (exclusive) of the returned set       * @param fromInclusive true if the low endpoint ({@code fromElement}) is
162         *        to be included in the the returned view
163         * @param toElement high endpoint of the returned set
164         * @param toInclusive true if the high endpoint ({@code toElement}) is
165         *        to be included in the the returned view
166       * @return a view of the portion of this set whose elements range from       * @return a view of the portion of this set whose elements range from
167       *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>, exclusive       *         {@code fromElement}, inclusive, to {@code toElement}, exclusive
168       * @throws ClassCastException if <tt>fromElement</tt> and       * @throws ClassCastException if {@code fromElement} and
169       *         <tt>toElement</tt> cannot be compared to one another using this       *         {@code toElement} cannot be compared to one another using this
170       *         set's comparator (or, if the set has no comparator, using       *         set's comparator (or, if the set has no comparator, using
171       *         natural ordering).  Implementations may, but are not required       *         natural ordering).  Implementations may, but are not required
172       *         to, throw this exception if <tt>fromElement</tt> or       *         to, throw this exception if {@code fromElement} or
173       *         <tt>toElement</tt> cannot be compared to elements currently in       *         {@code toElement} cannot be compared to elements currently in
174       *         the set.       *         the set.
175       * @throws NullPointerException if <tt>fromElement</tt> or       * @throws NullPointerException if {@code fromElement} or
176       *         <tt>toElement</tt> is null and this set does       *         {@code toElement} is null and this set does
177       *         not permit null elements       *         not permit null elements
178       * @throws IllegalArgumentException if <tt>fromElement</tt> is       * @throws IllegalArgumentException if {@code fromElement} is
179       *         greater than <tt>toElement</tt>; or if this set itself       *         greater than {@code toElement}; or if this set itself
180       *         has a restricted range, and <tt>fromElement</tt> or       *         has a restricted range, and {@code fromElement} or
181       *         <tt>toElement</tt> lies outside the bounds of the range.       *         {@code toElement} lies outside the bounds of the range.
182       */       */
183      NavigableSet<E> navigableSubSet(E fromElement, E toElement);      NavigableSet<E> navigableSubSet(E fromElement, boolean fromInclusive,
184                                        E toElement,   boolean toInclusive);
185    
186      /**      /**
187       * Returns a view of the portion of this set whose elements are       * Returns a view of the portion of this set whose elements are less than
188       * strictly less than <tt>toElement</tt>.  The returned set is       * (or equal to, if {@code inclusive} is true) {@code toElement}.  The
189       * backed by this set, so changes in the returned set are       * returned set is backed by this set, so changes in the returned set are
190       * reflected in this set, and vice-versa.  The returned set       * reflected in this set, and vice-versa.  The returned set supports all
191       * supports all optional set operations that this set supports.       * optional set operations that this set supports.
192       *       *
193       * <p>The returned set will throw an <tt>IllegalArgumentException</tt>       * <p>The returned set will throw an {@code IllegalArgumentException}
194       * on an attempt to insert an element outside its range.       * on an attempt to insert an element outside its range.
195       *       *
196       * @param toElement high endpoint (exclusive) of the returned set       * @param toElement high endpoint of the returned set
197       * @return a view of the portion of this set whose elements are strictly       * @param inclusive true if the high endpoint ({@code toElement}) is
198       *         less than <tt>toElement</tt>       *        to be included in the the returned view
199       * @throws ClassCastException if <tt>toElement</tt> is not compatible       * @return a view of the portion of this set whose elements are less than
200         *         (or equal to, if {@code inclusive} is true) {@code toElement}
201         * @throws ClassCastException if {@code toElement} is not compatible
202       *         with this set's comparator (or, if the set has no comparator,       *         with this set's comparator (or, if the set has no comparator,
203       *         if <tt>toElement</tt> does not implement {@link Comparable}).       *         if {@code toElement} does not implement {@link Comparable}).
204       *         Implementations may, but are not required to, throw this       *         Implementations may, but are not required to, throw this
205       *         exception if <tt>toElement</tt> cannot be compared to elements       *         exception if {@code toElement} cannot be compared to elements
206       *         currently in the set.       *         currently in the set.
207       * @throws NullPointerException if <tt>toElement</tt> is null and       * @throws NullPointerException if {@code toElement} is null and
208       *         this set does not permit null elements       *         this set does not permit null elements
209       * @throws IllegalArgumentException if this set itself has a       * @throws IllegalArgumentException if this set itself has a
210       *         restricted range, and <tt>toElement</tt> lies outside the       *         restricted range, and {@code toElement} lies outside the
211       *         bounds of the range       *         bounds of the range
212       */       */
213      NavigableSet<E> navigableHeadSet(E toElement);      NavigableSet<E> navigableHeadSet(E toElement, boolean inclusive);
214    
215      /**      /**
216       * Returns a view of the portion of this set whose elements are       * Returns a view of the portion of this set whose elements are greater
217       * greater than or equal to <tt>fromElement</tt>.  The returned       * than (or equal to, if {@code inclusive} is true) {@code fromElement}.
218       * set is backed by this set, so changes in the returned set are       * The returned set is backed by this set, so changes in the returned set
219       * reflected in this set, and vice-versa.  The returned set       * are reflected in this set, and vice-versa.  The returned set supports
220       * supports all optional set operations that this set supports.       * all optional set operations that this set supports.
221       *       *
222       * <p>The returned set will throw an <tt>IllegalArgumentException</tt>       * <p>The returned set will throw an {@code IllegalArgumentException}
223       * on an attempt to insert an element outside its range.       * on an attempt to insert an element outside its range.
224       *       *
225       * @param fromElement low endpoint (inclusive) of the returned set       * @param fromElement low endpoint of the returned set
226         * @param inclusive true if the low endpoint ({@code fromElement}) is
227         *        to be included in the the returned view
228       * @return a view of the portion of this set whose elements are greater       * @return a view of the portion of this set whose elements are greater
229       *         than or equal to <tt>fromElement</tt>       *         than or equal to {@code fromElement}
230       * @throws ClassCastException if <tt>fromElement</tt> is not compatible       * @throws ClassCastException if {@code fromElement} is not compatible
231       *         with this set's comparator (or, if the set has no comparator,       *         with this set's comparator (or, if the set has no comparator,
232       *         if <tt>fromElement</tt> does not implement {@link Comparable}).       *         if {@code fromElement} does not implement {@link Comparable}).
233       *         Implementations may, but are not required to, throw this       *         Implementations may, but are not required to, throw this
234       *         exception if <tt>fromElement</tt> cannot be compared to elements       *         exception if {@code fromElement} cannot be compared to elements
235       *         currently in the set.       *         currently in the set.
236       * @throws NullPointerException if <tt>fromElement</tt> is null       * @throws NullPointerException if {@code fromElement} is null
237       *         and this set does not permit null elements       *         and this set does not permit null elements
238       * @throws IllegalArgumentException if this set itself has a       * @throws IllegalArgumentException if this set itself has a
239       *         restricted range, and <tt>fromElement</tt> lies outside the       *         restricted range, and {@code fromElement} lies outside the
240       *         bounds of the range       *         bounds of the range
241       */       */
242      NavigableSet<E> navigableTailSet(E fromElement);      NavigableSet<E> navigableTailSet(E fromElement, boolean inclusive);
243  }  }

Legend:
Removed from v.1.14  
changed lines
  Added in v.1.15

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8