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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.28 - (view) (download)

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

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8