ViewVC Help

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

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

Comparing jsr166/src/main/java/util/NavigableMap.java (file contents):
Revision 1.1 by dl, Tue Dec 28 12:14:07 2004 UTC vs.
Revision 1.9 by jsr166, Wed May 18 01:39:35 2005 UTC

#	Line 25 | Line 25 | package java.util;
25		* <tt>descendingEntrySet</tt> return descending views. The
26		* performance of ascending traversals is likely to be faster than
27		* descending traversals.  Notice that it is possible to perform
28	<	* subrannge traversals in either direction using <tt>SubMap</tt>.
29	<	*
28	>	* subrange traversals in either direction using <tt>navigableSubMap</tt>.
29	>	* Methods <tt>navigableSubMap</tt>, <tt>navigableHeadMap</tt>, and
30	>	* <tt>navigableTailMap</tt> differ from the similarly named
31	>	* <tt>SortedMap</tt> methods only in that the returned maps
32	>	* are guaranteed to obey the <tt>NavigableMap</tt> interface.
33	>	*
34		* <p>This interface additionally defines methods <tt>firstEntry</tt>,
35		* <tt>pollFirstEntry</tt>, <tt>lastEntry</tt>, and
36		* <tt>pollLastEntry</tt> that return and/or remove the least and
#	Line 39 | Line 43 | package java.util;
43		* that it is possible to change mappings in the associated map using
44		* method <tt>put</tt>.
45		*
46	+	* <p>This interface is a member of the
47	+	* <a href="{@docRoot}/../guide/collections/index.html">
48	+	* Java Collections Framework</a>.
49	+	*
50		* @author Doug Lea
51		* @param <K> the type of keys maintained by this map
52	<	* @param <V> the type of mapped values
52	>	* @param <V> the type of mapped values
53	>	* @since 1.6
54		*/
55		public interface NavigableMap<K,V> extends SortedMap<K,V> {
56		/**
57	<	* Returns a key-value mapping associated with the least key
58	<	* greater than or equal to the given key, or <tt>null</tt> if there is
59	<	* no such entry.
60	<	*
61	<	* @param key the key.
62	<	* @return an Entry associated with ceiling of given key, or <tt>null</tt>
63	<	* if there is no such Entry.
64	<	* @throws ClassCastException if key cannot be compared with the keys
65	<	*            currently in the map.
66	<	* @throws NullPointerException if key is <tt>null</tt> and this map
67	<	* does not support <tt>null</tt> keys.
57	>	* Returns a key-value mapping associated with the greatest key
58	>	* strictly less than the given key, or <tt>null</tt> if there is
59	>	* no such key.
60	>	*
61	>	* @param key the key
62	>	* @return an entry with the greatest key less than <tt>key</tt>,
63	>	*         or <tt>null</tt> if there is no such key
64	>	* @throws ClassCastException if the specified key cannot be compared
65	>	*         with the keys currently in the map
66	>	* @throws NullPointerException if the specified key is null
67	>	*         and this map does not permit null keys
68		*/
69	<	public Map.Entry<K,V> ceilingEntry(K key);
69	>	Map.Entry<K,V> lowerEntry(K key);
70
71		/**
72	<	* Returns least key greater than or equal to the given key, or
72	>	* Returns the greatest key strictly less than the given key, or
73		* <tt>null</tt> if there is no such key.
74	<	*
75	<	* @param key the key.
76	<	* @return the ceiling key, or <tt>null</tt>
77	<	* if there is no such key.
78	<	* @throws ClassCastException if key cannot be compared with the keys
79	<	*            currently in the map.
80	<	* @throws NullPointerException if key is <tt>null</tt> and this map
81	<	* does not support <tt>null</tt> keys.
74	>	*
75	>	* @param key the key
76	>	* @return the greatest key less than <tt>key</tt>,
77	>	*         or <tt>null</tt> if there is no such key
78	>	* @throws ClassCastException if the specified key cannot be compared
79	>	*         with the keys currently in the map
80	>	* @throws NullPointerException if the specified key is null
81	>	*         and this map does not permit null keys
82		*/
83	<	public K ceilingKey(K key);
83	>	K lowerKey(K key);
84
85		/**
86	<	* Returns a key-value mapping associated with the greatest
87	<	* key strictly less than the given key, or <tt>null</tt> if there is no
88	<	* such entry.
89	<	*
90	<	* @param key the key.
91	<	* @return an Entry with greatest key less than the given
92	<	* key, or <tt>null</tt> if there is no such Entry.
93	<	* @throws ClassCastException if key cannot be compared with the keys
94	<	*            currently in the map.
95	<	* @throws NullPointerException if key is <tt>null</tt> and this map
96	<	* does not support <tt>null</tt> keys.
86	>	* Returns a key-value mapping associated with the greatest key
87	>	* less than or equal to the given key, or <tt>null</tt> if there
88	>	* is no such key.
89	>	*
90	>	* @param key the key
91	>	* @return an entry with the greatest key less than or equal to
92	>	*         <tt>key</tt>, or <tt>null</tt> if there is no such key
93	>	* @throws ClassCastException if the specified key cannot be compared
94	>	*         with the keys currently in the map
95	>	* @throws NullPointerException if the specified key is null
96	>	*         and this map does not permit null keys
97		*/
98	<	public Map.Entry<K,V> lowerEntry(K key);
98	>	Map.Entry<K,V> floorEntry(K key);
99
100		/**
101	<	* Returns the greatest key strictly less than the given key, or
102	<	* <tt>null</tt> if there is no such key.
103	<	*
104	<	* @param key the key.
105	<	* @return the greatest key less than the given
106	<	* key, or <tt>null</tt> if there is no such key.
107	<	* @throws ClassCastException if key cannot be compared with the keys
108	<	*            currently in the map.
109	<	* @throws NullPointerException if key is <tt>null</tt> and this map
110	<	* does not support <tt>null</tt> keys.
101	>	* Returns the greatest key less than or equal to the given key,
102	>	* or <tt>null</tt> if there is no such key.
103	>	*
104	>	* @param key the key
105	>	* @return the greatest key less than or equal to <tt>key</tt>,
106	>	*         or <tt>null</tt> if there is no such key
107	>	* @throws ClassCastException if the specified key cannot be compared
108	>	*         with the keys currently in the map
109	>	* @throws NullPointerException if the specified key is null
110	>	*         and this map does not permit null keys
111		*/
112	<	public K lowerKey(K key);
112	>	K floorKey(K key);
113
114		/**
115	<	* Returns a key-value mapping associated with the greatest key
116	<	* less than or equal to the given key, or <tt>null</tt> if there
117	<	* is no such entry.
118	<	*
119	<	* @param key the key.
120	<	* @return an Entry associated with floor of given key, or <tt>null</tt>
121	<	* if there is no such Entry.
122	<	* @throws ClassCastException if key cannot be compared with the keys
123	<	*            currently in the map.
124	<	* @throws NullPointerException if key is <tt>null</tt> and this map
125	<	* does not support <tt>null</tt> keys.
115	>	* Returns a key-value mapping associated with the least key
116	>	* greater than or equal to the given key, or <tt>null</tt> if
117	>	* there is no such key.
118	>	*
119	>	* @param key the key
120	>	* @return an entry with the least key greater than or equal to
121	>	*         <tt>key</tt>, or <tt>null</tt> if there is no such key
122	>	* @throws ClassCastException if the specified key cannot be compared
123	>	*         with the keys currently in the map
124	>	* @throws NullPointerException if the specified key is null
125	>	*         and this map does not permit null keys
126		*/
127	<	public Map.Entry<K,V> floorEntry(K key);
127	>	Map.Entry<K,V> ceilingEntry(K key);
128
129		/**
130	<	* Returns the greatest key
131	<	* less than or equal to the given key, or <tt>null</tt> if there
132	<	* is no such key.
133	<	*
134	<	* @param key the key.
135	<	* @return the floor of given key, or <tt>null</tt> if there is no
136	<	* such key.
137	<	* @throws ClassCastException if key cannot be compared with the keys
138	<	*            currently in the map.
139	<	* @throws NullPointerException if key is <tt>null</tt> and this map
131	<	* does not support <tt>null</tt> keys.
130	>	* Returns the least key greater than or equal to the given key,
131	>	* or <tt>null</tt> if there is no such key.
132	>	*
133	>	* @param key the key
134	>	* @return the least key greater than or equal to <tt>key</tt>,
135	>	*         or <tt>null</tt> if there is no such key
136	>	* @throws ClassCastException if the specified key cannot be compared
137	>	*         with the keys currently in the map
138	>	* @throws NullPointerException if the specified key is null
139	>	*         and this map does not permit null keys
140		*/
141	<	public K floorKey(K key);
141	>	K ceilingKey(K key);
142
143		/**
144		* Returns a key-value mapping associated with the least key
145		* strictly greater than the given key, or <tt>null</tt> if there
146	<	* is no such entry.
147	<	*
148	<	* @param key the key.
149	<	* @return an Entry with least key greater than the given key, or
150	<	* <tt>null</tt> if there is no such Entry.
151	<	* @throws ClassCastException if key cannot be compared with the keys
152	<	*            currently in the map.
153	<	* @throws NullPointerException if key is <tt>null</tt> and this map
154	<	* does not support <tt>null</tt> keys.
146	>	* is no such key.
147	>	*
148	>	* @param key the key
149	>	* @return an entry with the least key greater than <tt>key</tt>,
150	>	*         or <tt>null</tt> if there is no such key
151	>	* @throws ClassCastException if the specified key cannot be compared
152	>	*         with the keys currently in the map
153	>	* @throws NullPointerException if the specified key is null
154	>	*         and this map does not permit null keys
155		*/
156	<	public Map.Entry<K,V> higherEntry(K key);
156	>	Map.Entry<K,V> higherEntry(K key);
157
158		/**
159		* Returns the least key strictly greater than the given key, or
160		* <tt>null</tt> if there is no such key.
161	<	*
162	<	* @param key the key.
163	<	* @return the least key greater than the given key, or
164	<	* <tt>null</tt> if there is no such key.
165	<	* @throws ClassCastException if key cannot be compared with the keys
166	<	*            currently in the map.
167	<	* @throws NullPointerException if key is <tt>null</tt> and this map
168	<	* does not support <tt>null</tt> keys.
161	>	*
162	>	* @param key the key
163	>	* @return the least key greater than <tt>key</tt>,
164	>	*         or <tt>null</tt> if there is no such key
165	>	* @throws ClassCastException if the specified key cannot be compared
166	>	*         with the keys currently in the map
167	>	* @throws NullPointerException if the specified key is null
168	>	*         and this map does not permit null keys
169		*/
170	<	public K higherKey(K key);
170	>	K higherKey(K key);
171
172		/**
173		* Returns a key-value mapping associated with the least
174		* key in this map, or <tt>null</tt> if the map is empty.
175	<	*
176	<	* @return an Entry with least key, or <tt>null</tt>
177	<	* if the map is empty.
175	>	*
176	>	* @return an entry with the least key,
177	>	*         or <tt>null</tt> if this map is empty
178		*/
179	<	public Map.Entry<K,V> firstEntry();
179	>	Map.Entry<K,V> firstEntry();
180
181		/**
182		* Returns a key-value mapping associated with the greatest
183		* key in this map, or <tt>null</tt> if the map is empty.
184	<	*
185	<	* @return an Entry with greatest key, or <tt>null</tt>
186	<	* if the map is empty.
184	>	*
185	>	* @return an entry with the greatest key,
186	>	*         or <tt>null</tt> if this map is empty
187		*/
188	<	public Map.Entry<K,V> lastEntry();
188	>	Map.Entry<K,V> lastEntry();
189
190		/**
191		* Removes and returns a key-value mapping associated with
192		* the least key in this map, or <tt>null</tt> if the map is empty.
193	<	*
194	<	* @return the removed first entry of this map, or <tt>null</tt>
195	<	* if the map is empty.
193	>	*
194	>	* @return the removed first entry of this map,
195	>	*         or <tt>null</tt> if this map is empty
196		*/
197	<	public Map.Entry<K,V> pollFirstEntry();
197	>	Map.Entry<K,V> pollFirstEntry();
198
199		/**
200		* Removes and returns a key-value mapping associated with
201		* the greatest key in this map, or <tt>null</tt> if the map is empty.
202	<	*
203	<	* @return the removed last entry of this map, or <tt>null</tt>
204	<	* if the map is empty.
205	<	*/
206	<	public Map.Entry<K,V> pollLastEntry();
207	<
208	<	/**
209	<	* Returns a set view of the keys contained in this map, in
210	<	* descending key order.  The set is backed by the map, so changes
211	<	* to the map are reflected in the set, and vice-versa.  If the
212	<	* map is modified while an iteration over the set is in progress
213	<	* (except through the iterator's own <tt>remove</tt> operation),
214	<	* the results of the iteration are undefined.  The set supports
215	<	* element removal, which removes the corresponding mapping from
216	<	* the map, via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
217	<	* <tt>removeAll</tt> <tt>retainAll</tt>, and <tt>clear</tt>
218	<	* operations.  It does not support the add or <tt>addAll</tt>
202	>	*
203	>	* @return the removed last entry of this map,
204	>	*         or <tt>null</tt> if this map is empty
205	>	*/
206	>	Map.Entry<K,V> pollLastEntry();
207	>
208	>	/**
209	>	* Returns a {@link Set} view of the keys contained in this map.
210	>	* The set's iterator returns the keys in descending order.
211	>	* The set is backed by the map, so changes to the map are
212	>	* reflected in the set, and vice-versa.  If the map is modified
213	>	* while an iteration over the set is in progress (except through
214	>	* the iterator's own <tt>remove</tt> operation), the results of
215	>	* the iteration are undefined.  The set supports element removal,
216	>	* which removes the corresponding mapping from the map, via the
217	>	* <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
218	>	* <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
219	>	* operations.  It does not support the <tt>add</tt> or <tt>addAll</tt>
220		* operations.
221		*
222	<	* @return a set view of the keys contained in this map.
222	>	* @return a set view of the keys contained in this map, sorted in
223	>	*         descending order
224		*/
225		Set<K> descendingKeySet();
226
227		/**
228	<	* Returns a set view of the mappings contained in this map, in
229	<	* descending key order.  Each element in the returned set is a
230	<	* <tt>Map.Entry</tt>.  The set is backed by the map, so changes to
231	<	* the map are reflected in the set, and vice-versa.  If the map
232	<	* is modified while an iteration over the set is in progress
233	<	* (except through the iterator's own <tt>remove</tt> operation,
234	<	* or through the <tt>setValue</tt> operation on a map entry
235	<	* returned by the iterator) the results of the iteration are
236	<	* undefined.  The set supports element removal, which removes the
237	<	* corresponding mapping from the map, via the
238	<	* <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
239	<	* <tt>removeAll</tt>, <tt>retainAll</tt> and <tt>clear</tt>
240	<	* operations.  It does not support the <tt>add</tt> or
231	<	* <tt>addAll</tt> operations.
228	>	* Returns a {@link Set} view of the mappings contained in this map.
229	>	* The set's iterator returns the entries in descending key order.
230	>	* The set is backed by the map, so changes to the map are
231	>	* reflected in the set, and vice-versa.  If the map is modified
232	>	* while an iteration over the set is in progress (except through
233	>	* the iterator's own <tt>remove</tt> operation, or through the
234	>	* <tt>setValue</tt> operation on a map entry returned by the
235	>	* iterator) the results of the iteration are undefined.  The set
236	>	* supports element removal, which removes the corresponding
237	>	* mapping from the map, via the <tt>Iterator.remove</tt>,
238	>	* <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
239	>	* <tt>clear</tt> operations.  It does not support the
240	>	* <tt>add</tt> or <tt>addAll</tt> operations.
241		*
242	<	* @return a set view of the mappings contained in this map.
242	>	* @return a set view of the mappings contained in this map,
243	>	*         sorted in descending key order
244		*/
245		Set<Map.Entry<K, V>> descendingEntrySet();
246
247		/**
248		* Returns a view of the portion of this map whose keys range from
249		* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.  (If
250	<	* <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned sorted map
251	<	* is empty.)  The returned sorted map is backed by this map, so changes
252	<	* in the returned sorted map are reflected in this map, and vice-versa.
253	<
254	<	* @param fromKey low endpoint (inclusive) of the subMap.
255	<	* @param toKey high endpoint (exclusive) of the subMap.
250	>	* <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned map
251	>	* is empty.)  The returned map is backed by this map, so changes
252	>	* in the returned map are reflected in this map, and vice-versa.
253	>	* The returned map supports all optional map operations that this
254	>	* map supports.
255	>	*
256	>	* <p>The returned map will throw an <tt>IllegalArgumentException</tt>
257	>	* on an attempt to insert a key outside its range.
258		*
259	+	* @param fromKey low endpoint (inclusive) of the keys in the returned map
260	+	* @param toKey high endpoint (exclusive) of the keys in the returned map
261		* @return a view of the portion of this map whose keys range from
262	<	* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.
262	>	*         <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive
263	>	* @throws ClassCastException if <tt>fromKey</tt> and <tt>toKey</tt>
264	>	*         cannot be compared to one another using this map's comparator
265	>	*         (or, if the map has no comparator, using natural ordering).
266	>	*         Implementations may, but are not required to, throw this
267	>	*         exception if <tt>fromKey</tt> or <tt>toKey</tt>
268	>	*         cannot be compared to keys currently in the map.
269	>	* @throws NullPointerException if <tt>fromKey</tt> or <tt>toKey</tt>
270	>	*         is null and this map does not permit null keys
271	>	* @throws IllegalArgumentException if <tt>fromKey</tt> is greater than
272	>	*         <tt>toKey</tt>; or if this map itself has a restricted
273	>	*         range, and <tt>fromKey</tt> or <tt>toKey</tt> lies
274	>	*         outside the bounds of the range
275	>	*/
276	>	NavigableMap<K,V> navigableSubMap(K fromKey, K toKey);
277	>
278	>	/**
279	>	* Returns a view of the portion of this map whose keys are
280	>	* strictly less than <tt>toKey</tt>.  The returned map is backed
281	>	* by this map, so changes in the returned map are reflected in
282	>	* this map, and vice-versa.  The returned map supports all
283	>	* optional map operations that this map supports.
284		*
285	<	* @throws ClassCastException if <tt>fromKey</tt> and
286	<	* <tt>toKey</tt> cannot be compared to one another using this
252	<	* map's comparator (or, if the map has no comparator, using
253	<	* natural ordering).
254	<	* @throws IllegalArgumentException if <tt>fromKey</tt> is greater
255	<	* than <tt>toKey</tt>.
256	<	* @throws NullPointerException if <tt>fromKey</tt> or
257	<	* <tt>toKey</tt> is <tt>null</tt> and this map does not support
258	<	* <tt>null</tt> keys.
259	<	*/
260	<	public NavigableMap<K,V> subMap(K fromKey, K toKey);
261	<
262	<	/**
263	<	* Returns a view of the portion of this map whose keys are strictly less
264	<	* than <tt>toKey</tt>.  The returned sorted map is backed by this map, so
265	<	* changes in the returned sorted map are reflected in this map, and
266	<	* vice-versa.
267	<	* @param toKey high endpoint (exclusive) of the headMap.
268	<	* @return a view of the portion of this map whose keys are strictly
269	<	*                less than <tt>toKey</tt>.
285	>	* <p>The returned map will throw an <tt>IllegalArgumentException</tt>
286	>	* on an attempt to insert a key outside its range.
287		*
288	+	* @param toKey high endpoint (exclusive) of the keys in the returned map
289	+	* @return a view of the portion of this map whose keys are strictly
290	+	*         less than <tt>toKey</tt>
291		* @throws ClassCastException if <tt>toKey</tt> is not compatible
292		*         with this map's comparator (or, if the map has no comparator,
293	<	*         if <tt>toKey</tt> does not implement <tt>Comparable</tt>).
294	<	* @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>
295	<	* and this map does not support <tt>null</tt> keys.
293	>	*         if <tt>toKey</tt> does not implement {@link Comparable}).
294	>	*         Implementations may, but are not required to, throw this
295	>	*         exception if <tt>toKey</tt> cannot be compared to keys
296	>	*         currently in the map.
297	>	* @throws NullPointerException if <tt>toKey</tt> is null
298	>	*         and this map does not permit null keys
299	>	* @throws IllegalArgumentException if this map itself has a
300	>	*         restricted range, and <tt>toKey</tt> lies outside the
301	>	*         bounds of the range
302		*/
303	<	public NavigableMap<K,V> headMap(K toKey);
303	>	NavigableMap<K,V> navigableHeadMap(K toKey);
304
305		/**
306		* Returns a view of the portion of this map whose keys are
307	<	* greater than or equal to <tt>fromKey</tt>.  The returned sorted
308	<	* map is backed by this map, so changes in the returned sorted
309	<	* map are reflected in this map, and vice-versa.
310	<	* @param fromKey low endpoint (inclusive) of the tailMap.
307	>	* greater than or equal to <tt>fromKey</tt>.  The returned map is
308	>	* backed by this map, so changes in the returned map are
309	>	* reflected in this map, and vice-versa.  The returned map
310	>	* supports all optional map operations that this map supports.
311	>	*
312	>	* <p>The returned map will throw an <tt>IllegalArgumentException</tt>
313	>	* on an attempt to insert a key outside its range.
314	>	*
315	>	* @param fromKey low endpoint (inclusive) of the keys in the returned map
316		* @return a view of the portion of this map whose keys are greater
317	<	*                than or equal to <tt>fromKey</tt>.
317	>	*         than or equal to <tt>fromKey</tt>
318		* @throws ClassCastException if <tt>fromKey</tt> is not compatible
319		*         with this map's comparator (or, if the map has no comparator,
320	<	*         if <tt>fromKey</tt> does not implement <tt>Comparable</tt>).
321	<	* @throws NullPointerException if <tt>fromKey</tt> is <tt>null</tt>
322	<	* and this map does not support <tt>null</tt> keys.
320	>	*         if <tt>fromKey</tt> does not implement {@link Comparable}).
321	>	*         Implementations may, but are not required to, throw this
322	>	*         exception if <tt>fromKey</tt> cannot be compared to keys
323	>	*         currently in the map.
324	>	* @throws NullPointerException if <tt>fromKey</tt> is null
325	>	*         and this map does not permit null keys
326	>	* @throws IllegalArgumentException if this map itself has a
327	>	*         restricted range, and <tt>fromKey</tt> lies outside the
328	>	*         bounds of the range
329		*/
330	<	public NavigableMap<K,V>  tailMap(K fromKey);
330	>	NavigableMap<K,V> navigableTailMap(K fromKey);
331		}

Diff Legend

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