jsr166x

Interface NavigableMap<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Superinterfaces:

Map<K,V>, SortedMap<K,V>

All Known Subinterfaces:

ConcurrentNavigableMap<K,V>

All Known Implementing Classes:

ConcurrentSkipListMap

public interface NavigableMap<K,V>
extends SortedMap<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 subrannge traversals in either direction using SubMap.

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.

Author:

Doug Lea

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

Methods

Modifier and Type	Method and Description
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 entry.
K	ceilingKey(K key) Returns 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, in descending key order.
Set<K>	descendingKeySet() Returns a set view of the keys contained in this map, in descending key order.
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 entry.
K	floorKey(K key) Returns the greatest key less than or equal to the given key, or null if there is no such key.
NavigableMap<K,V>	headMap(K toKey) Returns a view of the portion of this map whose keys are strictly less than toKey.
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 entry.
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 entry.
K	lowerKey(K key) Returns the greatest key strictly less than the given key, or null if there is no such key.
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.
NavigableMap<K,V>	subMap(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>	tailMap(K fromKey) Returns a view of the portion of this map whose keys are greater than or equal to fromKey.

Methods inherited from interface java.util.SortedMap

comparator, entrySet, firstKey, keySet, lastKey, values

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, equals, get, hashCode, isEmpty, put, putAll, remove, size

Method Detail

ceilingEntry

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 entry.

Parameters:

key - the key

Returns:

an Entry associated with ceiling of given key, or null if there is no such Entry

Throws:

ClassCastException - if key cannot be compared with the keys currently in the map

NullPointerException - if key is null and this map does not support null keys

ceilingKey

K ceilingKey(K key)

Returns least key greater than or equal to the given key, or null if there is no such key.

Parameters:

key - the key

Returns:

the ceiling key, or null if there is no such key

Throws:

ClassCastException - if key cannot be compared with the keys currently in the map

NullPointerException - if key is null and this map does not support null keys

lowerEntry

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 entry.

Parameters:

key - the key

Returns:

an Entry with greatest key less than the given key, or null if there is no such Entry

Throws:

ClassCastException - if key cannot be compared with the keys currently in the map

NullPointerException - if key is null and this map does not support null keys

lowerKey

K lowerKey(K key)

Returns the greatest key strictly less than the given key, or null if there is no such key.

Parameters:

key - the key

Returns:

the greatest key less than the given key, or null if there is no such key

Throws:

ClassCastException - if key cannot be compared with the keys currently in the map

NullPointerException - if key is null and this map does not support null keys

floorEntry

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 entry.

Parameters:

key - the key

Returns:

an Entry associated with floor of given key, or null if there is no such Entry

Throws:

ClassCastException - if key cannot be compared with the keys currently in the map

NullPointerException - if key is null and this map does not support null keys

floorKey

K floorKey(K key)

Returns the greatest key less than or equal to the given key, or null if there is no such key.

Parameters:

key - the key

Returns:

the floor of given key, or null if there is no such key

Throws:

ClassCastException - if key cannot be compared with the keys currently in the map

NullPointerException - if key is null and this map does not support null keys

higherEntry

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 entry.

Parameters:

key - the key

Returns:

an Entry with least key greater than the given key, or null if there is no such Entry

Throws:

ClassCastException - if key cannot be compared with the keys currently in the map

NullPointerException - if key is null and this map does not support null keys

higherKey

K higherKey(K key)

Returns the least key strictly greater than the given key, or null if there is no such key.

Parameters:

key - the key

Returns:

the least key greater than the given key, or null if there is no such key

Throws:

ClassCastException - if key cannot be compared with the keys currently in the map

NullPointerException - if key is null and this map does not support null keys

firstEntry

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.

Returns:

an Entry with least key, or null if the map is empty

lastEntry

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.

Returns:

an Entry with greatest key, or null if the map is empty

pollFirstEntry

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.

Returns:

the removed first entry of this map, or null if the map is empty

pollLastEntry

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.

Returns:

the removed last entry of this map, or null if the map is empty

descendingKeySet

Set<K> descendingKeySet()

Returns a set view of the keys contained in this map, 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), 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.

Returns:

a set view of the keys contained in this map

descendingEntrySet

Set<Map.Entry<K,V>> descendingEntrySet()

Returns a set view of the mappings contained in this map, in descending key order. Each element in the returned set is a Map.Entry. 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.

Returns:

a set view of the mappings contained in this map

subMap

NavigableMap<K,V> subMap(K fromKey,
                       K toKey)

Returns a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive. (If fromKey and toKey are equal, the returned sorted map is empty.) The returned sorted map is backed by this map, so changes in the returned sorted map are reflected in this map, and vice-versa.

Specified by:

subMap in interface SortedMap<K,V>

Parameters:

fromKey - low endpoint (inclusive) of the subMap

toKey - high endpoint (exclusive) of the subMap

Returns:

a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive

Throws:

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)

IllegalArgumentException - if fromKey is greater than toKey

NullPointerException - if fromKey or toKey is null and this map does not support null keys

headMap

NavigableMap<K,V> headMap(K toKey)

Returns a view of the portion of this map whose keys are strictly less than toKey. The returned sorted map is backed by this map, so changes in the returned sorted map are reflected in this map, and vice-versa.

Specified by:

headMap in interface SortedMap<K,V>

Parameters:

toKey - high endpoint (exclusive) of the headMap

Returns:

a view of the portion of this map whose keys are strictly less than toKey

Throws:

ClassCastException - if toKey is not compatible with this map's comparator (or, if the map has no comparator, if toKey does not implement Comparable)

NullPointerException - if toKey is null and this map does not support null keys

tailMap

NavigableMap<K,V> tailMap(K fromKey)

Returns a view of the portion of this map whose keys are greater than or equal to fromKey. The returned sorted map is backed by this map, so changes in the returned sorted map are reflected in this map, and vice-versa.

Specified by:

tailMap in interface SortedMap<K,V>

Parameters:

fromKey - low endpoint (inclusive) of the tailMap

Returns:

a view of the portion of this map whose keys are greater than or equal to fromKey

Throws:

ClassCastException - if fromKey is not compatible with this map's comparator (or, if the map has no comparator, if fromKey does not implement Comparable)

NullPointerException - if fromKey is null and this map does not support null keys