K - the type of keys maintained by this mapV - the type of mapped valuespublic interface NavigableMap<K,V>
A SortedMap extended with navigation methods returning the
closest matches for given search targets. Methods
lowerEntry, floorEntry, ceilingEntry,
and higherEntry return Map.Entry objects
associated with keys respectively less than, less than or equal,
greater than or equal, and greater than a given key, returning
null if there is no such key. Similarly, methods
lowerKey, floorKey, ceilingKey, and
higherKey return only the associated keys. All of these
methods are designed for locating, not traversing entries.
A NavigableMap may be viewed and traversed in either ascending or descending key order. The Map methods keySet and entrySet return ascending views, and the additional methods descendingKeySet and descendingEntrySet return descending views. The performance of ascending traversals is likely to be faster than descending traversals. Notice that it is possible to perform subrange traversals in either direction using navigableSubMap. Methods navigableSubMap, navigableHeadMap, and navigableTailMap differ from the similarly named SortedMap methods only in their declared return types. Submaps of any NavigableMap must implement the NavigableMap interface.
This interface additionally defines methods firstEntry, pollFirstEntry, lastEntry, and pollLastEntry that return and/or remove the least and greatest mappings, if any exist, else returning null.
Implementations of entry-returning methods are expected to return Map.Entry pairs representing snapshots of mappings at the time they were produced, and thus generally do not support the optional Entry.setValue method. Note however that it is possible to change mappings in the associated map using method put.
This interface is a member of the Java Collections Framework.
| Nested Class Summary |
|---|
| Nested classes/interfaces inherited from interface java.util.Map |
|---|
Map.Entry<K,V> |
| Method Summary | |
|---|---|
Map.Entry<K,V> |
ceilingEntry(K key)
Returns a key-value mapping associated with the least key greater than or equal to the given key, or null if there is no such key. |
K |
ceilingKey(K key)
Returns the least key greater than or equal to the given key, or null if there is no such key. |
Set<Map.Entry<K,V>> |
descendingEntrySet()
Returns a Set view of the mappings contained in this map. |
Set<K> |
descendingKeySet()
Returns a Set view of the keys contained in this map. |
Map.Entry<K,V> |
firstEntry()
Returns a key-value mapping associated with the least key in this map, or null if the map is empty. |
Map.Entry<K,V> |
floorEntry(K key)
Returns a key-value mapping associated with the greatest key less than or equal to the given key, or null if there is no such key. |
K |
floorKey(K key)
Returns the greatest key less than or equal to the given key, or null if there is no such key. |
Map.Entry<K,V> |
higherEntry(K key)
Returns a key-value mapping associated with the least key strictly greater than the given key, or null if there is no such key. |
K |
higherKey(K key)
Returns the least key strictly greater than the given key, or null if there is no such key. |
Map.Entry<K,V> |
lastEntry()
Returns a key-value mapping associated with the greatest key in this map, or null if the map is empty. |
Map.Entry<K,V> |
lowerEntry(K key)
Returns a key-value mapping associated with the greatest key strictly less than the given key, or null if there is no such key. |
K |
lowerKey(K key)
Returns the greatest key strictly less than the given key, or null if there is no such key. |
NavigableMap<K,V> |
navigableHeadMap(K toKey)
Returns a view of the portion of this map whose keys are strictly less than toKey. |
NavigableMap<K,V> |
navigableSubMap(K fromKey,
K toKey)
Returns a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive. |
NavigableMap<K,V> |
navigableTailMap(K fromKey)
Returns a view of the portion of this map whose keys are greater than or equal to fromKey. |
Map.Entry<K,V> |
pollFirstEntry()
Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty. |
Map.Entry<K,V> |
pollLastEntry()
Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty. |
| Methods inherited from interface java.util.SortedMap |
|---|
comparator, entrySet, firstKey, headMap, keySet, lastKey, subMap, tailMap, values |
| Methods inherited from interface java.util.Map |
|---|
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, put, putAll, remove, size |
| Method Detail |
|---|
Map.Entry<K,V> lowerEntry(K key)
key - the key
ClassCastException - if the specified key cannot be compared
with the keys currently in the map
NullPointerException - if the specified key is null
and this map does not permit null keysK lowerKey(K key)
key - the key
ClassCastException - if the specified key cannot be compared
with the keys currently in the map
NullPointerException - if the specified key is null
and this map does not permit null keysMap.Entry<K,V> floorEntry(K key)
key - the key
ClassCastException - if the specified key cannot be compared
with the keys currently in the map
NullPointerException - if the specified key is null
and this map does not permit null keysK floorKey(K key)
key - the key
ClassCastException - if the specified key cannot be compared
with the keys currently in the map
NullPointerException - if the specified key is null
and this map does not permit null keysMap.Entry<K,V> ceilingEntry(K key)
key - the key
ClassCastException - if the specified key cannot be compared
with the keys currently in the map
NullPointerException - if the specified key is null
and this map does not permit null keysK ceilingKey(K key)
key - the key
ClassCastException - if the specified key cannot be compared
with the keys currently in the map
NullPointerException - if the specified key is null
and this map does not permit null keysMap.Entry<K,V> higherEntry(K key)
key - the key
ClassCastException - if the specified key cannot be compared
with the keys currently in the map
NullPointerException - if the specified key is null
and this map does not permit null keysK higherKey(K key)
key - the key
ClassCastException - if the specified key cannot be compared
with the keys currently in the map
NullPointerException - if the specified key is null
and this map does not permit null keysMap.Entry<K,V> firstEntry()
Map.Entry<K,V> lastEntry()
Map.Entry<K,V> pollFirstEntry()
Map.Entry<K,V> pollLastEntry()
Set<K> descendingKeySet()
Set view of the keys contained in this map.
The set's iterator returns the keys in descending order.
The set is backed by the map, so changes to the map are
reflected in the set, and vice-versa. If the map is modified
while an iteration over the set is in progress (except through
the iterator's own remove operation), the results of
the iteration are undefined. The set supports element removal,
which removes the corresponding mapping from the map, via the
Iterator.remove, Set.remove,
removeAll, retainAll, and clear
operations. It does not support the add or addAll
operations.
Set<Map.Entry<K,V>> descendingEntrySet()
Set view of the mappings contained in this map.
The set's iterator returns the entries in descending key order.
The set is backed by the map, so changes to the map are
reflected in the set, and vice-versa. If the map is modified
while an iteration over the set is in progress (except through
the iterator's own remove operation, or through the
setValue operation on a map entry returned by the
iterator) the results of the iteration are undefined. The set
supports element removal, which removes the corresponding
mapping from the map, via the Iterator.remove,
Set.remove, removeAll, retainAll and
clear operations. It does not support the
add or addAll operations.
NavigableMap<K,V> navigableSubMap(K fromKey,
K toKey)
The returned map will throw an IllegalArgumentException on an attempt to insert a key outside its range.
fromKey - low endpoint (inclusive) of the keys in the returned maptoKey - high endpoint (exclusive) of the keys in the returned map
ClassCastException - if fromKey and toKey
cannot be compared to one another using this map's comparator
(or, if the map has no comparator, using natural ordering).
Implementations may, but are not required to, throw this
exception if fromKey or toKey
cannot be compared to keys currently in the map.
NullPointerException - if fromKey or toKey
is null and this map does not permit null keys
IllegalArgumentException - if fromKey is greater than
toKey; or if this map itself has a restricted
range, and fromKey or toKey lies
outside the bounds of the rangeNavigableMap<K,V> navigableHeadMap(K toKey)
The returned map will throw an IllegalArgumentException on an attempt to insert a key outside its range.
toKey - high endpoint (exclusive) of the keys in the returned map
ClassCastException - if toKey is not compatible
with this map's comparator (or, if the map has no comparator,
if toKey does not implement Comparable).
Implementations may, but are not required to, throw this
exception if toKey cannot be compared to keys
currently in the map.
NullPointerException - if toKey is null
and this map does not permit null keys
IllegalArgumentException - if this map itself has a
restricted range, and toKey lies outside the
bounds of the rangeNavigableMap<K,V> navigableTailMap(K fromKey)
The returned map will throw an IllegalArgumentException on an attempt to insert a key outside its range.
fromKey - low endpoint (inclusive) of the keys in the returned map
ClassCastException - if fromKey is not compatible
with this map's comparator (or, if the map has no comparator,
if fromKey does not implement Comparable).
Implementations may, but are not required to, throw this
exception if fromKey cannot be compared to keys
currently in the map.
NullPointerException - if fromKey is null
and this map does not permit null keys
IllegalArgumentException - if this map itself has a
restricted range, and fromKey lies outside the
bounds of the range