NavigableMappublic interface NavigableMap implements SortedMap| A {@link SortedMap} extended with navigation methods returning the
closest matches for given search targets. Methods
{@code lowerEntry}, {@code floorEntry}, {@code ceilingEntry},
and {@code higherEntry} return {@code Map.Entry} objects
associated with keys respectively less than, less than or equal,
greater than or equal, and greater than a given key, returning
{@code null} if there is no such key. Similarly, methods
{@code lowerKey}, {@code floorKey}, {@code ceilingKey}, and
{@code higherKey} return only the associated keys. All of these
methods are designed for locating, not traversing entries.
A {@code NavigableMap} may be accessed and traversed in either
ascending or descending key order. The {@code descendingMap}
method returns a view of the map with the senses of all relational
and directional methods inverted. The performance of ascending
operations and views is likely to be faster than that of descending
ones. Methods {@code subMap}, {@code headMap},
and {@code tailMap} differ from the like-named {@code
SortedMap} methods in accepting additional arguments describing
whether lower and upper bounds are inclusive versus exclusive.
Submaps of any {@code NavigableMap} must implement the {@code
NavigableMap} interface.
This interface additionally defines methods {@code firstEntry},
{@code pollFirstEntry}, {@code lastEntry}, and
{@code pollLastEntry} that return and/or remove the least and
greatest mappings, if any exist, else returning {@code null}.
Implementations of entry-returning methods are expected to
return {@code Map.Entry} pairs representing snapshots of mappings
at the time they were produced, and thus generally do not
support the optional {@code Entry.setValue} method. Note however
that it is possible to change mappings in the associated map using
method {@code put}.
Methods
{@link #subMap(Object, Object) subMap(K, K)},
{@link #headMap(Object) headMap(K)}, and
{@link #tailMap(Object) tailMap(K)}
are specified to return {@code SortedMap} to allow existing
implementations of {@code SortedMap} to be compatibly retrofitted to
implement {@code NavigableMap}, but extensions and implementations
of this interface are encouraged to override these methods to return
{@code NavigableMap}. Similarly,
{@link #keySet()} can be overriden to return {@code NavigableSet}.
This interface is a member of the
Java Collections Framework. |
| Methods Summary |
|---|
| public java.util.Map$Entry | ceilingEntry(K key)Returns a key-value mapping associated with the least key
greater than or equal to the given key, or {@code null} if
there is no such key.
| | public K | ceilingKey(K key)Returns the least key greater than or equal to the given key,
or {@code null} if there is no such key.
| | public java.util.NavigableSet | descendingKeySet()Returns a reverse order {@link NavigableSet} 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 {@code
remove} operation), the results of the iteration are undefined. The
set supports element removal, which removes the corresponding mapping
from the map, via the {@code Iterator.remove}, {@code Set.remove},
{@code removeAll}, {@code retainAll}, and {@code clear} operations.
It does not support the {@code add} or {@code addAll} operations.
| | public java.util.NavigableMap | descendingMap()Returns a reverse order view of the mappings contained in this map.
The descending map is backed by this map, so changes to the map are
reflected in the descending map, and vice-versa. If either map is
modified while an iteration over a collection view of either map
is in progress (except through the iterator's own {@code remove}
operation), the results of the iteration are undefined.
The returned map has an ordering equivalent to
{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator()).
The expression {@code m.descendingMap().descendingMap()} returns a
view of {@code m} essentially equivalent to {@code m}.
| | public java.util.Map$Entry | firstEntry()Returns a key-value mapping associated with the least
key in this map, or {@code null} if the map is empty.
| | public java.util.Map$Entry | floorEntry(K key)Returns a key-value mapping associated with the greatest key
less than or equal to the given key, or {@code null} if there
is no such key.
| | public K | floorKey(K key)Returns the greatest key less than or equal to the given key,
or {@code null} if there is no such key.
| | public java.util.NavigableMap | headMap(K toKey, boolean inclusive)Returns a view of the portion of this map whose keys are less than (or
equal to, if {@code inclusive} is true) {@code toKey}. The returned
map is backed by this map, so changes in the returned map are reflected
in this map, and vice-versa. The returned map supports all optional
map operations that this map supports.
The returned map will throw an {@code IllegalArgumentException}
on an attempt to insert a key outside its range.
| | public java.util.SortedMap | headMap(K toKey){@inheritDoc}
Equivalent to {@code headMap(toKey, false)}.
| | public java.util.Map$Entry | higherEntry(K key)Returns a key-value mapping associated with the least key
strictly greater than the given key, or {@code null} if there
is no such key.
| | public K | higherKey(K key)Returns the least key strictly greater than the given key, or
{@code null} if there is no such key.
| | public java.util.Map$Entry | lastEntry()Returns a key-value mapping associated with the greatest
key in this map, or {@code null} if the map is empty.
| | public java.util.Map$Entry | lowerEntry(K key)Returns a key-value mapping associated with the greatest key
strictly less than the given key, or {@code null} if there is
no such key.
| | public K | lowerKey(K key)Returns the greatest key strictly less than the given key, or
{@code null} if there is no such key.
| | public java.util.NavigableSet | navigableKeySet()Returns a {@link NavigableSet} view of the keys contained in this map.
The set's iterator returns the keys in ascending 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 {@code
remove} operation), the results of the iteration are undefined. The
set supports element removal, which removes the corresponding mapping
from the map, via the {@code Iterator.remove}, {@code Set.remove},
{@code removeAll}, {@code retainAll}, and {@code clear} operations.
It does not support the {@code add} or {@code addAll} operations.
| | public java.util.Map$Entry | pollFirstEntry()Removes and returns a key-value mapping associated with
the least key in this map, or {@code null} if the map is empty.
| | public java.util.Map$Entry | pollLastEntry()Removes and returns a key-value mapping associated with
the greatest key in this map, or {@code null} if the map is empty.
| | public java.util.NavigableMap | subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)Returns a view of the portion of this map whose keys range from
{@code fromKey} to {@code toKey}. If {@code fromKey} and
{@code toKey} are equal, the returned map is empty unless
{@code fromExclusive} and {@code toExclusive} are both true. The
returned map is backed by this map, so changes in the returned map are
reflected in this map, and vice-versa. The returned map supports all
optional map operations that this map supports.
The returned map will throw an {@code IllegalArgumentException}
on an attempt to insert a key outside of its range, or to construct a
submap either of whose endpoints lie outside its range.
| | public java.util.SortedMap | subMap(K fromKey, K toKey){@inheritDoc}
Equivalent to {@code subMap(fromKey, true, toKey, false)}.
| | public java.util.NavigableMap | tailMap(K fromKey, boolean inclusive)Returns a view of the portion of this map whose keys are greater than (or
equal to, if {@code inclusive} is true) {@code fromKey}. The returned
map is backed by this map, so changes in the returned map are reflected
in this map, and vice-versa. The returned map supports all optional
map operations that this map supports.
The returned map will throw an {@code IllegalArgumentException}
on an attempt to insert a key outside its range.
| | public java.util.SortedMap | tailMap(K fromKey){@inheritDoc}
Equivalent to {@code tailMap(fromKey, true)}.
|
|
