ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166x/NavigableMap.java
Revision: 1.4
Committed: Sun Dec 26 20:13:15 2004 UTC (19 years, 4 months ago) by dl
Branch: MAIN
Changes since 1.3: +13 -14 lines
Log Message: 
Rename {first,last}Element->get{First,Last}

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     * http://creativecommons.org/licenses/publicdomain
5     */
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     *
32     * <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 dl 1.3 * <p> Implementations of entry-returning methods are expected to
38     * 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     * @param <V> the type of mapped values
47     */
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 dl 1.1 * no such entry.
53     *
54     * @param key the key.
55 dl 1.2 * @return an Entry associated with ceiling of given key, or <tt>null</tt>
56 dl 1.1 * if there is no such Entry.
57     * @throws ClassCastException if key cannot be compared with the keys
58     * currently in the map.
59     * @throws NullPointerException if key is <tt>null</tt> and this map
60     * does not support <tt>null</tt> keys.
61     */
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     *
68     * @param key the key.
69     * @return the ceiling key, or <tt>null</tt>
70     * if there is no such key.
71     * @throws ClassCastException if key cannot be compared with the keys
72     * currently in the map.
73     * @throws NullPointerException if key is <tt>null</tt> and this map
74     * does not support <tt>null</tt> keys.
75     */
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 dl 1.1 * such entry.
82     *
83     * @param key the key.
84     * @return an Entry with greatest key less than the given
85 dl 1.2 * 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     * currently in the map.
88     * @throws NullPointerException if key is <tt>null</tt> and this map
89     * does not support <tt>null</tt> keys.
90     */
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     *
97     * @param key the key.
98     * @return the greatest key less than the given
99     * key, or <tt>null</tt> if there is no such key.
100     * @throws ClassCastException if key cannot be compared with the keys
101     * currently in the map.
102     * @throws NullPointerException if key is <tt>null</tt> and this map
103     * does not support <tt>null</tt> keys.
104     */
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 dl 1.1 *
112     * @param key the key.
113 dl 1.2 * @return an Entry associated with floor of given key, or <tt>null</tt>
114 dl 1.1 * if there is no such Entry.
115     * @throws ClassCastException if key cannot be compared with the keys
116     * currently in the map.
117     * @throws NullPointerException if key is <tt>null</tt> and this map
118     * does not support <tt>null</tt> keys.
119     */
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     *
127     * @param key the key.
128     * @return the floor of given key, or <tt>null</tt> if there is no
129     * such key.
130     * @throws ClassCastException if key cannot be compared with the keys
131     * currently in the map.
132     * @throws NullPointerException if key is <tt>null</tt> and this map
133     * does not support <tt>null</tt> keys.
134     */
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 dl 1.1 *
142     * @param key the key.
143     * @return an Entry with least key greater than the given key, or
144 dl 1.2 * <tt>null</tt> if there is no such Entry.
145 dl 1.1 * @throws ClassCastException if key cannot be compared with the keys
146     * currently in the map.
147     * @throws NullPointerException if key is <tt>null</tt> and this map
148     * does not support <tt>null</tt> keys.
149     */
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     *
156     * @param key the key.
157     * @return the least key greater than the given key, or
158     * <tt>null</tt> if there is no such key.
159     * @throws ClassCastException if key cannot be compared with the keys
160     * currently in the map.
161     * @throws NullPointerException if key is <tt>null</tt> and this map
162     * does not support <tt>null</tt> keys.
163     */
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 dl 1.1 *
170 dl 1.2 * @return an Entry with least key, or <tt>null</tt>
171 dl 1.1 * if the map is empty.
172     */
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 dl 1.1 *
179 dl 1.2 * @return an Entry with greatest key, or <tt>null</tt>
180 dl 1.1 * if the map is empty.
181     */
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 dl 1.1 *
188 dl 1.2 * @return the removed first entry of this map, or <tt>null</tt>
189 dl 1.1 * if the map is empty.
190     */
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 dl 1.1 *
197 dl 1.2 * @return the removed last entry of this map, or <tt>null</tt>
198 dl 1.1 * if the map is empty.
199     */
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     * @return a set view of the keys contained in this map.
216     */
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     * @return a set view of the mappings contained in this map.
236     */
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    
246     * @param fromKey low endpoint (inclusive) of the subMap.
247     * @param toKey high endpoint (exclusive) of the subMap.
248     *
249     * @return a view of the portion of this map whose keys range from
250     * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.
251     *
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     * natural ordering).
256     * @throws IllegalArgumentException if <tt>fromKey</tt> is greater
257     * than <tt>toKey</tt>.
258     * @throws NullPointerException if <tt>fromKey</tt> or
259     * <tt>toKey</tt> is <tt>null</tt> and this map does not support
260     * <tt>null</tt> keys.
261     */
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     * vice-versa.
269     * @param toKey high endpoint (exclusive) of the headMap.
270     * @return a view of the portion of this map whose keys are strictly
271     * less than <tt>toKey</tt>.
272     *
273     * @throws ClassCastException if <tt>toKey</tt> is not compatible
274     * with this map's comparator (or, if the map has no comparator,
275     * if <tt>toKey</tt> does not implement <tt>Comparable</tt>).
276     * @throws NullPointerException if <tt>toKey</tt> is <tt>null</tt>
277     * and this map does not support <tt>null</tt> keys.
278     */
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     * @param fromKey low endpoint (inclusive) of the tailMap.
287     * @return a view of the portion of this map whose keys are greater
288     * than or equal to <tt>fromKey</tt>.
289     * @throws ClassCastException if <tt>fromKey</tt> is not compatible
290     * with this map's comparator (or, if the map has no comparator,
291     * if <tt>fromKey</tt> does not implement <tt>Comparable</tt>).
292     * @throws NullPointerException if <tt>fromKey</tt> is <tt>null</tt>
293     * and this map does not support <tt>null</tt> keys.
294     */
295     public NavigableMap<K,V> tailMap(K fromKey);
296     }