org.djutils.immutablecollections

Interface ImmutableNavigableMap<K,V>

Type Parameters:

K - the key type of content of this Map

V - the value type of content of this Map

All Superinterfaces:

ImmutableMap<K,V>, ImmutableSortedMap<K,V>, Serializable

All Known Implementing Classes:

ImmutableTreeMap

public interface ImmutableNavigableMap<K,V>
extends ImmutableSortedMap<K,V>

A ImmutableSortedMap extended with navigation methods reporting closest matches for given search targets. Methods lowerKey, floorKey, ceilingKey, and higherKey return 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. All methods from java.util.NavigableMap that can change the map have been left out.

Copyright (c) 2016-2019 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djutils.org. The DJUTILS project is distributed under a three-clause BSD-style license, which can be found at https://djutils.org/docs/license.html.

Author:

Alexander Verbraeck, Peter Knoppers, Wouter Schakel

Nested Class Summary

Nested classes/interfaces inherited from interface org.djutils.immutablecollections.ImmutableMap

ImmutableMap.ImmutableEntry<K,V>

Method Summary

Modifier and Type	Method and Description
K	ceilingKey(K e) Returns the least key in this immutable map greater than or equal to the given key, or null if there is no such key.
ImmutableNavigableMap<K,V>	descendingMap() Returns a reverse order view of the keys contained in this immutable map.
boolean	equals(Object obj) Force to redefine equals for the implementations of immutable collection classes.
K	floorKey(K e) Returns the greatest key in this immutable map less than or equal to the given key, or null if there is no such key.
int	hashCode() Force to redefine hashCode for the implementations of immutable collection classes.
ImmutableNavigableMap<K,V>	headMap(K toKey, boolean inclusive) Returns a view of the portion of this immutable map whose keys are less than (or equal to, if inclusive is true) toKey.
K	higherKey(K e) Returns the least key in this immutable map strictly greater than the given key, or null if there is no such key.
ImmutableSortedSet<K>	keySet() Returns a ImmutableSortedSet view of the keys contained in this map.
K	lowerKey(K e) Returns the greatest key in this immutable map strictly less than the given key, or null if there is no such key.
ImmutableNavigableMap<K,V>	subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive) Returns a view of the portion of this immutable map whose keys range from fromKey to toKey.
ImmutableNavigableMap<K,V>	tailMap(K fromKey, boolean inclusive) Returns a view of the portion of this immutable map whose keys are greater than (or equal to, if inclusive is true) fromKey.
NavigableMap<K,V>	toMap() Returns a modifiable copy of this immutable map.

Methods inherited from interface org.djutils.immutablecollections.ImmutableSortedMap

comparator, firstKey, headMap, lastKey, subMap, tailMap

Methods inherited from interface org.djutils.immutablecollections.ImmutableMap

containsKey, containsValue, entrySet, forEach, get, getOrDefault, isCopy, isEmpty, isWrap, size, values

Method Detail

toMap

NavigableMap<K,V> toMap()

Returns a modifiable copy of this immutable map.

Specified by:

toMap in interface ImmutableMap<K,V>

Specified by:

toMap in interface ImmutableSortedMap<K,V>

Returns:

a modifiable copy of this immutable map.

keySet

ImmutableSortedSet<K> keySet()

Returns a ImmutableSortedSet view of the keys contained in this map.

Specified by:

keySet in interface ImmutableMap<K,V>

Specified by:

keySet in interface ImmutableSortedMap<K,V>

Returns:

an immutable sorted set of the keys contained in this map

lowerKey

K lowerKey(K e)

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

Parameters:

e - K; the value to match

Returns:

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

Throws:

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

NullPointerException - if the specified key is null and this immutable map does not permit null keys

floorKey

K floorKey(K e)

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

Parameters:

e - K; the value to match

Returns:

the greatest key less than or equal to e, or null if there is no such key

Throws:

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

NullPointerException - if the specified key is null and this immutable map does not permit null keys

ceilingKey

K ceilingKey(K e)

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

Parameters:

e - K; the value to match

Returns:

the least key greater than or equal to e, or null if there is no such key

Throws:

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

NullPointerException - if the specified key is null and this immutable map does not permit null keys

higherKey

K higherKey(K e)

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

Parameters:

e - K; the value to match

Returns:

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

Throws:

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

NullPointerException - if the specified key is null and this immutable map does not permit null keys

descendingMap

ImmutableNavigableMap<K,V> descendingMap()

Returns a reverse order view of the keys contained in this immutable map.

The returned immutable map has an ordering equivalent to Collections.reverseOrder(comparator()). The expression s.descendingMap().descendingMap() returns a view of s essentially equivalent to s.

Returns:

a reverse order view of this immutable map

subMap

ImmutableNavigableMap<K,V> subMap(K fromKey,
                                  boolean fromInclusive,
                                  K toKey,
                                  boolean toInclusive)

Returns a view of the portion of this immutable map whose keys range from fromKey to toKey. If fromKey and toKey are equal, the returned immutable map is empty unless fromInclusive and toInclusive are both true.

Parameters:

fromKey - K; low endpoint of the returned immutable map

fromInclusive - boolean; true if the low endpoint is to be included in the returned view

toKey - K; high endpoint of the returned immutable map

toInclusive - boolean; true if the high endpoint is to be included in the returned view

Returns:

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

Throws:

ClassCastException - if fromKey and toKey cannot be compared to one another using this immutable map's comparator (or, if the immutable 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 immutable map.

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

IllegalArgumentException - if fromKey is greater than toKey; or if this immutable map itself has a restricted range, and fromKey or toKey lies outside the bounds of the range.

headMap

ImmutableNavigableMap<K,V> headMap(K toKey,
                                   boolean inclusive)

Returns a view of the portion of this immutable map whose keys are less than (or equal to, if inclusive is true) toKey.

Parameters:

toKey - K; high endpoint of the returned immutable map

inclusive - boolean; true if the high endpoint is to be included in the returned view

Returns:

a view of the portion of this immutable map whose keys are less than (or equal to, if inclusive is true) toKey

Throws:

ClassCastException - if toKey is not compatible with this immutable map's comparator (or, if the immutable 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 immutable map.

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

IllegalArgumentException - if this immutable map itself has a restricted range, and toKey lies outside the bounds of the range

tailMap

ImmutableNavigableMap<K,V> tailMap(K fromKey,
                                   boolean inclusive)

Returns a view of the portion of this immutable map whose keys are greater than (or equal to, if inclusive is true) fromKey.

Parameters:

fromKey - K; low endpoint of the returned immutable map

inclusive - boolean; true if the low endpoint is to be included in the returned view

Returns:

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

Throws:

ClassCastException - if fromKey is not compatible with this immutable map's comparator (or, if the immutable 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 immutable map.

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

IllegalArgumentException - if this immutable map itself has a restricted range, and fromKey lies outside the bounds of the range

equals

boolean equals(Object obj)

Force to redefine equals for the implementations of immutable collection classes.

Specified by:

equals in interface ImmutableMap<K,V>

Specified by:

equals in interface ImmutableSortedMap<K,V>

Overrides:

equals in class Object

Parameters:

obj - Object; the object to compare this collection with

Returns:

whether the objects are equal

hashCode

int hashCode()

Force to redefine hashCode for the implementations of immutable collection classes.

Specified by:

hashCode in interface ImmutableMap<K,V>

Specified by:

hashCode in interface ImmutableSortedMap<K,V>

Overrides:

hashCode in class Object

Returns:

the calculated hashCode