ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/NavigableSet.java

Comparing jsr166/src/main/java/util/NavigableSet.java (file contents):
Revision 1.7 by jsr166, Mon May 2 22:34:56 2005 UTC vs.
Revision 1.31 by jsr166, Wed Sep 30 19:14:05 2015 UTC

#	Line 1 | Line 1
1		/*
2	<	* Written by Doug Lea with assistance from members of JCP JSR-166
3	<	* Expert Group and released to the public domain, as explained at
4	<	* http://creativecommons.org/licenses/publicdomain
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 <tt>lower</tt>,
12	<	* <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return keys
11	>	* closest matches for given search targets. Methods {@link #lower},
12	>	* {@link #floor}, {@link #ceiling}, and {@link #higher} return elements
13		* respectively less than, less than or equal, greater than or equal,
14	<	* and greater than a given key, returning <tt>null</tt> if there is
15	<	* no such key.  A <tt>NavigableSet</tt> may be viewed and traversed
16	<	* in either ascending or descending order.  The <tt>Collection</tt>
17	<	* <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and
18	<	* the additional method <tt>descendingIterator</tt> returns
19	<	* descending iterator. The performance of ascending traversals is
20	<	* likely to be faster than descending traversals.  This interface
21	<	* additionally defines methods <tt>pollFirst</tt> and
22	<	* <t>pollLast</tt> that return and remove the lowest and highest key,
23	<	* if one exists, else returning <tt>null</tt>.
24	<	* Methods <tt>navigableSubSet</tt>, <tt>navigableHeadSet</tt>, and
25	<	* <tt>navigableTailSet</tt> differ from the similarly named
26	<	* <tt>SortedSet</tt> methods only in that the returned sets
27	<	* are guaranteed to obey the <tt>NavigableSet</tt> interface.
14	>	* and greater than a given element, returning {@code null} if there
15	>	* is no such element.
16		*
17	<	* <p> The return values of navigation methods may be ambiguous in
18	<	* implementations that permit <tt>null</tt> elements. However, even
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	>	*
34	>	* <p>The return values of navigation methods may be ambiguous in
35	>	* implementations that permit {@code null} elements. However, even
36		* in this case the result can be disambiguated by checking
37	<	* <tt>contains(null)</tt>. To avoid such issues, implementations of
38	<	* this interface are encouraged <em>not</em> to permit insertion of
39	<	* <tt>null</tt> elements. (Note that sorted sets of {@link
40	<	* Comparable} elements intrinsically do not permit <tt>null</tt>.)
37	>	* {@code contains(null)}. To avoid such issues, implementations of
38	>	* this interface are encouraged to <em>not</em> permit insertion of
39	>	* {@code null} elements. (Note that sorted sets of {@link
40	>	* Comparable} elements intrinsically do not permit {@code null}.)
41	>	*
42	>	* <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	>	*
52	>	* <p>This interface is a member of the
53	>	* <a href="{@docRoot}/../technotes/guides/collections/index.html">
54	>	* Java Collections Framework</a>.
55		*
56		* @author Doug Lea
57	+	* @author Josh Bloch
58		* @param <E> the type of elements maintained by this set
59		* @since 1.6
60		*/
61		public interface NavigableSet<E> extends SortedSet<E> {
62		/**
63	<	* Returns an element greater than or equal to the given element, or
64	<	* <tt>null</tt> if there is no such element.
63	>	* Returns the greatest element in this set strictly less than the
64	>	* given element, or {@code null} if there is no such element.
65		*
66		* @param e the value to match
67	<	* @return an element greater than or equal to given element, or
68	<	* <tt>null</tt> if there is no such element.
69	<	* @throws ClassCastException if e cannot be compared with the elements
70	<	*            currently in the set.
71	<	* @throws NullPointerException if e is <tt>null</tt>
72	<	* and this set does not permit <tt>null</tt> elements
67	>	* @return the greatest element less than {@code e},
68	>	*         or {@code null} if there is no such element
69	>	* @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		*/
74	<	E ceiling(E e);
74	>	E lower(E e);
75
76		/**
77	<	* Returns an element strictly less than the given element, or
78	<	* <tt>null</tt> if there is no such element.
77	>	* Returns the greatest element in this set less than or equal to
78	>	* the given element, or {@code null} if there is no such element.
79		*
80		* @param e the value to match
81	<	* @return the greatest element less than the given element, or
82	<	* <tt>null</tt> if there is no such element.
83	<	* @throws ClassCastException if e cannot be compared with the elements
84	<	*            currently in the set.
85	<	* @throws NullPointerException if e is <tt>null</tt>
86	<	* and this set does not permit <tt>null</tt> elements
81	>	* @return the greatest element less than or equal to {@code e},
82	>	*         or {@code null} if there is no such element
83	>	* @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		*/
88	<	E lower(E e);
88	>	E floor(E e);
89
90		/**
91	<	* Returns an element less than or equal to the given element, or
92	<	* <tt>null</tt> if there is no such element.
91	>	* Returns the least element in this set greater than or equal to
92	>	* the given element, or {@code null} if there is no such element.
93		*
94		* @param e the value to match
95	<	* @return the greatest element less than or equal to given
96	<	* element, or <tt>null</tt> if there is no such element.
97	<	* @throws ClassCastException if e cannot be compared with the elements
98	<	*            currently in the set.
99	<	* @throws NullPointerException if e is <tt>null</tt>.
100	<	* and this set does not permit <tt>null</tt> elements
95	>	* @return the least element greater than or equal to {@code e},
96	>	*         or {@code null} if there is no such element
97	>	* @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		*/
102	<	E floor(E e);
102	>	E ceiling(E e);
103
104		/**
105	<	* Returns an element strictly greater than the given element, or
106	<	* <tt>null</tt> if there is no such element.
105	>	* Returns the least element in this set strictly greater than the
106	>	* given element, or {@code null} if there is no such element.
107		*
108		* @param e the value to match
109	<	* @return the least element greater than the given element, or
110	<	* <tt>null</tt> if there is no such element.
111	<	* @throws ClassCastException if e cannot be compared with the elements
112	<	*            currently in the set.
113	<	* @throws NullPointerException if e is <tt>null</tt>
114	<	* and this set does not permit <tt>null</tt> elements
109	>	* @return the least element greater than {@code e},
110	>	*         or {@code null} if there is no such element
111	>	* @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		*/
116		E higher(E e);
117
118		/**
119	<	* Retrieves and removes the first (lowest) element.
119	>	* Retrieves and removes the first (lowest) element,
120	>	* or returns {@code null} if this set is empty.
121		*
122	<	* @return the first element, or <tt>null</tt> if empty.
122	>	* @return the first element, or {@code null} if this set is empty
123		*/
124		E pollFirst();
125
126		/**
127	<	* Retrieves and removes the last (highest) element.
127	>	* Retrieves and removes the last (highest) element,
128	>	* or returns {@code null} if this set is empty.
129		*
130	<	* @return the last element, or <tt>null</tt> if empty.
130	>	* @return the last element, or {@code null} if this set is empty
131		*/
132		E pollLast();
133
134		/**
135	<	* Returns an iterator over the elements in this collection, in
114	<	* descending order.
135	>	* Returns an iterator over the elements in this set, in ascending order.
136		*
137	<	* @return an <tt>Iterator</tt> over the elements in this collection
137	>	* @return an iterator over the elements in this set, in ascending order
138	>	*/
139	>	Iterator<E> iterator();
140	>
141	>	/**
142	>	* 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	>	* {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
151	>	* The expression {@code s.descendingSet().descendingSet()} returns a
152	>	* view of {@code s} essentially equivalent to {@code s}.
153	>	*
154	>	* @return a reverse order view of this set
155	>	*/
156	>	NavigableSet<E> descendingSet();
157	>
158	>	/**
159	>	* Returns an iterator over the elements in this set, in descending order.
160	>	* Equivalent in effect to {@code descendingSet().iterator()}.
161	>	*
162	>	* @return an iterator over the elements in this set, in descending order
163		*/
164		Iterator<E> descendingIterator();
165
166		/**
167	<	* Returns a view of the portion of this set whose elements range
168	<	* from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
169	<	* exclusive.  (If <tt>fromElement</tt> and <tt>toElement</tt> are
170	<	* equal, the returned navigable set is empty.)  The returned
171	<	* navigable set is backed by this set, so changes in the returned
172	<	* navigable set are reflected in this set, and vice-versa.
167	>	* 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	>	* fromInclusive} and {@code toInclusive} are both true.  The returned set
171	>	* 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		*
175	<	* @param fromElement low endpoint (inclusive) of the subSet.
176	<	* @param toElement high endpoint (exclusive) of the subSet.
175	>	* <p>The returned set will throw an {@code IllegalArgumentException}
176	>	* on an attempt to insert an element outside its range.
177	>	*
178	>	* @param fromElement low endpoint of the returned set
179	>	* @param fromInclusive {@code true} if the low endpoint
180	>	*        is to be included in the returned view
181	>	* @param toElement high endpoint of the returned set
182	>	* @param toInclusive {@code true} if the high endpoint
183	>	*        is to be included in the returned view
184		* @return a view of the portion of this set whose elements range from
185	<	*         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
186	<	*         exclusive.
187	<	* @throws ClassCastException if <tt>fromElement</tt> and
188	<	*         <tt>toElement</tt> cannot be compared to one another using
189	<	*         this set's comparator (or, if the set has no comparator,
190	<	*         using natural ordering).
191	<	* @throws IllegalArgumentException if <tt>fromElement</tt> is
192	<	* greater than <tt>toElement</tt>.
193	<	* @throws NullPointerException if <tt>fromElement</tt> or
194	<	*         <tt>toElement</tt> is <tt>null</tt>
195	<	* and this set does not permit <tt>null</tt> elements
196	<	*/
197	<	NavigableSet<E> navigableSubSet(E fromElement, E toElement);
198	<
199	<	/**
200	<	* Returns a view of the portion of this set whose elements are
201	<	* strictly less than <tt>toElement</tt>.  The returned navigable
202	<	* set is backed by this set, so changes in the returned navigable
203	<	* set are reflected in this set, and vice-versa.
204	<	* @param toElement high endpoint (exclusive) of the headSet.
205	<	* @return a view of the portion of this set whose elements are strictly
206	<	*         less than toElement.
207	<	* @throws ClassCastException if <tt>toElement</tt> is not compatible
185	>	*         {@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	>	*         set's comparator (or, if the set has no comparator, using
189	>	*         natural ordering).  Implementations may, but are not required
190	>	*         to, throw this exception if {@code fromElement} or
191	>	*         {@code toElement} cannot be compared to elements currently in
192	>	*         the set.
193	>	* @throws NullPointerException if {@code fromElement} or
194	>	*         {@code toElement} is null and this set does
195	>	*         not permit null elements
196	>	* @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	>	NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
202	>	E toElement,   boolean toInclusive);
203	>
204	>	/**
205	>	* 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	>	*
211	>	* <p>The returned set will throw an {@code IllegalArgumentException}
212	>	* on an attempt to insert an element outside its range.
213	>	*
214	>	* @param toElement high endpoint of the returned set
215	>	* @param inclusive {@code true} if the high endpoint
216	>	*        is to be included in the returned view
217	>	* @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		*         with this set's comparator (or, if the set has no comparator,
221	<	*         if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
222	<	* @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt>
223	<	* and this set does not permit <tt>null</tt> elements
224	<	*/
225	<	NavigableSet<E> navigableHeadSet(E toElement);
226	<
227	<	/**
228	<	* Returns a view of the portion of this set whose elements are
229	<	* greater than or equal to <tt>fromElement</tt>.  The returned
230	<	* navigable set is backed by this set, so changes in the returned
231	<	* navigable set are reflected in this set, and vice-versa.
232	<	* @param fromElement low endpoint (inclusive) of the tailSet.
233	<	* @return a view of the portion of this set whose elements are
234	<	* greater than or equal to <tt>fromElement</tt>.
235	<	* @throws ClassCastException if <tt>fromElement</tt> is not
236	<	* compatible with this set's comparator (or, if the set has no
237	<	* comparator, if <tt>fromElement</tt> does not implement
238	<	* <tt>Comparable</tt>).
239	<	* @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
240	<	* and this set does not permit <tt>null</tt> elements
221	>	*         if {@code toElement} does not implement {@link Comparable}).
222	>	*         Implementations may, but are not required to, throw this
223	>	*         exception if {@code toElement} cannot be compared to elements
224	>	*         currently in the set.
225	>	* @throws NullPointerException if {@code toElement} is null and
226	>	*         this set does not permit null elements
227	>	* @throws IllegalArgumentException if this set itself has a
228	>	*         restricted range, and {@code toElement} lies outside the
229	>	*         bounds of the range
230	>	*/
231	>	NavigableSet<E> headSet(E toElement, boolean inclusive);
232	>
233	>	/**
234	>	* 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	>	*
240	>	* <p>The returned set will throw an {@code IllegalArgumentException}
241	>	* on an attempt to insert an element outside its range.
242	>	*
243	>	* @param fromElement low endpoint of the returned set
244	>	* @param inclusive {@code true} if the low endpoint
245	>	*        is to be included in the returned view
246	>	* @return a view of the portion of this set whose elements are greater
247	>	*         than or equal to {@code fromElement}
248	>	* @throws ClassCastException if {@code fromElement} is not compatible
249	>	*         with this set's comparator (or, if the set has no comparator,
250	>	*         if {@code fromElement} does not implement {@link Comparable}).
251	>	*         Implementations may, but are not required to, throw this
252	>	*         exception if {@code fromElement} cannot be compared to elements
253	>	*         currently in the set.
254	>	* @throws NullPointerException if {@code fromElement} is null
255	>	*         and this set does not permit null elements
256	>	* @throws IllegalArgumentException if this set itself has a
257	>	*         restricted range, and {@code fromElement} lies outside the
258	>	*         bounds of the range
259	>	*/
260	>	NavigableSet<E> tailSet(E fromElement, boolean inclusive);
261	>
262	>	/**
263	>	* {@inheritDoc}
264	>	*
265	>	* <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
266	>	*
267	>	* @throws ClassCastException       {@inheritDoc}
268	>	* @throws NullPointerException     {@inheritDoc}
269	>	* @throws IllegalArgumentException {@inheritDoc}
270	>	*/
271	>	SortedSet<E> subSet(E fromElement, E toElement);
272	>
273	>	/**
274	>	* {@inheritDoc}
275	>	*
276	>	* <p>Equivalent to {@code headSet(toElement, false)}.
277	>	*
278	>	* @throws ClassCastException       {@inheritDoc}
279	>	* @throws NullPointerException     {@inheritDoc}
280	>	* @throws IllegalArgumentException {@inheritDoc}
281	>	*/
282	>	SortedSet<E> headSet(E toElement);
283	>
284	>	/**
285	>	* {@inheritDoc}
286	>	*
287	>	* <p>Equivalent to {@code tailSet(fromElement, true)}.
288	>	*
289	>	* @throws ClassCastException       {@inheritDoc}
290	>	* @throws NullPointerException     {@inheritDoc}
291	>	* @throws IllegalArgumentException {@inheritDoc}
292		*/
293	<	NavigableSet<E> navigableTailSet(E fromElement);
293	>	SortedSet<E> tailSet(E fromElement);
294		}

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines