ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166x/NavigableMap.java
(Generate patch)

Comparing jsr166/src/jsr166x/NavigableMap.java (file contents):
Revision 1.1 by dl, Mon Sep 6 17:01:54 2004 UTC vs.
Revision 1.3 by dl, Tue Dec 21 17:27:44 2004 UTC

# Line 9 | Line 9 | package jsr166x;
9   import java.util.*;
10  
11   /**
12 < * A {@link SortedMap} extended with methods returning key-value pairs
13 < * holding the closest matches for given search targets. Methods
14 < * <tt>lowerEntry</tt>, <tt>floorEntry</tt>, <tt>ceilingEntry</tt>,
15 < * and <tt>higherEntry</tt> return {@link Map.Entry} 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.  These methods are designed
19 < * for locating, not traversing entries. To traverse, use view
20 < * iterators and/or <tt>submap</tt>. This interface additionally
21 < * defines methods <tt>firstEntry</tt>, <tt>pollFirstEntry</tt>
22 < * <tt>lastEntry</tt>, and <tt>pollLastEntry</tt> that return and/or
23 < * remove the least and greatest mappings, if any exist, else
24 < * returning <tt>null</tt>.
12 > * A {@link SortedMap} extended with navigation methods returning
13 > * key-value pairs holding the closest matches for given search
14 > * targets. Methods <tt>lowerEntry</tt>, <tt>floorEntry</tt>,
15 > * <tt>ceilingEntry</tt>, and <tt>higherEntry</tt> return
16 > * <tt>Map.Entry</tt> objects associated with keys respectively less
17 > * than, less than or equal, greater than or equal, and greater than a
18 > * given key, returning <tt>null</tt> if there is no such key.
19 > * Similarly, methods <tt>lowerKey</tt>, <tt>floorKey</tt>,
20 > * <tt>ceilingKey</tt>, and <tt>higherKey</tt> return only the
21 > * associated keys. All of these methods are designed for locating,
22 > * not traversing entries.
23   *
24 < * <p> Implementations of these methods are expected to return
25 < * <tt>Map.Entry</tt> pairs representing snapshots of mappings at the
26 < * time they were produced, and thus generally do <em>not</em> support
27 < * the optional <tt>Entry.setValue</tt> method. Note however that it
28 < * is possible to change mappings in the associated map using method
29 < * <tt>put</tt>.
24 > * <p>A <tt>NavigableMap</tt> may be viewed and traversed in either
25 > * ascending or descending key order.  The <tt>Map</tt> methods
26 > * <tt>keySet</tt> and <tt>entrySet</tt>) return ascending views, and
27 > * the additional methods <tt>descendingKeySet</tt> and
28 > * <tt>descendingEntrySet</tt>) return descending views. The
29 > * performance of ascending traversals is likely to be faster than
30 > * descending traversals.  Notice that it is possible to perform
31 > * subrannge traversals in either direction using <tt>SubMap</tt>.
32 > *
33 > * <p>This interface additionally defines methods <tt>firstEntry</tt>,
34 > * <tt>pollFirstEntry</tt>, <tt>lastEntry</tt>, and
35 > * <tt>pollLastEntry</tt> that return and/or remove the least and
36 > * greatest mappings, if any exist, else returning <tt>null</tt>.
37 > *
38 > * <p> Implementations of entry-returning methods are expected to
39 > * return <tt>Map.Entry</tt> pairs representing snapshots of mappings
40 > * at the time they were produced, and thus generally do <em>not</em>
41 > * support the optional <tt>Entry.setValue</tt> method. Note however
42 > * that it is possible to change mappings in the associated map using
43 > * method <tt>put</tt>.
44   *
45   * @author Doug Lea
46   * @param <K> the type of keys maintained by this map
# Line 37 | Line 49 | import java.util.*;
49   public interface NavigableMap<K,V> extends SortedMap<K,V> {
50      /**
51       * Returns a key-value mapping associated with the least key
52 <     * greater than or equal to the given key, or null if there is
52 >     * greater than or equal to the given key, or <tt>null</tt> if there is
53       * no such entry.
54       *
55       * @param key the key.
56 <     * @return an Entry associated with ceiling of given key, or null
56 >     * @return an Entry associated with ceiling of given key, or <tt>null</tt>
57       * if there is no such Entry.
58       * @throws ClassCastException if key cannot be compared with the keys
59       *            currently in the map.
# Line 51 | Line 63 | public interface NavigableMap<K,V> exten
63      public Map.Entry<K,V> ceilingEntry(K key);
64  
65      /**
66 +     * Returns least key greater than or equal to the given key, or
67 +     * <tt>null</tt> if there is no such key.
68 +     *
69 +     * @param key the key.
70 +     * @return the ceiling key, or <tt>null</tt>
71 +     * if there is no such key.
72 +     * @throws ClassCastException if key cannot be compared with the keys
73 +     *            currently in the map.
74 +     * @throws NullPointerException if key is <tt>null</tt> and this map
75 +     * does not support <tt>null</tt> keys.
76 +     */
77 +    public K ceilingKey(K key);
78 +
79 +    /**
80       * Returns a key-value mapping associated with the greatest
81 <     * key strictly less than the given key, or null if there is no
81 >     * key strictly less than the given key, or <tt>null</tt> if there is no
82       * such entry.
83       *
84       * @param key the key.
85       * @return an Entry with greatest key less than the given
86 <     * key, or null if there is no such Entry.
86 >     * key, or <tt>null</tt> if there is no such Entry.
87       * @throws ClassCastException if key cannot be compared with the keys
88       *            currently in the map.
89       * @throws NullPointerException if key is <tt>null</tt> and this map
# Line 66 | Line 92 | public interface NavigableMap<K,V> exten
92      public Map.Entry<K,V> lowerEntry(K key);
93  
94      /**
95 <     * Returns a key-value mapping associated with the greatest
96 <     * key less than or equal to the given key, or null if there is no
71 <     * such entry.
95 >     * Returns the greatest key strictly less than the given key, or
96 >     * <tt>null</tt> if there is no such key.
97       *
98       * @param key the key.
99 <     * @return an Entry associated with floor of given key, or null
99 >     * @return the greatest key less than the given
100 >     * key, or <tt>null</tt> if there is no such key.
101 >     * @throws ClassCastException if key cannot be compared with the keys
102 >     *            currently in the map.
103 >     * @throws NullPointerException if key is <tt>null</tt> and this map
104 >     * does not support <tt>null</tt> keys.
105 >     */
106 >    public K lowerKey(K key);
107 >
108 >    /**
109 >     * Returns a key-value mapping associated with the greatest key
110 >     * less than or equal to the given key, or <tt>null</tt> if there
111 >     * is no such entry.
112 >     *
113 >     * @param key the key.
114 >     * @return an Entry associated with floor of given key, or <tt>null</tt>
115       * if there is no such Entry.
116       * @throws ClassCastException if key cannot be compared with the keys
117       *            currently in the map.
# Line 81 | Line 121 | public interface NavigableMap<K,V> exten
121      public Map.Entry<K,V> floorEntry(K key);
122  
123      /**
124 <     * Returns a key-value mapping associated with the least
125 <     * key strictly greater than the given key, or null if there is no
126 <     * such entry.
124 >     * Returns the greatest key
125 >     * less than or equal to the given key, or <tt>null</tt> if there
126 >     * is no such key.
127 >     *
128 >     * @param key the key.
129 >     * @return the floor of given key, or <tt>null</tt> if there is no
130 >     * such key.
131 >     * @throws ClassCastException if key cannot be compared with the keys
132 >     *            currently in the map.
133 >     * @throws NullPointerException if key is <tt>null</tt> and this map
134 >     * does not support <tt>null</tt> keys.
135 >     */
136 >    public K floorKey(K key);
137 >
138 >    /**
139 >     * Returns a key-value mapping associated with the least key
140 >     * strictly greater than the given key, or <tt>null</tt> if there
141 >     * is no such entry.
142       *
143       * @param key the key.
144       * @return an Entry with least key greater than the given key, or
145 <     * null if there is no such Entry.
145 >     * <tt>null</tt> if there is no such Entry.
146       * @throws ClassCastException if key cannot be compared with the keys
147       *            currently in the map.
148       * @throws NullPointerException if key is <tt>null</tt> and this map
# Line 96 | Line 151 | public interface NavigableMap<K,V> exten
151      public Map.Entry<K,V> higherEntry(K key);
152  
153      /**
154 +     * Returns the least key strictly greater than the given key, or
155 +     * <tt>null</tt> if there is no such key.
156 +     *
157 +     * @param key the key.
158 +     * @return the least key greater than the given key, or
159 +     * <tt>null</tt> if there is no such key.
160 +     * @throws ClassCastException if key cannot be compared with the keys
161 +     *            currently in the map.
162 +     * @throws NullPointerException if key is <tt>null</tt> and this map
163 +     * does not support <tt>null</tt> keys.
164 +     */
165 +    public K higherKey(K key);
166 +
167 +    /**
168       * Returns a key-value mapping associated with the least
169 <     * key in this map, or null if the map is empty.
169 >     * key in this map, or <tt>null</tt> if the map is empty.
170       *
171 <     * @return an Entry with least key, or null
171 >     * @return an Entry with least key, or <tt>null</tt>
172       * if the map is empty.
173       */
174      public Map.Entry<K,V> firstEntry();
175  
176      /**
177       * Returns a key-value mapping associated with the greatest
178 <     * key in this map, or null if the map is empty.
178 >     * key in this map, or <tt>null</tt> if the map is empty.
179       *
180 <     * @return an Entry with greatest key, or null
180 >     * @return an Entry with greatest key, or <tt>null</tt>
181       * if the map is empty.
182       */
183      public Map.Entry<K,V> lastEntry();
184  
185      /**
186       * Removes and returns a key-value mapping associated with
187 <     * the least key in this map, or null if the map is empty.
187 >     * the least key in this map, or <tt>null</tt> if the map is empty.
188       *
189 <     * @return the removed first entry of this map, or null
189 >     * @return the removed first entry of this map, or <tt>null</tt>
190       * if the map is empty.
191       */
192      public Map.Entry<K,V> pollFirstEntry();
193  
194      /**
195       * Removes and returns a key-value mapping associated with
196 <     * the greatest key in this map, or null if the map is empty.
196 >     * the greatest key in this map, or <tt>null</tt> if the map is empty.
197       *
198 <     * @return the removed last entry of this map, or null
198 >     * @return the removed last entry of this map, or <tt>null</tt>
199       * if the map is empty.
200       */
201      public Map.Entry<K,V> pollLastEntry();
202  
203      /**
204 +     * Returns a set view of the keys contained in this map, in
205 +     * descending key order.  The set is backed by the map, so changes
206 +     * to the map are reflected in the set, and vice-versa.  If the
207 +     * map is modified while an iteration over the set is in progress
208 +     * (except through the iterator's own <tt>remove</tt> operation),
209 +     * the results of the iteration are undefined.  The set supports
210 +     * element removal, which removes the corresponding mapping from
211 +     * the map, via the <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
212 +     * <tt>removeAll</tt> <tt>retainAll</tt>, and <tt>clear</tt>
213 +     * operations.  It does not support the add or <tt>addAll</tt>
214 +     * operations.
215 +     *
216 +     * @return a set view of the keys contained in this map.
217 +     */
218 +    Set<K> descendingKeySet();
219 +
220 +    /**
221 +     * Returns a set view of the mappings contained in this map, in
222 +     * descending key order.  Each element in the returned set is a
223 +     * {@link Map.Entry}.  The set is backed by the map, so changes to
224 +     * the map are reflected in the set, and vice-versa.  If the map
225 +     * is modified while an iteration over the set is in progress
226 +     * (except through the iterator's own <tt>remove</tt> operation,
227 +     * or through the <tt>setValue</tt> operation on a map entry
228 +     * returned by the iterator) the results of the iteration are
229 +     * undefined.  The set supports element removal, which removes the
230 +     * corresponding mapping from the map, via the
231 +     * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
232 +     * <tt>removeAll</tt>, <tt>retainAll</tt> and <tt>clear</tt>
233 +     * operations.  It does not support the <tt>add</tt> or
234 +     * <tt>addAll</tt> operations.
235 +     *
236 +     * @return a set view of the mappings contained in this map.
237 +     */
238 +    Set<Map.Entry<K, V>> descendingEntrySet();
239 +
240 +    /**
241       * Returns a view of the portion of this map whose keys range from
242       * <tt>fromKey</tt>, inclusive, to <tt>toKey</tt>, exclusive.  (If
243       * <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned sorted map

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines