ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/NavigableSet.java
Revision: 1.33
Committed: Mon Oct 1 00:10:53 2018 UTC (5 years, 7 months ago) by jsr166
Branch: MAIN
CVS Tags: HEAD
Changes since 1.32: +1 -1 lines
Log Message: 
update to using jdk11 by default, except link to jdk10 javadocs;
sync @docRoot references in javadoc with upstream

File Contents

# User Rev Content
1 dl 1.1 /*
2 dl 1.15 * 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
4 jsr166 1.25 * http://creativecommons.org/publicdomain/zero/1.0/
5 dl 1.1 */
6    
7     package java.util;
8    
9     /**
10     * A {@link SortedSet} extended with navigation methods reporting
11 jsr166 1.27 * closest matches for given search targets. Methods {@link #lower},
12     * {@link #floor}, {@link #ceiling}, and {@link #higher} return elements
13 dl 1.1 * respectively less than, less than or equal, greater than or equal,
14 dl 1.15 * and greater than a given element, returning {@code null} if there
15 jsr166 1.31 * is no such element.
16     *
17     * <p>A {@code NavigableSet} may be accessed and traversed in either
18     * ascending or descending order. The {@link #descendingSet} method
19     * returns a view of the set with the senses of all relational and
20     * directional methods inverted. The performance of ascending
21     * operations and views is likely to be faster than that of descending
22     * ones. This interface additionally defines methods {@link
23     * #pollFirst} and {@link #pollLast} that return and remove the lowest
24     * and highest element, if one exists, else returning {@code null}.
25     * Methods
26     * {@link #subSet(Object, boolean, Object, boolean) subSet(E, boolean, E, boolean)},
27     * {@link #headSet(Object, boolean) headSet(E, boolean)}, and
28     * {@link #tailSet(Object, boolean) tailSet(E, boolean)}
29     * differ from the like-named {@code SortedSet} methods in accepting
30     * additional arguments describing whether lower and upper bounds are
31     * inclusive versus exclusive. Subsets of any {@code NavigableSet}
32     * must implement the {@code NavigableSet} interface.
33 dl 1.1 *
34 jsr166 1.26 * <p>The return values of navigation methods may be ambiguous in
35 dl 1.15 * implementations that permit {@code null} elements. However, even
36 dl 1.1 * in this case the result can be disambiguated by checking
37 dl 1.15 * {@code contains(null)}. To avoid such issues, implementations of
38 jsr166 1.9 * this interface are encouraged to <em>not</em> permit insertion of
39 dl 1.15 * {@code null} elements. (Note that sorted sets of {@link
40     * Comparable} elements intrinsically do not permit {@code null}.)
41 dl 1.1 *
42 jsr166 1.23 * <p>Methods
43     * {@link #subSet(Object, Object) subSet(E, E)},
44     * {@link #headSet(Object) headSet(E)}, and
45     * {@link #tailSet(Object) tailSet(E)}
46     * are specified to return {@code SortedSet} to allow existing
47     * implementations of {@code SortedSet} to be compatibly retrofitted to
48     * implement {@code NavigableSet}, but extensions and implementations
49     * of this interface are encouraged to override these methods to return
50     * {@code NavigableSet}.
51 jsr166 1.24 *
52 jsr166 1.8 * <p>This interface is a member of the
53 jsr166 1.33 * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
54 jsr166 1.8 * Java Collections Framework</a>.
55     *
56 dl 1.1 * @author Doug Lea
57 dl 1.15 * @author Josh Bloch
58 dl 1.1 * @param <E> the type of elements maintained by this set
59 jsr166 1.7 * @since 1.6
60 dl 1.1 */
61     public interface NavigableSet<E> extends SortedSet<E> {
62     /**
63 jsr166 1.9 * Returns the greatest element in this set strictly less than the
64 dl 1.15 * given element, or {@code null} if there is no such element.
65 jsr166 1.6 *
66 jsr166 1.5 * @param e the value to match
67 dl 1.15 * @return the greatest element less than {@code e},
68     * or {@code null} if there is no such element
69 jsr166 1.9 * @throws ClassCastException if the specified element cannot be
70     * compared with the elements currently in the set
71     * @throws NullPointerException if the specified element is null
72     * and this set does not permit null elements
73 dl 1.1 */
74 jsr166 1.9 E lower(E e);
75 dl 1.1
76     /**
77 jsr166 1.9 * Returns the greatest element in this set less than or equal to
78 dl 1.15 * the given element, or {@code null} if there is no such element.
79 jsr166 1.6 *
80 jsr166 1.5 * @param e the value to match
81 dl 1.15 * @return the greatest element less than or equal to {@code e},
82     * or {@code null} if there is no such element
83 jsr166 1.9 * @throws ClassCastException if the specified element cannot be
84     * compared with the elements currently in the set
85     * @throws NullPointerException if the specified element is null
86     * and this set does not permit null elements
87 dl 1.1 */
88 jsr166 1.9 E floor(E e);
89 dl 1.1
90     /**
91 jsr166 1.9 * Returns the least element in this set greater than or equal to
92 dl 1.15 * the given element, or {@code null} if there is no such element.
93 jsr166 1.6 *
94 jsr166 1.5 * @param e the value to match
95 dl 1.15 * @return the least element greater than or equal to {@code e},
96     * or {@code null} if there is no such element
97 jsr166 1.9 * @throws ClassCastException if the specified element cannot be
98     * compared with the elements currently in the set
99     * @throws NullPointerException if the specified element is null
100     * and this set does not permit null elements
101 dl 1.1 */
102 jsr166 1.9 E ceiling(E e);
103 dl 1.1
104     /**
105 jsr166 1.9 * Returns the least element in this set strictly greater than the
106 dl 1.15 * given element, or {@code null} if there is no such element.
107 jsr166 1.6 *
108 jsr166 1.5 * @param e the value to match
109 dl 1.15 * @return the least element greater than {@code e},
110     * or {@code null} if there is no such element
111 jsr166 1.9 * @throws ClassCastException if the specified element cannot be
112     * compared with the elements currently in the set
113     * @throws NullPointerException if the specified element is null
114     * and this set does not permit null elements
115 dl 1.1 */
116 jsr166 1.5 E higher(E e);
117 dl 1.1
118     /**
119 jsr166 1.13 * Retrieves and removes the first (lowest) element,
120 dl 1.15 * or returns {@code null} if this set is empty.
121 dl 1.1 *
122 dl 1.15 * @return the first element, or {@code null} if this set is empty
123 dl 1.1 */
124 dl 1.3 E pollFirst();
125 dl 1.1
126     /**
127 jsr166 1.13 * Retrieves and removes the last (highest) element,
128 dl 1.15 * or returns {@code null} if this set is empty.
129 dl 1.1 *
130 dl 1.15 * @return the last element, or {@code null} if this set is empty
131 dl 1.1 */
132 dl 1.3 E pollLast();
133 dl 1.1
134     /**
135 jsr166 1.10 * Returns an iterator over the elements in this set, in ascending order.
136 jsr166 1.6 *
137 jsr166 1.10 * @return an iterator over the elements in this set, in ascending order
138     */
139     Iterator<E> iterator();
140    
141     /**
142 jsr166 1.23 * Returns a reverse order view of the elements contained in this set.
143     * The descending set is backed by this set, so changes to the set are
144     * reflected in the descending set, and vice-versa. If either set is
145     * modified while an iteration over either set is in progress (except
146     * through the iterator's own {@code remove} operation), the results of
147     * the iteration are undefined.
148     *
149     * <p>The returned set has an ordering equivalent to
150 jsr166 1.28 * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
151 jsr166 1.23 * The expression {@code s.descendingSet().descendingSet()} returns a
152     * view of {@code s} essentially equivalent to {@code s}.
153 dl 1.15 *
154 jsr166 1.23 * @return a reverse order view of this set
155 dl 1.15 */
156     NavigableSet<E> descendingSet();
157    
158     /**
159 jsr166 1.10 * Returns an iterator over the elements in this set, in descending order.
160 jsr166 1.22 * Equivalent in effect to {@code descendingSet().iterator()}.
161 jsr166 1.10 *
162     * @return an iterator over the elements in this set, in descending order
163 dl 1.1 */
164     Iterator<E> descendingIterator();
165    
166     /**
167 dl 1.15 * Returns a view of the portion of this set whose elements range from
168     * {@code fromElement} to {@code toElement}. If {@code fromElement} and
169     * {@code toElement} are equal, the returned set is empty unless {@code
170 jsr166 1.30 * fromInclusive} and {@code toInclusive} are both true. The returned set
171 dl 1.15 * is backed by this set, so changes in the returned set are reflected in
172     * this set, and vice-versa. The returned set supports all optional set
173     * operations that this set supports.
174 dl 1.3 *
175 dl 1.15 * <p>The returned set will throw an {@code IllegalArgumentException}
176 jsr166 1.9 * on an attempt to insert an element outside its range.
177     *
178 dl 1.15 * @param fromElement low endpoint of the returned set
179 jsr166 1.21 * @param fromInclusive {@code true} if the low endpoint
180     * is to be included in the returned view
181 dl 1.15 * @param toElement high endpoint of the returned set
182 jsr166 1.21 * @param toInclusive {@code true} if the high endpoint
183     * is to be included in the returned view
184 dl 1.1 * @return a view of the portion of this set whose elements range from
185 dl 1.15 * {@code fromElement}, inclusive, to {@code toElement}, exclusive
186     * @throws ClassCastException if {@code fromElement} and
187     * {@code toElement} cannot be compared to one another using this
188 jsr166 1.9 * set's comparator (or, if the set has no comparator, using
189     * natural ordering). Implementations may, but are not required
190 dl 1.15 * to, throw this exception if {@code fromElement} or
191     * {@code toElement} cannot be compared to elements currently in
192 jsr166 1.9 * the set.
193 dl 1.15 * @throws NullPointerException if {@code fromElement} or
194     * {@code toElement} is null and this set does
195 jsr166 1.9 * not permit null elements
196 dl 1.15 * @throws IllegalArgumentException if {@code fromElement} is
197     * greater than {@code toElement}; or if this set itself
198     * has a restricted range, and {@code fromElement} or
199     * {@code toElement} lies outside the bounds of the range.
200     */
201 dl 1.16 NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
202     E toElement, boolean toInclusive);
203 dl 1.1
204     /**
205 dl 1.15 * Returns a view of the portion of this set whose elements are less than
206     * (or equal to, if {@code inclusive} is true) {@code toElement}. The
207     * returned set is backed by this set, so changes in the returned set are
208     * reflected in this set, and vice-versa. The returned set supports all
209     * optional set operations that this set supports.
210 jsr166 1.9 *
211 dl 1.15 * <p>The returned set will throw an {@code IllegalArgumentException}
212 jsr166 1.9 * on an attempt to insert an element outside its range.
213     *
214 dl 1.15 * @param toElement high endpoint of the returned set
215 jsr166 1.21 * @param inclusive {@code true} if the high endpoint
216     * is to be included in the returned view
217 dl 1.15 * @return a view of the portion of this set whose elements are less than
218     * (or equal to, if {@code inclusive} is true) {@code toElement}
219     * @throws ClassCastException if {@code toElement} is not compatible
220 dl 1.1 * with this set's comparator (or, if the set has no comparator,
221 dl 1.15 * if {@code toElement} does not implement {@link Comparable}).
222 jsr166 1.9 * Implementations may, but are not required to, throw this
223 dl 1.15 * exception if {@code toElement} cannot be compared to elements
224 jsr166 1.9 * currently in the set.
225 dl 1.15 * @throws NullPointerException if {@code toElement} is null and
226 jsr166 1.9 * this set does not permit null elements
227     * @throws IllegalArgumentException if this set itself has a
228 dl 1.15 * restricted range, and {@code toElement} lies outside the
229 jsr166 1.9 * bounds of the range
230 dl 1.1 */
231 dl 1.16 NavigableSet<E> headSet(E toElement, boolean inclusive);
232 dl 1.1
233     /**
234 dl 1.15 * Returns a view of the portion of this set whose elements are greater
235     * than (or equal to, if {@code inclusive} is true) {@code fromElement}.
236     * The returned set is backed by this set, so changes in the returned set
237     * are reflected in this set, and vice-versa. The returned set supports
238     * all optional set operations that this set supports.
239 jsr166 1.9 *
240 dl 1.15 * <p>The returned set will throw an {@code IllegalArgumentException}
241 jsr166 1.9 * on an attempt to insert an element outside its range.
242     *
243 dl 1.15 * @param fromElement low endpoint of the returned set
244 jsr166 1.21 * @param inclusive {@code true} if the low endpoint
245     * is to be included in the returned view
246 jsr166 1.9 * @return a view of the portion of this set whose elements are greater
247 dl 1.15 * than or equal to {@code fromElement}
248     * @throws ClassCastException if {@code fromElement} is not compatible
249 jsr166 1.9 * with this set's comparator (or, if the set has no comparator,
250 dl 1.15 * if {@code fromElement} does not implement {@link Comparable}).
251 jsr166 1.9 * Implementations may, but are not required to, throw this
252 dl 1.15 * exception if {@code fromElement} cannot be compared to elements
253 jsr166 1.9 * currently in the set.
254 dl 1.15 * @throws NullPointerException if {@code fromElement} is null
255 jsr166 1.9 * and this set does not permit null elements
256     * @throws IllegalArgumentException if this set itself has a
257 dl 1.15 * restricted range, and {@code fromElement} lies outside the
258 jsr166 1.9 * bounds of the range
259 dl 1.1 */
260 dl 1.16 NavigableSet<E> tailSet(E fromElement, boolean inclusive);
261 jsr166 1.21
262     /**
263 jsr166 1.23 * {@inheritDoc}
264 jsr166 1.21 *
265 jsr166 1.23 * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
266 jsr166 1.21 *
267     * @throws ClassCastException {@inheritDoc}
268     * @throws NullPointerException {@inheritDoc}
269     * @throws IllegalArgumentException {@inheritDoc}
270     */
271     SortedSet<E> subSet(E fromElement, E toElement);
272    
273     /**
274 jsr166 1.23 * {@inheritDoc}
275 jsr166 1.21 *
276 jsr166 1.23 * <p>Equivalent to {@code headSet(toElement, false)}.
277 jsr166 1.21 *
278     * @throws ClassCastException {@inheritDoc}
279     * @throws NullPointerException {@inheritDoc}
280     * @throws IllegalArgumentException {@inheritDoc}
281 jsr166 1.29 */
282 jsr166 1.21 SortedSet<E> headSet(E toElement);
283    
284     /**
285 jsr166 1.23 * {@inheritDoc}
286 jsr166 1.21 *
287 jsr166 1.23 * <p>Equivalent to {@code tailSet(fromElement, true)}.
288 jsr166 1.21 *
289     * @throws ClassCastException {@inheritDoc}
290     * @throws NullPointerException {@inheritDoc}
291     * @throws IllegalArgumentException {@inheritDoc}
292     */
293     SortedSet<E> tailSet(E fromElement);
294 dl 1.1 }