ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166x/NavigableMap.java
Revision: 1.10
Committed: Sat Dec 29 23:55:19 2012 UTC (11 years, 4 months ago) by jsr166
Branch: MAIN
Changes since 1.9: +52 -52 lines
Log Message: 
punctuation

File Contents

# User Rev Content
1 dl 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 jsr166 1.6 * http://creativecommons.org/publicdomain/zero/1.0/
5 dl 1.1 */
6    
7     package jsr166x;
8    
9     import java.util.*;
10    
11     /**
12 dl 1.4 * A {@link SortedMap} extended with navigation methods returning the
13     * closest matches for given search targets. Methods
14     * <tt>lowerEntry</tt>, <tt>floorEntry</tt>, <tt>ceilingEntry</tt>,
15     * and <tt>higherEntry</tt> return <tt>Map.Entry</tt> objects
16     * associated with keys respectively less than, less than or equal,
17     * greater than or equal, and greater than a given key, returning
18     * <tt>null</tt> if there is no such key. Similarly, methods
19     * <tt>lowerKey</tt>, <tt>floorKey</tt>, <tt>ceilingKey</tt>, and
20     * <tt>higherKey</tt> return only the associated keys. All of these
21     * methods are designed for locating, not traversing entries.
22 dl 1.3 *
23     * <p>A <tt>NavigableMap</tt> may be viewed and traversed in either
24     * ascending or descending key order. The <tt>Map</tt> methods
25 dl 1.4 * <tt>keySet</tt> and <tt>entrySet</tt> return ascending views, and
26 dl 1.3 * the additional methods <tt>descendingKeySet</tt> and
27 dl 1.4 * <tt>descendingEntrySet</tt> return descending views. The
28 dl 1.3 * performance of ascending traversals is likely to be faster than
29     * descending traversals. Notice that it is possible to perform
30     * subrannge traversals in either direction using <tt>SubMap</tt>.
31 jsr166 1.5 *
32 dl 1.3 * <p>This interface additionally defines methods <tt>firstEntry</tt>,
33 dl 1.2 * <tt>pollFirstEntry</tt>, <tt>lastEntry</tt>, and
34     * <tt>pollLastEntry</tt> that return and/or remove the least and
35     * greatest mappings, if any exist, else returning <tt>null</tt>.
36 dl 1.1 *
37 jsr166 1.9 * <p>Implementations of entry-returning methods are expected to
38 dl 1.3 * return <tt>Map.Entry</tt> pairs representing snapshots of mappings
39     * at the time they were produced, and thus generally do <em>not</em>
40     * support the optional <tt>Entry.setValue</tt> method. Note however
41     * that it is possible to change mappings in the associated map using
42     * method <tt>put</tt>.
43 dl 1.1 *
44     * @author Doug Lea
45     * @param <K> the type of keys maintained by this map
46 jsr166 1.5 * @param <V> the type of mapped values
47 dl 1.1 */
48     public interface NavigableMap<K,V> extends SortedMap<K,V> {
49     /**
50     * Returns a key-value mapping associated with the least key
51 dl 1.2 * greater than or equal to the given key, or <tt>null</tt> if there is
52 jsr166 1.5 * no such entry.
53     *
54 jsr166 1.10 * @param key the key
55 dl 1.2 * @return an Entry associated with ceiling of given key, or <tt>null</tt>
56 jsr166 1.10 * if there is no such Entry
57 dl 1.1 * @throws ClassCastException if key cannot be compared with the keys
58 jsr166 1.10 * currently in the map
59 dl 1.1 * @throws NullPointerException if key is <tt>null</tt> and this map
60 jsr166 1.10 * does not support <tt>null</tt> keys
61 dl 1.1 */
62     public Map.Entry<K,V> ceilingEntry(K key);
63    
64     /**
65 dl 1.3 * Returns least key greater than or equal to the given key, or
66     * <tt>null</tt> if there is no such key.
67 jsr166 1.5 *
68 jsr166 1.10 * @param key the key
69 dl 1.3 * @return the ceiling key, or <tt>null</tt>
70 jsr166 1.10 * if there is no such key
71 dl 1.3 * @throws ClassCastException if key cannot be compared with the keys
72 jsr166 1.10 * currently in the map
73 dl 1.3 * @throws NullPointerException if key is <tt>null</tt> and this map
74 jsr166 1.10 * does not support <tt>null</tt> keys
75 dl 1.3 */
76     public K ceilingKey(K key);
77    
78     /**
79 dl 1.1 * Returns a key-value mapping associated with the greatest
80 dl 1.2 * key strictly less than the given key, or <tt>null</tt> if there is no
81 jsr166 1.5 * such entry.
82     *
83 jsr166 1.10 * @param key the key
84 dl 1.1 * @return an Entry with greatest key less than the given
85 jsr166 1.10 * key, or <tt>null</tt> if there is no such Entry
86 dl 1.1 * @throws ClassCastException if key cannot be compared with the keys
87 jsr166 1.10 * currently in the map
88 dl 1.1 * @throws NullPointerException if key is <tt>null</tt> and this map
89 jsr166 1.10 * does not support <tt>null</tt> keys
90 dl 1.1 */
91     public Map.Entry<K,V> lowerEntry(K key);
92    
93     /**
94 dl 1.3 * Returns the greatest key strictly less than the given key, or
95     * <tt>null</tt> if there is no such key.
96 jsr166 1.5 *
97 jsr166 1.10 * @param key the key
98 dl 1.3 * @return the greatest key less than the given
99 jsr166 1.10 * key, or <tt>null</tt> if there is no such key
100 dl 1.3 * @throws ClassCastException if key cannot be compared with the keys
101 jsr166 1.10 * currently in the map
102 dl 1.3 * @throws NullPointerException if key is <tt>null</tt> and this map
103 jsr166 1.10 * does not support <tt>null</tt> keys
104 dl 1.3 */
105     public K lowerKey(K key);
106    
107     /**
108     * Returns a key-value mapping associated with the greatest key
109     * less than or equal to the given key, or <tt>null</tt> if there
110     * is no such entry.
111 jsr166 1.5 *
112 jsr166 1.10 * @param key the key
113 dl 1.2 * @return an Entry associated with floor of given key, or <tt>null</tt>
114 jsr166 1.10 * if there is no such Entry
115 dl 1.1 * @throws ClassCastException if key cannot be compared with the keys
116 jsr166 1.10 * currently in the map
117 dl 1.1 * @throws NullPointerException if key is <tt>null</tt> and this map
118 jsr166 1.10 * does not support <tt>null</tt> keys
119 dl 1.1 */
120     public Map.Entry<K,V> floorEntry(K key);
121    
122     /**
123 dl 1.3 * Returns the greatest key
124     * less than or equal to the given key, or <tt>null</tt> if there
125     * is no such key.
126 jsr166 1.5 *
127 jsr166 1.10 * @param key the key
128 dl 1.3 * @return the floor of given key, or <tt>null</tt> if there is no
129 jsr166 1.10 * such key
130 dl 1.3 * @throws ClassCastException if key cannot be compared with the keys
131 jsr166 1.10 * currently in the map
132 dl 1.3 * @throws NullPointerException if key is <tt>null</tt> and this map
133 jsr166 1.10 * does not support <tt>null</tt> keys
134 dl 1.3 */
135     public K floorKey(K key);
136    
137     /**
138     * Returns a key-value mapping associated with the least key
139     * strictly greater than the given key, or <tt>null</tt> if there
140     * is no such entry.
141 jsr166 1.5 *
142 jsr166 1.10 * @param key the key
143 dl 1.1 * @return an Entry with least key greater than the given key, or
144 jsr166 1.10 * <tt>null</tt> if there is no such Entry
145 dl 1.1 * @throws ClassCastException if key cannot be compared with the keys
146 jsr166 1.10 * currently in the map
147 dl 1.1 * @throws NullPointerException if key is <tt>null</tt> and this map
148 jsr166 1.10 * does not support <tt>null</tt> keys
149 dl 1.1 */
150     public Map.Entry<K,V> higherEntry(K key);
151    
152     /**
153 dl 1.3 * Returns the least key strictly greater than the given key, or
154     * <tt>null</tt> if there is no such key.
155 jsr166 1.5 *
156 jsr166 1.10 * @param key the key
157 dl 1.3 * @return the least key greater than the given key, or
158 jsr166 1.10 * <tt>null</tt> if there is no such key
159 dl 1.3 * @throws ClassCastException if key cannot be compared with the keys
160 jsr166 1.10 * currently in the map
161 dl 1.3 * @throws NullPointerException if key is <tt>null</tt> and this map
162 jsr166 1.10 * does not support <tt>null</tt> keys
163 dl 1.3 */
164     public K higherKey(K key);
165    
166     /**
167 dl 1.1 * Returns a key-value mapping associated with the least
168 dl 1.2 * key in this map, or <tt>null</tt> if the map is empty.
169 jsr166 1.5 *
170     * @return an Entry with least key, or <tt>null</tt>
171 jsr166 1.10 * if the map is empty
172 dl 1.1 */
173     public Map.Entry<K,V> firstEntry();
174    
175     /**
176     * Returns a key-value mapping associated with the greatest
177 dl 1.2 * key in this map, or <tt>null</tt> if the map is empty.
178 jsr166 1.5 *
179 dl 1.2 * @return an Entry with greatest key, or <tt>null</tt>
180 jsr166 1.10 * if the map is empty
181 dl 1.1 */
182     public Map.Entry<K,V> lastEntry();
183    
184     /**
185     * Removes and returns a key-value mapping associated with
186 dl 1.2 * the least key in this map, or <tt>null</tt> if the map is empty.
187 jsr166 1.5 *
188 dl 1.2 * @return the removed first entry of this map, or <tt>null</tt>
189 jsr166 1.10 * if the map is empty
190 dl 1.1 */
191     public Map.Entry<K,V> pollFirstEntry();
192    
193     /**
194     * Removes and returns a key-value mapping associated with
195 dl 1.2 * the greatest key in this map, or <tt>null</tt> if the map is empty.
196 jsr166 1.5 *
197 dl 1.2 * @return the removed last entry of this map, or <tt>null</tt>
198 jsr166 1.10 * if the map is empty
199 dl 1.1 */
200     public Map.Entry<K,V> pollLastEntry();
201    
202     /**
203 dl 1.3 * Returns a set view of the keys contained in this map, in
204     * descending key order. The set is backed by the map, so changes
205     * to the map are reflected in the set, and vice-versa. If the
206     * map is modified while an iteration over the set is in progress
207     * (except through the iterator's own <tt>remove</tt> operation),
208     * the results of the iteration are undefined. The set supports
209     * element removal, which removes the corresponding mapping from
210     * the map, via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
211     * <tt>removeAll</tt> <tt>retainAll</tt>, and <tt>clear</tt>
212     * operations. It does not support the add or <tt>addAll</tt>
213     * operations.
214     *
215 jsr166 1.10 * @return a set view of the keys contained in this map
216 dl 1.3 */
217     Set<K> descendingKeySet();
218    
219     /**
220     * Returns a set view of the mappings contained in this map, in
221     * descending key order. Each element in the returned set is a
222 dl 1.4 * <tt>Map.Entry</tt>. The set is backed by the map, so changes to
223 dl 1.3 * the map are reflected in the set, and vice-versa. If the map
224     * is modified while an iteration over the set is in progress
225     * (except through the iterator's own <tt>remove</tt> operation,
226     * or through the <tt>setValue</tt> operation on a map entry
227     * returned by the iterator) the results of the iteration are
228     * undefined. The set supports element removal, which removes the
229     * corresponding mapping from the map, via the
230     * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
231     * <tt>removeAll</tt>, <tt>retainAll</tt> and <tt>clear</tt>
232     * operations. It does not support the <tt>add</tt> or
233     * <tt>addAll</tt> operations.
234     *
235 jsr166 1.10 * @return a set view of the mappings contained in this map
236 dl 1.3 */
237     Set<Map.Entry<K, V>> descendingEntrySet();
238    
239     /**
240 dl 1.1 * Returns a view of the portion of this map whose keys range from
241     * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive. (If
242     * <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned sorted map
243     * is empty.) The returned sorted map is backed by this map, so changes
244     * in the returned sorted map are reflected in this map, and vice-versa.
245 jsr166 1.7 *
246 jsr166 1.10 * @param fromKey low endpoint (inclusive) of the subMap
247     * @param toKey high endpoint (exclusive) of the subMap
248 dl 1.1 *
249     * @return a view of the portion of this map whose keys range from
250 jsr166 1.10 * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive
251 dl 1.1 *
252     * @throws ClassCastException if <tt>fromKey</tt> and
253     * <tt>toKey</tt> cannot be compared to one another using this
254     * map's comparator (or, if the map has no comparator, using
255 jsr166 1.10 * natural ordering)
256 dl 1.1 * @throws IllegalArgumentException if <tt>fromKey</tt> is greater
257 jsr166 1.10 * than <tt>toKey</tt>
258 dl 1.1 * @throws NullPointerException if <tt>fromKey</tt> or
259     * <tt>toKey</tt> is <tt>null</tt> and this map does not support
260 jsr166 1.10 * <tt>null</tt> keys
261 dl 1.1 */
262     public NavigableMap<K,V> subMap(K fromKey, K toKey);
263    
264     /**
265     * Returns a view of the portion of this map whose keys are strictly less
266     * than <tt>toKey</tt>. The returned sorted map is backed by this map, so
267     * changes in the returned sorted map are reflected in this map, and
268 jsr166 1.5 * vice-versa.
269 jsr166 1.10 * @param toKey high endpoint (exclusive) of the headMap
270 dl 1.1 * @return a view of the portion of this map whose keys are strictly
271 jsr166 1.10 * less than <tt>toKey</tt>
272 dl 1.1 *
273     * @throws ClassCastException if <tt>toKey</tt> is not compatible
274     * with this map's comparator (or, if the map has no comparator,
275 jsr166 1.10 * if <tt>toKey</tt> does not implement <tt>Comparable</tt>)
276 dl 1.1 * @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>
277 jsr166 1.10 * and this map does not support <tt>null</tt> keys
278 dl 1.1 */
279     public NavigableMap<K,V> headMap(K toKey);
280    
281     /**
282     * Returns a view of the portion of this map whose keys are
283     * greater than or equal to <tt>fromKey</tt>. The returned sorted
284     * map is backed by this map, so changes in the returned sorted
285     * map are reflected in this map, and vice-versa.
286 jsr166 1.10 * @param fromKey low endpoint (inclusive) of the tailMap
287 dl 1.1 * @return a view of the portion of this map whose keys are greater
288 jsr166 1.10 * than or equal to <tt>fromKey</tt>
289 dl 1.1 * @throws ClassCastException if <tt>fromKey</tt> is not compatible
290     * with this map's comparator (or, if the map has no comparator,
291 jsr166 1.10 * if <tt>fromKey</tt> does not implement <tt>Comparable</tt>)
292 dl 1.1 * @throws NullPointerException if <tt>fromKey</tt> is <tt>null</tt>
293 jsr166 1.10 * and this map does not support <tt>null</tt> keys
294 dl 1.1 */
295 jsr166 1.8 public NavigableMap<K,V> tailMap(K fromKey);
296 dl 1.1 }