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. These |
19 |
> |
* methods are designed for locating, not traversing entries. To |
20 |
> |
* traverse, use view iterators and/or <tt>submap</tt>. This interface |
21 |
> |
* additionally defines methods <tt>firstEntry</tt>, |
22 |
> |
* <tt>pollFirstEntry</tt>, <tt>lastEntry</tt>, and |
23 |
> |
* <tt>pollLastEntry</tt> that return and/or remove the least and |
24 |
> |
* greatest mappings, if any exist, else returning <tt>null</tt>. |
25 |
|
* |
26 |
|
* <p> Implementations of these methods are expected to return |
27 |
|
* <tt>Map.Entry</tt> pairs representing snapshots of mappings at the |
37 |
|
public interface NavigableMap<K,V> extends SortedMap<K,V> { |
38 |
|
/** |
39 |
|
* Returns a key-value mapping associated with the least key |
40 |
< |
* greater than or equal to the given key, or null if there is |
40 |
> |
* greater than or equal to the given key, or <tt>null</tt> if there is |
41 |
|
* no such entry. |
42 |
|
* |
43 |
|
* @param key the key. |
44 |
< |
* @return an Entry associated with ceiling of given key, or null |
44 |
> |
* @return an Entry associated with ceiling of given key, or <tt>null</tt> |
45 |
|
* if there is no such Entry. |
46 |
|
* @throws ClassCastException if key cannot be compared with the keys |
47 |
|
* currently in the map. |
52 |
|
|
53 |
|
/** |
54 |
|
* Returns a key-value mapping associated with the greatest |
55 |
< |
* key strictly less than the given key, or null if there is no |
55 |
> |
* key strictly less than the given key, or <tt>null</tt> if there is no |
56 |
|
* such entry. |
57 |
|
* |
58 |
|
* @param key the key. |
59 |
|
* @return an Entry with greatest key less than the given |
60 |
< |
* key, or null if there is no such Entry. |
60 |
> |
* key, or <tt>null</tt> if there is no such Entry. |
61 |
|
* @throws ClassCastException if key cannot be compared with the keys |
62 |
|
* currently in the map. |
63 |
|
* @throws NullPointerException if key is <tt>null</tt> and this map |
67 |
|
|
68 |
|
/** |
69 |
|
* Returns a key-value mapping associated with the greatest |
70 |
< |
* key less than or equal to the given key, or null if there is no |
70 |
> |
* key less than or equal to the given key, or <tt>null</tt> if there is no |
71 |
|
* such entry. |
72 |
|
* |
73 |
|
* @param key the key. |
74 |
< |
* @return an Entry associated with floor of given key, or null |
74 |
> |
* @return an Entry associated with floor of given key, or <tt>null</tt> |
75 |
|
* if there is no such Entry. |
76 |
|
* @throws ClassCastException if key cannot be compared with the keys |
77 |
|
* currently in the map. |
82 |
|
|
83 |
|
/** |
84 |
|
* Returns a key-value mapping associated with the least |
85 |
< |
* key strictly greater than the given key, or null if there is no |
85 |
> |
* key strictly greater than the given key, or <tt>null</tt> if there is no |
86 |
|
* such entry. |
87 |
|
* |
88 |
|
* @param key the key. |
89 |
|
* @return an Entry with least key greater than the given key, or |
90 |
< |
* null if there is no such Entry. |
90 |
> |
* <tt>null</tt> if there is no such Entry. |
91 |
|
* @throws ClassCastException if key cannot be compared with the keys |
92 |
|
* currently in the map. |
93 |
|
* @throws NullPointerException if key is <tt>null</tt> and this map |
97 |
|
|
98 |
|
/** |
99 |
|
* Returns a key-value mapping associated with the least |
100 |
< |
* key in this map, or null if the map is empty. |
100 |
> |
* key in this map, or <tt>null</tt> if the map is empty. |
101 |
|
* |
102 |
< |
* @return an Entry with least key, or null |
102 |
> |
* @return an Entry with least key, or <tt>null</tt> |
103 |
|
* if the map is empty. |
104 |
|
*/ |
105 |
|
public Map.Entry<K,V> firstEntry(); |
106 |
|
|
107 |
|
/** |
108 |
|
* Returns a key-value mapping associated with the greatest |
109 |
< |
* key in this map, or null if the map is empty. |
109 |
> |
* key in this map, or <tt>null</tt> if the map is empty. |
110 |
|
* |
111 |
< |
* @return an Entry with greatest key, or null |
111 |
> |
* @return an Entry with greatest key, or <tt>null</tt> |
112 |
|
* if the map is empty. |
113 |
|
*/ |
114 |
|
public Map.Entry<K,V> lastEntry(); |
115 |
|
|
116 |
|
/** |
117 |
|
* Removes and returns a key-value mapping associated with |
118 |
< |
* the least key in this map, or null if the map is empty. |
118 |
> |
* the least key in this map, or <tt>null</tt> if the map is empty. |
119 |
|
* |
120 |
< |
* @return the removed first entry of this map, or null |
120 |
> |
* @return the removed first entry of this map, or <tt>null</tt> |
121 |
|
* if the map is empty. |
122 |
|
*/ |
123 |
|
public Map.Entry<K,V> pollFirstEntry(); |
124 |
|
|
125 |
|
/** |
126 |
|
* Removes and returns a key-value mapping associated with |
127 |
< |
* the greatest key in this map, or null if the map is empty. |
127 |
> |
* the greatest key in this map, or <tt>null</tt> if the map is empty. |
128 |
|
* |
129 |
< |
* @return the removed last entry of this map, or null |
129 |
> |
* @return the removed last entry of this map, or <tt>null</tt> |
130 |
|
* if the map is empty. |
131 |
|
*/ |
132 |
|
public Map.Entry<K,V> pollLastEntry(); |