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

Diff of /jsr166/src/main/java/util/NavigableMap.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.7, Tue May 3 02:52:07 2005 UTC revision 1.8, Mon May 16 06:27:52 2005 UTC
# Line 54  Line 54 
54   */   */
55  public interface NavigableMap<K,V> extends SortedMap<K,V> {  public interface NavigableMap<K,V> extends SortedMap<K,V> {
56      /**      /**
57       * Returns a key-value mapping associated with the least key       * Returns a key-value mapping associated with the greatest key
58       * greater than or equal to the given key, or <tt>null</tt> if there is       * strictly less than the given key, or <tt>null</tt> if there is
59       * no such entry.       * no such key.
60       *       *
61       * @param key the key.       * @param key the key
62       * @return an Entry associated with ceiling of given key, or <tt>null</tt>       * @return an entry with the greatest key less than <tt>key</tt>,
63       * if there is no such Entry.       *         or <tt>null</tt> if there is no such key
64       * @throws ClassCastException if key cannot be compared with the keys       * @throws ClassCastException if the specified key cannot be compared
65       *            currently in the map.       *         with the keys currently in the map
66       * @throws NullPointerException if key is <tt>null</tt> and this map       * @throws NullPointerException if the specified key is null
67       * does not support <tt>null</tt> keys.       *         and this map does not permit null keys
68       */       */
69      Map.Entry<K,V> ceilingEntry(K key);      Map.Entry<K,V> lowerEntry(K key);
70    
71      /**      /**
72       * Returns least key greater than or equal to the given key, or       * Returns the greatest key strictly less than the given key, or
73       * <tt>null</tt> if there is no such key.       * <tt>null</tt> if there is no such key.
74       *       *
75       * @param key the key.       * @param key the key
76       * @return the ceiling key, or <tt>null</tt>       * @return the greatest key less than <tt>key</tt>,
77       * if there is no such key.       *         or <tt>null</tt> if there is no such key
78       * @throws ClassCastException if key cannot be compared with the keys       * @throws ClassCastException if the specified key cannot be compared
79       *            currently in the map.       *         with the keys currently in the map
80       * @throws NullPointerException if key is <tt>null</tt> and this map       * @throws NullPointerException if the specified key is null
81       * does not support <tt>null</tt> keys.       *         and this map does not permit null keys
82       */       */
83      K ceilingKey(K key);      K lowerKey(K key);
84    
85      /**      /**
86       * Returns a key-value mapping associated with the greatest       * Returns a key-value mapping associated with the greatest key
87       * key strictly less than the given key, or <tt>null</tt> if there is no       * less than or equal to the given key, or <tt>null</tt> if there
88       * such entry.       * is no such key.
89       *       *
90       * @param key the key.       * @param key the key
91       * @return an Entry with greatest key less than the given       * @return an entry with the greatest key less than or equal to
92       * key, or <tt>null</tt> if there is no such Entry.       *         <tt>key</tt>, or <tt>null</tt> if there is no such key
93       * @throws ClassCastException if key cannot be compared with the keys       * @throws ClassCastException if the specified key cannot be compared
94       *            currently in the map.       *         with the keys currently in the map
95       * @throws NullPointerException if key is <tt>null</tt> and this map       * @throws NullPointerException if the specified key is null
96       * does not support <tt>null</tt> keys.       *         and this map does not permit null keys
97       */       */
98      Map.Entry<K,V> lowerEntry(K key);      Map.Entry<K,V> floorEntry(K key);
99    
100      /**      /**
101       * Returns the greatest key strictly less than the given key, or       * Returns the greatest key less than or equal to the given key,
102       * <tt>null</tt> if there is no such key.       * or <tt>null</tt> if there is no such key.
103       *       *
104       * @param key the key.       * @param key the key
105       * @return the greatest key less than the given       * @return the greatest key less than or equal to <tt>key</tt>,
106       * key, or <tt>null</tt> if there is no such key.       *         or <tt>null</tt> if there is no such key
107       * @throws ClassCastException if key cannot be compared with the keys       * @throws ClassCastException if the specified key cannot be compared
108       *            currently in the map.       *         with the keys currently in the map
109       * @throws NullPointerException if key is <tt>null</tt> and this map       * @throws NullPointerException if the specified key is null
110       * does not support <tt>null</tt> keys.       *         and this map does not permit null keys
111       */       */
112      K lowerKey(K key);      K floorKey(K key);
113    
114      /**      /**
115       * Returns a key-value mapping associated with the greatest key       * Returns a key-value mapping associated with the least key
116       * less than or equal to the given key, or <tt>null</tt> if there       * greater than or equal to the given key, or <tt>null</tt> if
117       * is no such entry.       * there is no such key.
118       *       *
119       * @param key the key.       * @param key the key
120       * @return an Entry associated with floor of given key, or <tt>null</tt>       * @return an entry with the least key greater than or equal to
121       * if there is no such Entry.       *         <tt>key</tt>, or <tt>null</tt> if there is no such key
122       * @throws ClassCastException if key cannot be compared with the keys       * @throws ClassCastException if the specified key cannot be compared
123       *            currently in the map.       *         with the keys currently in the map
124       * @throws NullPointerException if key is <tt>null</tt> and this map       * @throws NullPointerException if the specified key is null
125       * does not support <tt>null</tt> keys.       *         and this map does not permit null keys
126       */       */
127      Map.Entry<K,V> floorEntry(K key);      Map.Entry<K,V> ceilingEntry(K key);
128    
129      /**      /**
130       * Returns the greatest key       * Returns the least key greater than or equal to the given key,
131       * less than or equal to the given key, or <tt>null</tt> if there       * or <tt>null</tt> if there is no such key.
      * is no such key.  
132       *       *
133       * @param key the key.       * @param key the key
134       * @return the floor of given key, or <tt>null</tt> if there is no       * @return the least key greater than or equal to <tt>key</tt>,
135       * such key.       *         or <tt>null</tt> if there is no such key
136       * @throws ClassCastException if key cannot be compared with the keys       * @throws ClassCastException if the specified key cannot be compared
137       *            currently in the map.       *         with the keys currently in the map
138       * @throws NullPointerException if key is <tt>null</tt> and this map       * @throws NullPointerException if the specified key is null
139       * does not support <tt>null</tt> keys.       *         and this map does not permit null keys
140       */       */
141      K floorKey(K key);      K ceilingKey(K key);
142    
143      /**      /**
144       * Returns a key-value mapping associated with the least key       * Returns a key-value mapping associated with the least key
145       * strictly greater than the given key, or <tt>null</tt> if there       * strictly greater than the given key, or <tt>null</tt> if there
146       * is no such entry.       * is no such key.
147       *       *
148       * @param key the key.       * @param key the key
149       * @return an Entry with least key greater than the given key, or       * @return an entry with the least key greater than <tt>key</tt>,
150       * <tt>null</tt> if there is no such Entry.       *         or <tt>null</tt> if there is no such key
151       * @throws ClassCastException if key cannot be compared with the keys       * @throws ClassCastException if the specified key cannot be compared
152       *            currently in the map.       *         with the keys currently in the map
153       * @throws NullPointerException if key is <tt>null</tt> and this map       * @throws NullPointerException if the specified key is null
154       * does not support <tt>null</tt> keys.       *         and this map does not permit null keys
155       */       */
156      Map.Entry<K,V> higherEntry(K key);      Map.Entry<K,V> higherEntry(K key);
157    
# Line 160  Line 159 
159       * Returns the least key strictly greater than the given key, or       * Returns the least key strictly greater than the given key, or
160       * <tt>null</tt> if there is no such key.       * <tt>null</tt> if there is no such key.
161       *       *
162       * @param key the key.       * @param key the key
163       * @return the least key greater than the given key, or       * @return the least key greater than <tt>key</tt>,
164       * <tt>null</tt> if there is no such key.       *         or <tt>null</tt> if there is no such key
165       * @throws ClassCastException if key cannot be compared with the keys       * @throws ClassCastException if the specified key cannot be compared
166       *            currently in the map.       *         with the keys currently in the map
167       * @throws NullPointerException if key is <tt>null</tt> and this map       * @throws NullPointerException if the specified key is null
168       * does not support <tt>null</tt> keys.       *         and this map does not permit null keys
169       */       */
170      K higherKey(K key);      K higherKey(K key);
171    
# Line 174  Line 173 
173       * Returns a key-value mapping associated with the least       * Returns a key-value mapping associated with the least
174       * key in this map, or <tt>null</tt> if the map is empty.       * 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>       * @return an entry with the least key,
177       * if the map is empty.       *         or <tt>null</tt> if this map is empty
178       */       */
179      Map.Entry<K,V> firstEntry();      Map.Entry<K,V> firstEntry();
180    
# Line 183  Line 182 
182       * Returns a key-value mapping associated with the greatest       * Returns a key-value mapping associated with the greatest
183       * key in this map, or <tt>null</tt> if the map is empty.       * 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>       * @return an entry with the greatest key,
186       * if the map is empty.       *         or <tt>null</tt> if this map is empty
187       */       */
188      Map.Entry<K,V> lastEntry();      Map.Entry<K,V> lastEntry();
189    
# Line 192  Line 191 
191       * Removes and returns a key-value mapping associated with       * 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.       * 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>       * @return the removed first entry of this map,
195       * if the map is empty.       *         or <tt>null</tt> if this map is empty
196       */       */
197      Map.Entry<K,V> pollFirstEntry();      Map.Entry<K,V> pollFirstEntry();
198    
# Line 201  Line 200 
200       * Removes and returns a key-value mapping associated with       * 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.       * 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>       * @return the removed last entry of this map,
204       * if the map is empty.       *         or <tt>null</tt> if this map is empty
205       */       */
206      Map.Entry<K,V> pollLastEntry();      Map.Entry<K,V> pollLastEntry();
207    
208      /**      /**
209       * Returns a set view of the keys contained in this map, in       * Returns a {@link Set} view of the keys contained in this map.
210       * descending key order.  The set is backed by the map, so changes       * The set's iterator returns the keys in descending order.
211       * to the map are reflected in the set, and vice-versa.  If the       * The set is backed by the map, so changes to the map are
212       * map is modified while an iteration over the set is in progress       * reflected in the set, and vice-versa.  If the map is modified
213       * (except through the iterator's own <tt>remove</tt> operation),       * while an iteration over the set is in progress (except through
214       * the results of the iteration are undefined.  The set supports       * the iterator's own <tt>remove</tt> operation), the results of
215       * element removal, which removes the corresponding mapping from       * the iteration are undefined.  The set supports element removal,
216       * the map, via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,       * 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>       * <tt>removeAll</tt> <tt>retainAll</tt>, and <tt>clear</tt>
219       * operations.  It does not support the add or <tt>addAll</tt>       * operations.  It does not support the add or <tt>addAll</tt>
220       * operations.       * operations.
221       *       *
222       * @return a set view of the keys contained in this map.       * @return a set view of the keys contained in this map, sorted in
223         *         descending order
224       */       */
225      Set<K> descendingKeySet();      Set<K> descendingKeySet();
226    
227      /**      /**
228       * Returns a set view of the mappings contained in this map, in       * Returns a {@link Set} view of the mappings contained in this map.
229       * descending key order.  Each element in the returned set is a       * The set's iterator returns the entries in descending key order.
230       * <tt>Map.Entry</tt>.  The set is backed by the map, so changes to       * The set is backed by the map, so changes to the map are
231       * the map are reflected in the set, and vice-versa.  If the map       * reflected in the set, and vice-versa.  If the map is modified
232       * is modified while an iteration over the set is in progress       * while an iteration over the set is in progress (except through
233       * (except through the iterator's own <tt>remove</tt> operation,       * the iterator's own <tt>remove</tt> operation, or through the
234       * or through the <tt>setValue</tt> operation on a map entry       * <tt>setValue</tt> operation on a map entry returned by the
235       * returned by the iterator) the results of the iteration are       * iterator) the results of the iteration are undefined.  The set
236       * undefined.  The set supports element removal, which removes the       * supports element removal, which removes the corresponding
237       * corresponding mapping from the map, via the       * mapping from the map, via the <tt>Iterator.remove</tt>,
238       * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,       * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
239       * <tt>removeAll</tt>, <tt>retainAll</tt> and <tt>clear</tt>       * <tt>clear</tt> operations.  It does not support the
240       * operations.  It does not support the <tt>add</tt> or       * <tt>add</tt> or <tt>addAll</tt> operations.
      * <tt>addAll</tt> operations.  
241       *       *
242       * @return a set view of the mappings contained in this map.       * @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();      Set<Map.Entry<K, V>> descendingEntrySet();
246    
247      /**      /**
248       * Returns a view of the portion of this map whose keys range from       * Returns a view of the portion of this map whose keys range from
249       * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.  (If       * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.  (If
250       * <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned       * <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned map
251       * navigable map is empty.)  The returned navigable map is backed       * is empty.)  The returned map is backed by this map, so changes
252       * by this map, so changes in the returned navigable map are       * in the returned map are reflected in this map, and vice-versa.
253       * reflected in this map, and vice-versa.       * The returned map supports all optional map operations that this
254         * map supports.
255       *       *
256       * @param fromKey low endpoint (inclusive) of the subMap.       * <p>The returned map will throw an <tt>IllegalArgumentException</tt>
257       * @param toKey high endpoint (exclusive) of the subMap.       * 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       * @return a view of the portion of this map whose keys range from
262       * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.       *         <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive
263       *       * @throws ClassCastException if <tt>fromKey</tt> and <tt>toKey</tt>
264       * @throws ClassCastException if <tt>fromKey</tt> and       *         cannot be compared to one another using this map's comparator
265       * <tt>toKey</tt> cannot be compared to one another using this       *         (or, if the map has no comparator, using natural ordering).
266       * map's comparator (or, if the map has no comparator, using       *         Implementations may, but are not required to, throw this
267       * natural ordering).       *         exception if <tt>fromKey</tt> or <tt>toKey</tt>
268       * @throws IllegalArgumentException if <tt>fromKey</tt> is greater       *         cannot be compared to keys currently in the map.
269       * than <tt>toKey</tt>.       * @throws NullPointerException if <tt>fromKey</tt> or <tt>toKey</tt>
270       * @throws NullPointerException if <tt>fromKey</tt> or       *         is null and this map does not permit null keys
271       * <tt>toKey</tt> is <tt>null</tt> and this map does not support       * @throws IllegalArgumentException if <tt>fromKey</tt> is greater than
272       * <tt>null</tt> keys.       *         <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);      NavigableMap<K,V> navigableSubMap(K fromKey, K toKey);
277    
278      /**      /**
279       * Returns a view of the portion of this map whose keys are strictly less       * Returns a view of the portion of this map whose keys are
280       * than <tt>toKey</tt>.  The returned navigable map is backed by this map, so       * strictly less than <tt>toKey</tt>.  The returned map is backed
281       * changes in the returned navigable map are reflected in this map, and       * by this map, so changes in the returned map are reflected in
282       * vice-versa.       * this map, and vice-versa.  The returned map supports all
283       * @param toKey high endpoint (exclusive) of the headMap.       * optional map operations that this map supports.
284       * @return a view of the portion of this map whose keys are strictly       *
285       *                less than <tt>toKey</tt>.       * <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       * @throws ClassCastException if <tt>toKey</tt> is not compatible
292       *         with this map's comparator (or, if the map has no comparator,       *         with this map's comparator (or, if the map has no comparator,
293       *         if <tt>toKey</tt> does not implement <tt>Comparable</tt>).       *         if <tt>toKey</tt> does not implement {@link Comparable}).
294       * @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>       *         Implementations may, but are not required to, throw this
295       * and this map does not support <tt>null</tt> keys.       *         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      NavigableMap<K,V> navigableHeadMap(K toKey);      NavigableMap<K,V> navigableHeadMap(K toKey);
304    
305      /**      /**
306       * Returns a view of the portion of this map whose keys are       * Returns a view of the portion of this map whose keys are
307       * greater than or equal to <tt>fromKey</tt>.  The returned navigable       * greater than or equal to <tt>fromKey</tt>.  The returned map is
308       * map is backed by this map, so changes in the returned navigable       * backed by this map, so changes in the returned map are
309       * map are reflected in this map, and vice-versa.       * reflected in this map, and vice-versa.  The returned map
310       * @param fromKey low endpoint (inclusive) of the tailMap.       * 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       * @return a view of the portion of this map whose keys are greater
317       *                than or equal to <tt>fromKey</tt>.       *         than or equal to <tt>fromKey</tt>
318       * @throws ClassCastException if <tt>fromKey</tt> is not compatible       * @throws ClassCastException if <tt>fromKey</tt> is not compatible
319       *         with this map's comparator (or, if the map has no comparator,       *         with this map's comparator (or, if the map has no comparator,
320       *         if <tt>fromKey</tt> does not implement <tt>Comparable</tt>).       *         if <tt>fromKey</tt> does not implement {@link Comparable}).
321       * @throws NullPointerException if <tt>fromKey</tt> is <tt>null</tt>       *         Implementations may, but are not required to, throw this
322       * and this map does not support <tt>null</tt> keys.       *         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      NavigableMap<K,V>  navigableTailMap(K fromKey);      NavigableMap<K,V>  navigableTailMap(K fromKey);
331  }  }

Legend:
Removed from v.1.7  
changed lines
  Added in v.1.8

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8