Package 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-2024 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

  • Method Details

    • 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