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.31 by jsr166, Sat May 6 06:49:46 2017 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;
#	Line 9 | Line 9 | package java.util;
9		/**
10		* A {@link SortedMap} extended with navigation methods returning the
11		* closest matches for given search targets. Methods
12	<	* <tt>lowerEntry</tt>, <tt>floorEntry</tt>, <tt>ceilingEntry</tt>,
13	<	* and <tt>higherEntry</tt> return <tt>Map.Entry</tt> objects
12	>	* {@link #lowerEntry}, {@link #floorEntry}, {@link #ceilingEntry},
13	>	* and {@link #higherEntry} return {@code Map.Entry} objects
14		* associated with keys respectively less than, less than or equal,
15		* greater than or equal, and greater than a given key, returning
16	<	* <tt>null</tt> if there is no such key.  Similarly, methods
17	<	* <tt>lowerKey</tt>, <tt>floorKey</tt>, <tt>ceilingKey</tt>, and
18	<	* <tt>higherKey</tt> return only the associated keys. All of these
16	>	* {@code null} if there is no such key.  Similarly, methods
17	>	* {@link #lowerKey}, {@link #floorKey}, {@link #ceilingKey}, and
18	>	* {@link #higherKey} return only the associated keys. All of these
19		* methods are designed for locating, not traversing entries.
20		*
21	<	* <p>A <tt>NavigableMap</tt> may be viewed and traversed in either
22	<	* ascending or descending key order.  The <tt>Map</tt> methods
23	<	* <tt>keySet</tt> and <tt>entrySet</tt> return ascending views, and
24	<	* the additional methods <tt>descendingKeySet</tt> and
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	<	*
30	<	* <p>This interface additionally defines methods <tt>firstEntry</tt>,
31	<	* <tt>pollFirstEntry</tt>, <tt>lastEntry</tt>, and
32	<	* <tt>pollLastEntry</tt> that return and/or remove the least and
33	<	* greatest mappings, if any exist, else returning <tt>null</tt>.
21	>	* <p>A {@code NavigableMap} may be accessed and traversed in either
22	>	* ascending or descending key order.  The {@link #descendingMap}
23	>	* method returns a view of the map with the senses of all relational
24	>	* and directional methods inverted. The performance of ascending
25	>	* operations and views is likely to be faster than that of descending
26	>	* ones.  Methods
27	>	* {@link #subMap(Object, boolean, Object, boolean) subMap(K, boolean, K, boolean)},
28	>	* {@link #headMap(Object, boolean) headMap(K, boolean)}, and
29	>	* {@link #tailMap(Object, boolean) tailMap(K, boolean)}
30	>	* differ from the like-named {@code SortedMap} methods in accepting
31	>	* additional arguments describing whether lower and upper bounds are
32	>	* inclusive versus exclusive.  Submaps of any {@code NavigableMap}
33	>	* must implement the {@code NavigableMap} interface.
34		*
35	<	* <p> Implementations of entry-returning methods are expected to
36	<	* return <tt>Map.Entry</tt> pairs representing snapshots of mappings
35	>	* <p>This interface additionally defines methods {@link #firstEntry},
36	>	* {@link #pollFirstEntry}, {@link #lastEntry}, and
37	>	* {@link #pollLastEntry} that return and/or remove the least and
38	>	* greatest mappings, if any exist, else returning {@code null}.
39	>	*
40	>	* <p>Implementations of entry-returning methods are expected to
41	>	* return {@code Map.Entry} pairs representing snapshots of mappings
42		* at the time they were produced, and thus generally do <em>not</em>
43	<	* support the optional <tt>Entry.setValue</tt> method. Note however
43	>	* support the optional {@code Entry.setValue} method. Note however
44		* that it is possible to change mappings in the associated map using
45	<	* method <tt>put</tt>.
45	>	* method {@code put}.
46	>	*
47	>	* <p>Methods
48	>	* {@link #subMap(Object, Object) subMap(K, K)},
49	>	* {@link #headMap(Object) headMap(K)}, and
50	>	* {@link #tailMap(Object) tailMap(K)}
51	>	* are specified to return {@code SortedMap} to allow existing
52	>	* implementations of {@code SortedMap} to be compatibly retrofitted to
53	>	* implement {@code NavigableMap}, but extensions and implementations
54	>	* of this interface are encouraged to override these methods to return
55	>	* {@code NavigableMap}.  Similarly,
56	>	* {@link #keySet()} can be overridden to return {@link NavigableSet}.
57	>	*
58	>	* <p>This interface is a member of the
59	>	* <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
60	>	* Java Collections Framework</a>.
61		*
62		* @author Doug Lea
63	+	* @author Josh Bloch
64		* @param <K> the type of keys maintained by this map
65	<	* @param <V> the type of mapped values
65	>	* @param <V> the type of mapped values
66	>	* @since 1.6
67		*/
68		public interface NavigableMap<K,V> extends SortedMap<K,V> {
69		/**
70	<	* Returns a key-value mapping associated with the least key
71	<	* greater than or equal to the given key, or <tt>null</tt> if there is
72	<	* no such entry.
73	<	*
74	<	* @param key the key.
75	<	* @return an Entry associated with ceiling of given key, or <tt>null</tt>
76	<	* if there is no such Entry.
77	<	* @throws ClassCastException if key cannot be compared with the keys
78	<	*            currently in the map.
79	<	* @throws NullPointerException if key is <tt>null</tt> and this map
80	<	* does not support <tt>null</tt> keys.
59	<	*/
60	<	public Map.Entry<K,V> ceilingEntry(K key);
61	<
62	<	/**
63	<	* Returns least key greater than or equal to the given key, or
64	<	* <tt>null</tt> if there is no such key.
65	<	*
66	<	* @param key the key.
67	<	* @return the ceiling key, or <tt>null</tt>
68	<	* if there is no such key.
69	<	* @throws ClassCastException if key cannot be compared with the keys
70	<	*            currently in the map.
71	<	* @throws NullPointerException if key is <tt>null</tt> and this map
72	<	* does not support <tt>null</tt> keys.
70	>	* Returns a key-value mapping associated with the greatest key
71	>	* strictly less than the given key, or {@code null} if there is
72	>	* no such key.
73	>	*
74	>	* @param key the key
75	>	* @return an entry with the greatest key less than {@code key},
76	>	*         or {@code null} if there is no such key
77	>	* @throws ClassCastException if the specified key cannot be compared
78	>	*         with the keys currently in the map
79	>	* @throws NullPointerException if the specified key is null
80	>	*         and this map does not permit null keys
81		*/
82	<	public K ceilingKey(K key);
82	>	Map.Entry<K,V> lowerEntry(K key);
83
84		/**
85	<	* Returns a key-value mapping associated with the greatest
86	<	* key strictly less than the given key, or <tt>null</tt> if there is no
87	<	* such entry.
88	<	*
89	<	* @param key the key.
90	<	* @return an Entry with greatest key less than the given
91	<	* key, or <tt>null</tt> if there is no such Entry.
92	<	* @throws ClassCastException if key cannot be compared with the keys
93	<	*            currently in the map.
94	<	* @throws NullPointerException if key is <tt>null</tt> and this map
87	<	* does not support <tt>null</tt> keys.
85	>	* Returns the greatest key strictly less than the given key, or
86	>	* {@code null} if there is no such key.
87	>	*
88	>	* @param key the key
89	>	* @return the greatest key less than {@code key},
90	>	*         or {@code null} if there is no such key
91	>	* @throws ClassCastException if the specified key cannot be compared
92	>	*         with the keys currently in the map
93	>	* @throws NullPointerException if the specified key is null
94	>	*         and this map does not permit null keys
95		*/
96	<	public Map.Entry<K,V> lowerEntry(K key);
96	>	K lowerKey(K key);
97
98		/**
99	<	* Returns the greatest key strictly less than the given key, or
100	<	* <tt>null</tt> if there is no such key.
101	<	*
102	<	* @param key the key.
103	<	* @return the greatest key less than the given
104	<	* key, or <tt>null</tt> if there is no such key.
105	<	* @throws ClassCastException if key cannot be compared with the keys
106	<	*            currently in the map.
107	<	* @throws NullPointerException if key is <tt>null</tt> and this map
108	<	* does not support <tt>null</tt> keys.
99	>	* Returns a key-value mapping associated with the greatest key
100	>	* less than or equal to the given key, or {@code null} if there
101	>	* is no such key.
102	>	*
103	>	* @param key the key
104	>	* @return an entry with the greatest key less than or equal to
105	>	*         {@code key}, or {@code null} if there is no such key
106	>	* @throws ClassCastException if the specified key cannot be compared
107	>	*         with the keys currently in the map
108	>	* @throws NullPointerException if the specified key is null
109	>	*         and this map does not permit null keys
110		*/
111	<	public K lowerKey(K key);
111	>	Map.Entry<K,V> floorEntry(K key);
112
113		/**
114	<	* Returns a key-value mapping associated with the greatest key
115	<	* less than or equal to the given key, or <tt>null</tt> if there
116	<	* is no such entry.
117	<	*
118	<	* @param key the key.
119	<	* @return an Entry associated with floor of given key, or <tt>null</tt>
120	<	* if there is no such Entry.
121	<	* @throws ClassCastException if key cannot be compared with the keys
122	<	*            currently in the map.
123	<	* @throws NullPointerException if key is <tt>null</tt> and this map
116	<	* does not support <tt>null</tt> keys.
114	>	* Returns the greatest key less than or equal to the given key,
115	>	* or {@code null} if there is no such key.
116	>	*
117	>	* @param key the key
118	>	* @return the greatest key less than or equal to {@code key},
119	>	*         or {@code null} if there is no such key
120	>	* @throws ClassCastException if the specified key cannot be compared
121	>	*         with the keys currently in the map
122	>	* @throws NullPointerException if the specified key is null
123	>	*         and this map does not permit null keys
124		*/
125	<	public Map.Entry<K,V> floorEntry(K key);
125	>	K floorKey(K key);
126
127		/**
128	<	* Returns the greatest key
129	<	* less than or equal to the given key, or <tt>null</tt> if there
130	<	* is no such key.
131	<	*
132	<	* @param key the key.
133	<	* @return the floor of given key, or <tt>null</tt> if there is no
134	<	* such key.
135	<	* @throws ClassCastException if key cannot be compared with the keys
136	<	*            currently in the map.
137	<	* @throws NullPointerException if key is <tt>null</tt> and this map
138	<	* does not support <tt>null</tt> keys.
128	>	* Returns a key-value mapping associated with the least key
129	>	* greater than or equal to the given key, or {@code null} if
130	>	* there is no such key.
131	>	*
132	>	* @param key the key
133	>	* @return an entry with the least key greater than or equal to
134	>	*         {@code key}, or {@code null} if there is no such key
135	>	* @throws ClassCastException if the specified key cannot be compared
136	>	*         with the keys currently in the map
137	>	* @throws NullPointerException if the specified key is null
138	>	*         and this map does not permit null keys
139	>	*/
140	>	Map.Entry<K,V> ceilingEntry(K key);
141	>
142	>	/**
143	>	* Returns the least key greater than or equal to the given key,
144	>	* or {@code null} if there is no such key.
145	>	*
146	>	* @param key the key
147	>	* @return the least key greater than or equal to {@code key},
148	>	*         or {@code null} if there is no such key
149	>	* @throws ClassCastException if the specified key cannot be compared
150	>	*         with the keys currently in the map
151	>	* @throws NullPointerException if the specified key is null
152	>	*         and this map does not permit null keys
153		*/
154	<	public K floorKey(K key);
154	>	K ceilingKey(K key);
155
156		/**
157		* Returns a key-value mapping associated with the least key
158	<	* strictly greater than the given key, or <tt>null</tt> if there
159	<	* is no such entry.
160	<	*
161	<	* @param key the key.
162	<	* @return an Entry with least key greater than the given key, or
163	<	* <tt>null</tt> if there is no such Entry.
164	<	* @throws ClassCastException if key cannot be compared with the keys
165	<	*            currently in the map.
166	<	* @throws NullPointerException if key is <tt>null</tt> and this map
167	<	* does not support <tt>null</tt> keys.
158	>	* strictly greater than the given key, or {@code null} if there
159	>	* is no such key.
160	>	*
161	>	* @param key the key
162	>	* @return an entry with the least key greater than {@code key},
163	>	*         or {@code null} if there is no such key
164	>	* @throws ClassCastException if the specified key cannot be compared
165	>	*         with the keys currently in the map
166	>	* @throws NullPointerException if the specified key is null
167	>	*         and this map does not permit null keys
168		*/
169	<	public Map.Entry<K,V> higherEntry(K key);
169	>	Map.Entry<K,V> higherEntry(K key);
170
171		/**
172		* Returns the least key strictly greater than the given key, or
173	<	* <tt>null</tt> if there is no such key.
174	<	*
175	<	* @param key the key.
176	<	* @return the least key greater than the given key, or
177	<	* <tt>null</tt> if there is no such key.
178	<	* @throws ClassCastException if key cannot be compared with the keys
179	<	*            currently in the map.
180	<	* @throws NullPointerException if key is <tt>null</tt> and this map
181	<	* does not support <tt>null</tt> keys.
173	>	* {@code null} if there is no such key.
174	>	*
175	>	* @param key the key
176	>	* @return the least key greater than {@code key},
177	>	*         or {@code null} if there is no such key
178	>	* @throws ClassCastException if the specified key cannot be compared
179	>	*         with the keys currently in the map
180	>	* @throws NullPointerException if the specified key is null
181	>	*         and this map does not permit null keys
182		*/
183	<	public K higherKey(K key);
183	>	K higherKey(K key);
184
185		/**
186		* Returns a key-value mapping associated with the least
187	<	* key in this map, or <tt>null</tt> if the map is empty.
188	<	*
189	<	* @return an Entry with least key, or <tt>null</tt>
190	<	* if the map is empty.
187	>	* key in this map, or {@code null} if the map is empty.
188	>	*
189	>	* @return an entry with the least key,
190	>	*         or {@code null} if this map is empty
191		*/
192	<	public Map.Entry<K,V> firstEntry();
192	>	Map.Entry<K,V> firstEntry();
193
194		/**
195		* Returns a key-value mapping associated with the greatest
196	<	* key in this map, or <tt>null</tt> if the map is empty.
197	<	*
198	<	* @return an Entry with greatest key, or <tt>null</tt>
199	<	* if the map is empty.
196	>	* key in this map, or {@code null} if the map is empty.
197	>	*
198	>	* @return an entry with the greatest key,
199	>	*         or {@code null} if this map is empty
200		*/
201	<	public Map.Entry<K,V> lastEntry();
201	>	Map.Entry<K,V> lastEntry();
202
203		/**
204		* Removes and returns a key-value mapping associated with
205	<	* the least key in this map, or <tt>null</tt> if the map is empty.
206	<	*
207	<	* @return the removed first entry of this map, or <tt>null</tt>
208	<	* if the map is empty.
205	>	* the least key in this map, or {@code null} if the map is empty.
206	>	*
207	>	* @return the removed first entry of this map,
208	>	*         or {@code null} if this map is empty
209		*/
210	<	public Map.Entry<K,V> pollFirstEntry();
210	>	Map.Entry<K,V> pollFirstEntry();
211
212		/**
213		* Removes and returns a key-value mapping associated with
214	<	* the greatest key in this map, or <tt>null</tt> if the map is empty.
194	<	*
195	<	* @return the removed last entry of this map, or <tt>null</tt>
196	<	* if the map is empty.
197	<	*/
198	<	public Map.Entry<K,V> pollLastEntry();
199	<
200	<	/**
201	<	* Returns a set view of the keys contained in this map, in
202	<	* descending key order.  The set is backed by the map, so changes
203	<	* to the map are reflected in the set, and vice-versa.  If the
204	<	* map is modified while an iteration over the set is in progress
205	<	* (except through the iterator's own <tt>remove</tt> operation),
206	<	* the results of the iteration are undefined.  The set supports
207	<	* element removal, which removes the corresponding mapping from
208	<	* the map, via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
209	<	* <tt>removeAll</tt> <tt>retainAll</tt>, and <tt>clear</tt>
210	<	* operations.  It does not support the add or <tt>addAll</tt>
211	<	* operations.
212	<	*
213	<	* @return a set view of the keys contained in this map.
214	<	*/
215	<	Set<K> descendingKeySet();
216	<
217	<	/**
218	<	* Returns a set view of the mappings contained in this map, in
219	<	* descending key order.  Each element in the returned set is a
220	<	* <tt>Map.Entry</tt>.  The set is backed by the map, so changes to
221	<	* the map are reflected in the set, and vice-versa.  If the map
222	<	* is modified while an iteration over the set is in progress
223	<	* (except through the iterator's own <tt>remove</tt> operation,
224	<	* or through the <tt>setValue</tt> operation on a map entry
225	<	* returned by the iterator) the results of the iteration are
226	<	* undefined.  The set supports element removal, which removes the
227	<	* corresponding mapping from the map, via the
228	<	* <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
229	<	* <tt>removeAll</tt>, <tt>retainAll</tt> and <tt>clear</tt>
230	<	* operations.  It does not support the <tt>add</tt> or
231	<	* <tt>addAll</tt> operations.
214	>	* the greatest key in this map, or {@code null} if the map is empty.
215		*
216	<	* @return a set view of the mappings contained in this map.
216	>	* @return the removed last entry of this map,
217	>	*         or {@code null} if this map is empty
218		*/
219	<	Set<Map.Entry<K, V>> descendingEntrySet();
219	>	Map.Entry<K,V> pollLastEntry();
220
221		/**
222	<	* Returns a view of the portion of this map whose keys range from
223	<	* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.  (If
224	<	* <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned sorted map
225	<	* is empty.)  The returned sorted map is backed by this map, so changes
226	<	* in the returned sorted map are reflected in this map, and vice-versa.
222	>	* Returns a reverse order view of the mappings contained in this map.
223	>	* The descending map is backed by this map, so changes to the map are
224	>	* reflected in the descending map, and vice-versa.  If either map is
225	>	* modified while an iteration over a collection view of either map
226	>	* is in progress (except through the iterator's own {@code remove}
227	>	* operation), the results of the iteration are undefined.
228	>	*
229	>	* <p>The returned map has an ordering equivalent to
230	>	* {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
231	>	* The expression {@code m.descendingMap().descendingMap()} returns a
232	>	* view of {@code m} essentially equivalent to {@code m}.
233	>	*
234	>	* @return a reverse order view of this map
235	>	*/
236	>	NavigableMap<K,V> descendingMap();
237	>
238	>	/**
239	>	* Returns a {@link NavigableSet} view of the keys contained in this map.
240	>	* The set's iterator returns the keys in ascending order.
241	>	* The set is backed by the map, so changes to the map are reflected in
242	>	* the set, and vice-versa.  If the map is modified while an iteration
243	>	* over the set is in progress (except through the iterator's own {@code
244	>	* remove} operation), the results of the iteration are undefined.  The
245	>	* set supports element removal, which removes the corresponding mapping
246	>	* from the map, via the {@code Iterator.remove}, {@code Set.remove},
247	>	* {@code removeAll}, {@code retainAll}, and {@code clear} operations.
248	>	* It does not support the {@code add} or {@code addAll} operations.
249	>	*
250	>	* @return a navigable set view of the keys in this map
251	>	*/
252	>	NavigableSet<K> navigableKeySet();
253
254	<	* @param fromKey low endpoint (inclusive) of the subMap.
255	<	* @param toKey high endpoint (exclusive) of the subMap.
254	>	/**
255	>	* Returns a reverse order {@link NavigableSet} view of the keys contained in this map.
256	>	* The set's iterator returns the keys in descending order.
257	>	* The set is backed by the map, so changes to the map are reflected in
258	>	* the set, and vice-versa.  If the map is modified while an iteration
259	>	* over the set is in progress (except through the iterator's own {@code
260	>	* remove} operation), the results of the iteration are undefined.  The
261	>	* set supports element removal, which removes the corresponding mapping
262	>	* from the map, via the {@code Iterator.remove}, {@code Set.remove},
263	>	* {@code removeAll}, {@code retainAll}, and {@code clear} operations.
264	>	* It does not support the {@code add} or {@code addAll} operations.
265		*
266	+	* @return a reverse order navigable set view of the keys in this map
267	+	*/
268	+	NavigableSet<K> descendingKeySet();
269	+
270	+	/**
271	+	* Returns a view of the portion of this map whose keys range from
272	+	* {@code fromKey} to {@code toKey}.  If {@code fromKey} and
273	+	* {@code toKey} are equal, the returned map is empty unless
274	+	* {@code fromInclusive} and {@code toInclusive} are both true.  The
275	+	* returned map is backed by this map, so changes in the returned map are
276	+	* reflected in this map, and vice-versa.  The returned map supports all
277	+	* optional map operations that this map supports.
278	+	*
279	+	* <p>The returned map will throw an {@code IllegalArgumentException}
280	+	* on an attempt to insert a key outside of its range, or to construct a
281	+	* submap either of whose endpoints lie outside its range.
282	+	*
283	+	* @param fromKey low endpoint of the keys in the returned map
284	+	* @param fromInclusive {@code true} if the low endpoint
285	+	*        is to be included in the returned view
286	+	* @param toKey high endpoint of the keys in the returned map
287	+	* @param toInclusive {@code true} if the high endpoint
288	+	*        is to be included in the returned view
289		* @return a view of the portion of this map whose keys range from
290	<	* <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.
290	>	*         {@code fromKey} to {@code toKey}
291	>	* @throws ClassCastException if {@code fromKey} and {@code toKey}
292	>	*         cannot be compared to one another using this map's comparator
293	>	*         (or, if the map has no comparator, using natural ordering).
294	>	*         Implementations may, but are not required to, throw this
295	>	*         exception if {@code fromKey} or {@code toKey}
296	>	*         cannot be compared to keys currently in the map.
297	>	* @throws NullPointerException if {@code fromKey} or {@code toKey}
298	>	*         is null and this map does not permit null keys
299	>	* @throws IllegalArgumentException if {@code fromKey} is greater than
300	>	*         {@code toKey}; or if this map itself has a restricted
301	>	*         range, and {@code fromKey} or {@code toKey} lies
302	>	*         outside the bounds of the range
303	>	*/
304	>	NavigableMap<K,V> subMap(K fromKey, boolean fromInclusive,
305	>	K toKey,   boolean toInclusive);
306	>
307	>	/**
308	>	* Returns a view of the portion of this map whose keys are less than (or
309	>	* equal to, if {@code inclusive} is true) {@code toKey}.  The returned
310	>	* map is backed by this map, so changes in the returned map are reflected
311	>	* in this map, and vice-versa.  The returned map supports all optional
312	>	* map operations that this map supports.
313	>	*
314	>	* <p>The returned map will throw an {@code IllegalArgumentException}
315	>	* on an attempt to insert a key outside its range.
316	>	*
317	>	* @param toKey high endpoint of the keys in the returned map
318	>	* @param inclusive {@code true} if the high endpoint
319	>	*        is to be included in the returned view
320	>	* @return a view of the portion of this map whose keys are less than
321	>	*         (or equal to, if {@code inclusive} is true) {@code toKey}
322	>	* @throws ClassCastException if {@code toKey} is not compatible
323	>	*         with this map's comparator (or, if the map has no comparator,
324	>	*         if {@code toKey} does not implement {@link Comparable}).
325	>	*         Implementations may, but are not required to, throw this
326	>	*         exception if {@code toKey} cannot be compared to keys
327	>	*         currently in the map.
328	>	* @throws NullPointerException if {@code toKey} is null
329	>	*         and this map does not permit null keys
330	>	* @throws IllegalArgumentException if this map itself has a
331	>	*         restricted range, and {@code toKey} lies outside the
332	>	*         bounds of the range
333	>	*/
334	>	NavigableMap<K,V> headMap(K toKey, boolean inclusive);
335	>
336	>	/**
337	>	* Returns a view of the portion of this map whose keys are greater than (or
338	>	* equal to, if {@code inclusive} is true) {@code fromKey}.  The returned
339	>	* map is backed by this map, so changes in the returned map are reflected
340	>	* in this map, and vice-versa.  The returned map supports all optional
341	>	* map operations that this map supports.
342		*
343	<	* @throws ClassCastException if <tt>fromKey</tt> and
344	<	* <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>.
343	>	* <p>The returned map will throw an {@code IllegalArgumentException}
344	>	* on an attempt to insert a key outside its range.
345		*
346	<	* @throws ClassCastException if <tt>toKey</tt> is not compatible
346	>	* @param fromKey low endpoint of the keys in the returned map
347	>	* @param inclusive {@code true} if the low endpoint
348	>	*        is to be included in the returned view
349	>	* @return a view of the portion of this map whose keys are greater than
350	>	*         (or equal to, if {@code inclusive} is true) {@code fromKey}
351	>	* @throws ClassCastException if {@code fromKey} is not compatible
352		*         with this map's comparator (or, if the map has no comparator,
353	<	*         if <tt>toKey</tt> does not implement <tt>Comparable</tt>).
354	<	* @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>
355	<	* and this map does not support <tt>null</tt> keys.
356	<	*/
357	<	public NavigableMap<K,V> headMap(K toKey);
353	>	*         if {@code fromKey} does not implement {@link Comparable}).
354	>	*         Implementations may, but are not required to, throw this
355	>	*         exception if {@code fromKey} cannot be compared to keys
356	>	*         currently in the map.
357	>	* @throws NullPointerException if {@code fromKey} is null
358	>	*         and this map does not permit null keys
359	>	* @throws IllegalArgumentException if this map itself has a
360	>	*         restricted range, and {@code fromKey} lies outside the
361	>	*         bounds of the range
362	>	*/
363	>	NavigableMap<K,V> tailMap(K fromKey, boolean inclusive);
364
365		/**
366	<	* Returns a view of the portion of this map whose keys are
367	<	* greater than or equal to <tt>fromKey</tt>.  The returned sorted
368	<	* map is backed by this map, so changes in the returned sorted
369	<	* map are reflected in this map, and vice-versa.
370	<	* @param fromKey low endpoint (inclusive) of the tailMap.
371	<	* @return a view of the portion of this map whose keys are greater
372	<	*                than or equal to <tt>fromKey</tt>.
373	<	* @throws ClassCastException if <tt>fromKey</tt> is not compatible
374	<	*         with this map's comparator (or, if the map has no comparator,
375	<	*         if <tt>fromKey</tt> does not implement <tt>Comparable</tt>).
376	<	* @throws NullPointerException if <tt>fromKey</tt> is <tt>null</tt>
377	<	* and this map does not support <tt>null</tt> keys.
366	>	* {@inheritDoc}
367	>	*
368	>	* <p>Equivalent to {@code subMap(fromKey, true, toKey, false)}.
369	>	*
370	>	* @throws ClassCastException       {@inheritDoc}
371	>	* @throws NullPointerException     {@inheritDoc}
372	>	* @throws IllegalArgumentException {@inheritDoc}
373	>	*/
374	>	SortedMap<K,V> subMap(K fromKey, K toKey);
375	>
376	>	/**
377	>	* {@inheritDoc}
378	>	*
379	>	* <p>Equivalent to {@code headMap(toKey, false)}.
380	>	*
381	>	* @throws ClassCastException       {@inheritDoc}
382	>	* @throws NullPointerException     {@inheritDoc}
383	>	* @throws IllegalArgumentException {@inheritDoc}
384	>	*/
385	>	SortedMap<K,V> headMap(K toKey);
386	>
387	>	/**
388	>	* {@inheritDoc}
389	>	*
390	>	* <p>Equivalent to {@code tailMap(fromKey, true)}.
391	>	*
392	>	* @throws ClassCastException       {@inheritDoc}
393	>	* @throws NullPointerException     {@inheritDoc}
394	>	* @throws IllegalArgumentException {@inheritDoc}
395		*/
396	<	public NavigableMap<K,V>  tailMap(K fromKey);
396	>	SortedMap<K,V> tailMap(K fromKey);
397		}

Diff Legend

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