java/util/NavigableSet.java

/*
 * Written by Doug Lea and Josh Bloch with assistance from members of JCP
 * JSR-166 Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package java.util;

/**
 * A {@link SortedSet} extended with navigation methods reporting
 * closest matches for given search targets. Methods {@code lower},
 * {@code floor}, {@code ceiling}, and {@code higher} return elements
 * respectively less than, less than or equal, greater than or equal,
 * and greater than a given element, returning {@code null} if there
 * is no such element.  A {@code NavigableSet} may be accessed and
 * traversed in either ascending or descending order.  The {@code
 * descendingSet} method returns a view of the set with the senses of
 * all relational and directional methods inverted. The performance of
 * ascending operations and views is likely to be faster than that of
 * descending ones.  This interface additionally defines methods
 * {@code pollFirst} and {@code pollLast} that return and remove the
 * lowest and highest element, if one exists, else returning {@code
 * null}.  Methods {@code subSet}, {@code headSet},
 * and {@code tailSet} differ from the like-named {@code
 * SortedSet} methods in accepting additional arguments describing
 * whether lower and upper bounds are inclusive versus exclusive.
 * Subsets of any {@code NavigableSet} must implement the {@code
 * NavigableSet} interface.
 *
 * <p>The return values of navigation methods may be ambiguous in
 * implementations that permit {@code null} elements. However, even
 * in this case the result can be disambiguated by checking
 * {@code contains(null)}. To avoid such issues, implementations of
 * this interface are encouraged to <em>not</em> permit insertion of
 * {@code null} elements. (Note that sorted sets of {@link
 * Comparable} elements intrinsically do not permit {@code null}.)
 *
 * <p>Methods
 * {@link #subSet(Object, Object) subSet(E, E)},
 * {@link #headSet(Object) headSet(E)}, and
 * {@link #tailSet(Object) tailSet(E)}
 * are specified to return {@code SortedSet} to allow existing
 * implementations of {@code SortedSet} to be compatibly retrofitted to
 * implement {@code NavigableSet}, but extensions and implementations
 * of this interface are encouraged to override these methods to return
 * {@code NavigableSet}.
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @author Doug Lea
 * @author Josh Bloch
 * @param <E> the type of elements maintained by this set
 * @since 1.6
 */
public interface NavigableSet<E> extends SortedSet<E> {
    /**
     * Returns the greatest element in this set strictly less than the
     * given element, or {@code null} if there is no such element.
     *
     * @param e the value to match
     * @return the greatest element less than {@code e},
     *         or {@code null} if there is no such element
     * @throws ClassCastException if the specified element cannot be
     *         compared with the elements currently in the set
     * @throws NullPointerException if the specified element is null
     *         and this set does not permit null elements
     */
    E lower(E e);

    /**
     * Returns the greatest element in this set less than or equal to
     * the given element, or {@code null} if there is no such element.
     *
     * @param e the value to match
     * @return the greatest element less than or equal to {@code e},
     *         or {@code null} if there is no such element
     * @throws ClassCastException if the specified element cannot be
     *         compared with the elements currently in the set
     * @throws NullPointerException if the specified element is null
     *         and this set does not permit null elements
     */
    E floor(E e);

    /**
     * Returns the least element in this set greater than or equal to
     * the given element, or {@code null} if there is no such element.
     *
     * @param e the value to match
     * @return the least element greater than or equal to {@code e},
     *         or {@code null} if there is no such element
     * @throws ClassCastException if the specified element cannot be
     *         compared with the elements currently in the set
     * @throws NullPointerException if the specified element is null
     *         and this set does not permit null elements
     */
    E ceiling(E e);

    /**
     * Returns the least element in this set strictly greater than the
     * given element, or {@code null} if there is no such element.
     *
     * @param e the value to match
     * @return the least element greater than {@code e},
     *         or {@code null} if there is no such element
     * @throws ClassCastException if the specified element cannot be
     *         compared with the elements currently in the set
     * @throws NullPointerException if the specified element is null
     *         and this set does not permit null elements
     */
    E higher(E e);

    /**
     * Retrieves and removes the first (lowest) element,
     * or returns {@code null} if this set is empty.
     *
     * @return the first element, or {@code null} if this set is empty
     */
    E pollFirst();

    /**
     * Retrieves and removes the last (highest) element,
     * or returns {@code null} if this set is empty.
     *
     * @return the last element, or {@code null} if this set is empty
     */
    E pollLast();

    /**
     * Returns an iterator over the elements in this set, in ascending order.
     *
     * @return an iterator over the elements in this set, in ascending order
     */
    Iterator<E> iterator();

    /**
     * Returns a reverse order view of the elements contained in this set.
     * The descending set is backed by this set, so changes to the set are
     * reflected in the descending set, and vice-versa.  If either set is
     * modified while an iteration over either set is in progress (except
     * through the iterator's own {@code remove} operation), the results of
     * the iteration are undefined.
     *
     * <p>The returned set has an ordering equivalent to
     * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
     * The expression {@code s.descendingSet().descendingSet()} returns a
     * view of {@code s} essentially equivalent to {@code s}.
     *
     * @return a reverse order view of this set
     */
    NavigableSet<E> descendingSet();

    /**
     * Returns an iterator over the elements in this set, in descending order.
     * Equivalent in effect to {@code descendingSet().iterator()}.
     *
     * @return an iterator over the elements in this set, in descending order
     */
    Iterator<E> descendingIterator();

    /**
     * Returns a view of the portion of this set whose elements range from
     * {@code fromElement} to {@code toElement}.  If {@code fromElement} and
     * {@code toElement} are equal, the returned set is empty unless {@code
     * fromInclusive} and {@code toInclusive} are both true.  The returned set
     * is backed by this set, so changes in the returned set are reflected in
     * this set, and vice-versa.  The returned set supports all optional set
     * operations that this set supports.
     *
     * <p>The returned set will throw an {@code IllegalArgumentException}
     * on an attempt to insert an element outside its range.
     *
     * @param fromElement low endpoint of the returned set
     * @param fromInclusive {@code true} if the low endpoint
     *        is to be included in the returned view
     * @param toElement high endpoint of the returned set
     * @param toInclusive {@code true} if the high endpoint
     *        is to be included in the returned view
     * @return a view of the portion of this set whose elements range from
     *         {@code fromElement}, inclusive, to {@code toElement}, exclusive
     * @throws ClassCastException if {@code fromElement} and
     *         {@code toElement} cannot be compared to one another using this
     *         set's comparator (or, if the set has no comparator, using
     *         natural ordering).  Implementations may, but are not required
     *         to, throw this exception if {@code fromElement} or
     *         {@code toElement} cannot be compared to elements currently in
     *         the set.
     * @throws NullPointerException if {@code fromElement} or
     *         {@code toElement} is null and this set does
     *         not permit null elements
     * @throws IllegalArgumentException if {@code fromElement} is
     *         greater than {@code toElement}; or if this set itself
     *         has a restricted range, and {@code fromElement} or
     *         {@code toElement} lies outside the bounds of the range.
     */
    NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
                           E toElement,   boolean toInclusive);

    /**
     * Returns a view of the portion of this set whose elements are less than
     * (or equal to, if {@code inclusive} is true) {@code toElement}.  The
     * returned set is backed by this set, so changes in the returned set are
     * reflected in this set, and vice-versa.  The returned set supports all
     * optional set operations that this set supports.
     *
     * <p>The returned set will throw an {@code IllegalArgumentException}
     * on an attempt to insert an element outside its range.
     *
     * @param toElement high endpoint of the returned set
     * @param inclusive {@code true} if the high endpoint
     *        is to be included in the returned view
     * @return a view of the portion of this set whose elements are less than
     *         (or equal to, if {@code inclusive} is true) {@code toElement}
     * @throws ClassCastException if {@code toElement} is not compatible
     *         with this set's comparator (or, if the set has no comparator,
     *         if {@code toElement} does not implement {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if {@code toElement} cannot be compared to elements
     *         currently in the set.
     * @throws NullPointerException if {@code toElement} is null and
     *         this set does not permit null elements
     * @throws IllegalArgumentException if this set itself has a
     *         restricted range, and {@code toElement} lies outside the
     *         bounds of the range
     */
    NavigableSet<E> headSet(E toElement, boolean inclusive);

    /**
     * Returns a view of the portion of this set whose elements are greater
     * than (or equal to, if {@code inclusive} is true) {@code fromElement}.
     * The returned set is backed by this set, so changes in the returned set
     * are reflected in this set, and vice-versa.  The returned set supports
     * all optional set operations that this set supports.
     *
     * <p>The returned set will throw an {@code IllegalArgumentException}
     * on an attempt to insert an element outside its range.
     *
     * @param fromElement low endpoint of the returned set
     * @param inclusive {@code true} if the low endpoint
     *        is to be included in the returned view
     * @return a view of the portion of this set whose elements are greater
     *         than or equal to {@code fromElement}
     * @throws ClassCastException if {@code fromElement} is not compatible
     *         with this set's comparator (or, if the set has no comparator,
     *         if {@code fromElement} does not implement {@link Comparable}).
     *         Implementations may, but are not required to, throw this
     *         exception if {@code fromElement} cannot be compared to elements
     *         currently in the set.
     * @throws NullPointerException if {@code fromElement} is null
     *         and this set does not permit null elements
     * @throws IllegalArgumentException if this set itself has a
     *         restricted range, and {@code fromElement} lies outside the
     *         bounds of the range
     */
    NavigableSet<E> tailSet(E fromElement, boolean inclusive);

    /**
     * {@inheritDoc}
     *
     * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    SortedSet<E> subSet(E fromElement, E toElement);

    /**
     * {@inheritDoc}
     *
     * <p>Equivalent to {@code headSet(toElement, false)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    SortedSet<E> headSet(E toElement);

    /**
     * {@inheritDoc}
     *
     * <p>Equivalent to {@code tailSet(fromElement, true)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    SortedSet<E> tailSet(E fromElement);
}
Revision:	1.4
Committed:	Sun Sep 6 04:29:42 2015 UTC (8 years, 7 months ago) by jsr166
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.3:	+1 -1 lines
Log Message:	merge 6828204: NavigableSet.subSet() documentation refers to nonexistent parameters
#	Content
1	/*
2	* 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	* http://creativecommons.org/publicdomain/zero/1.0/
5	*/
6
7	package java.util;
8
9	/**
10	* A {@link SortedSet} extended with navigation methods reporting
11	* closest matches for given search targets. Methods {@code lower},
12	* {@code floor}, {@code ceiling}, and {@code higher} return elements
13	* respectively less than, less than or equal, greater than or equal,
14	* 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	* {@code pollFirst} and {@code pollLast} that return and remove the
22	* lowest and highest element, if one exists, else returning {@code
23	* null}. Methods {@code subSet}, {@code headSet},
24	* and {@code tailSet} differ from the like-named {@code
25	* 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	*
30	* <p>The return values of navigation methods may be ambiguous in
31	* implementations that permit {@code null} elements. However, even
32	* in this case the result can be disambiguated by checking
33	* {@code contains(null)}. To avoid such issues, implementations of
34	* this interface are encouraged to <em>not</em> permit insertion of
35	* {@code null} elements. (Note that sorted sets of {@link
36	* 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
49	* <a href="{@docRoot}/../technotes/guides/collections/index.html">
50	* Java Collections Framework</a>.
51	*
52	* @author Doug Lea
53	* @author Josh Bloch
54	* @param <E> the type of elements maintained by this set
55	* @since 1.6
56	*/
57	public interface NavigableSet<E> extends SortedSet<E> {
58	/**
59	* Returns the greatest element in this set strictly less than the
60	* given element, or {@code null} if there is no such element.
61	*
62	* @param e the value to match
63	* @return the greatest element less than {@code e},
64	* or {@code null} if there is no such element
65	* @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	*/
70	E lower(E e);
71
72	/**
73	* Returns the greatest element in this set less than or equal to
74	* the given element, or {@code null} if there is no such element.
75	*
76	* @param e the value to match
77	* @return the greatest element less than or equal to {@code e},
78	* or {@code null} if there is no such element
79	* @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	*/
84	E floor(E e);
85
86	/**
87	* Returns the least element in this set greater than or equal to
88	* the given element, or {@code null} if there is no such element.
89	*
90	* @param e the value to match
91	* @return the least element greater than or equal to {@code e},
92	* or {@code null} if there is no such element
93	* @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	*/
98	E ceiling(E e);
99
100	/**
101	* Returns the least element in this set strictly greater than the
102	* given element, or {@code null} if there is no such element.
103	*
104	* @param e the value to match
105	* @return the least element greater than {@code e},
106	* or {@code null} if there is no such element
107	* @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	*/
112	E higher(E e);
113
114	/**
115	* Retrieves and removes the first (lowest) element,
116	* or returns {@code null} if this set is empty.
117	*
118	* @return the first element, or {@code null} if this set is empty
119	*/
120	E pollFirst();
121
122	/**
123	* Retrieves and removes the last (highest) element,
124	* or returns {@code null} if this set is empty.
125	*
126	* @return the last element, or {@code null} if this set is empty
127	*/
128	E pollLast();
129
130	/**
131	* Returns an iterator over the elements in this set, in ascending order.
132	*
133	* @return an iterator over the elements in this set, in ascending order
134	*/
135	Iterator<E> iterator();
136
137	/**
138	* 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	* {@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 reverse order view of this set
151	*/
152	NavigableSet<E> descendingSet();
153
154	/**
155	* Returns an iterator over the elements in this set, in descending order.
156	* Equivalent in effect to {@code descendingSet().iterator()}.
157	*
158	* @return an iterator over the elements in this set, in descending order
159	*/
160	Iterator<E> descendingIterator();
161
162	/**
163	* 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	* fromInclusive} and {@code toInclusive} 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	*
171	* <p>The returned set will throw an {@code IllegalArgumentException}
172	* on an attempt to insert an element outside its range.
173	*
174	* @param fromElement low endpoint of the returned set
175	* @param fromInclusive {@code true} if the low endpoint
176	* is to be included in the returned view
177	* @param toElement high endpoint of the returned set
178	* @param toInclusive {@code true} if the high endpoint
179	* is to be included in the returned view
180	* @return a view of the portion of this set whose elements range from
181	* {@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	* set's comparator (or, if the set has no comparator, using
185	* natural ordering). Implementations may, but are not required
186	* to, throw this exception if {@code fromElement} or
187	* {@code toElement} cannot be compared to elements currently in
188	* the set.
189	* @throws NullPointerException if {@code fromElement} or
190	* {@code toElement} is null and this set does
191	* not permit null elements
192	* @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	NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
198	E toElement, boolean toInclusive);
199
200	/**
201	* 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	*
207	* <p>The returned set will throw an {@code IllegalArgumentException}
208	* on an attempt to insert an element outside its range.
209	*
210	* @param toElement high endpoint of the returned set
211	* @param inclusive {@code true} if the high endpoint
212	* is to be included in the returned view
213	* @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	* with this set's comparator (or, if the set has no comparator,
217	* if {@code toElement} does not implement {@link Comparable}).
218	* Implementations may, but are not required to, throw this
219	* exception if {@code toElement} cannot be compared to elements
220	* currently in the set.
221	* @throws NullPointerException if {@code toElement} is null and
222	* this set does not permit null elements
223	* @throws IllegalArgumentException if this set itself has a
224	* restricted range, and {@code toElement} lies outside the
225	* bounds of the range
226	*/
227	NavigableSet<E> headSet(E toElement, boolean inclusive);
228
229	/**
230	* 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	*
236	* <p>The returned set will throw an {@code IllegalArgumentException}
237	* on an attempt to insert an element outside its range.
238	*
239	* @param fromElement low endpoint of the returned set
240	* @param inclusive {@code true} if the low endpoint
241	* is to be included in the returned view
242	* @return a view of the portion of this set whose elements are greater
243	* than or equal to {@code fromElement}
244	* @throws ClassCastException if {@code fromElement} is not compatible
245	* with this set's comparator (or, if the set has no comparator,
246	* if {@code fromElement} does not implement {@link Comparable}).
247	* Implementations may, but are not required to, throw this
248	* exception if {@code fromElement} cannot be compared to elements
249	* currently in the set.
250	* @throws NullPointerException if {@code fromElement} is null
251	* and this set does not permit null elements
252	* @throws IllegalArgumentException if this set itself has a
253	* restricted range, and {@code fromElement} lies outside the
254	* bounds of the range
255	*/
256	NavigableSet<E> tailSet(E fromElement, boolean inclusive);
257
258	/**
259	* {@inheritDoc}
260	*
261	* <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
262	*
263	* @throws ClassCastException {@inheritDoc}
264	* @throws NullPointerException {@inheritDoc}
265	* @throws IllegalArgumentException {@inheritDoc}
266	*/
267	SortedSet<E> subSet(E fromElement, E toElement);
268
269	/**
270	* {@inheritDoc}
271	*
272	* <p>Equivalent to {@code headSet(toElement, false)}.
273	*
274	* @throws ClassCastException {@inheritDoc}
275	* @throws NullPointerException {@inheritDoc}
276	* @throws IllegalArgumentException {@inheritDoc}
277	*/
278	SortedSet<E> headSet(E toElement);
279
280	/**
281	* {@inheritDoc}
282	*
283	* <p>Equivalent to {@code tailSet(fromElement, true)}.
284	*
285	* @throws ClassCastException {@inheritDoc}
286	* @throws NullPointerException {@inheritDoc}
287	* @throws IllegalArgumentException {@inheritDoc}
288	*/
289	SortedSet<E> tailSet(E fromElement);
290	}