Interface PSortedMap<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this map
    V - the type of mapped values
    All Superinterfaces:
    java.util.Map<K,​V>, java.util.NavigableMap<K,​V>, PMap<K,​V>, java.util.SortedMap<K,​V>
    All Known Implementing Classes:
    TreePMap

    public interface PSortedMap<K,​V>
    extends PMap<K,​V>, java.util.NavigableMap<K,​V>
    An immutable, persistent map from keys of type K to values of type V, with keys arranged in sorted order (according to some Comparator), and with various methods to obtain specific mappings or ranges of mappings based on this ordering (such as the least key greater than some instance of type K, or the sub-map with keys between two instances of type K).

    Null values are supported. Null keys are disallowed unless the subclass specifically supports them; attempts to add a null key will result in NullPointerException.

    (Note: this is different from OrderedPMap, which keeps entries in the order that they were added to the map.)

    Every PSortedMap is a Map and more specifically a PMap, but as with any sorted map, a PSortedMap will only obey the general contract of those interfaces if its comparator is consistent with equals. (See SortedMap for more information.)

    Every PSortedMap is a SortedMap and more specifically a NavigableMap, but the implementations of PSortedMap provided by this library (pcollections) depart from the specification of those interfaces in a few ways:

    • headMap(...), subMap(...), and tailMap(...) are specified by SortedMap and NavigableMap to return maps with a "restricted key range", and to throw IllegalArgumentException if this instance already has a restricted key range and the relevant argument is outside that range. (This ensures that map.headMap(10).headMap(15) doesn't contain elements that map.headMap(10) does not, and that map.headMap(10).headMap(15).put(12, "x") is invalid because a mapping with the key 12 can't be put in map.headMap(10).) This library's implementations do not throw IllegalArgumentException, but rather, they ensure that an argument outside the applicable range simply has no effect; so, map.headMap(10).headMap(15) is equivalent to map.headMap(10), because map.headMap(10) already contains no elements ≥ 15. (This is also the behavior of Guava's ImmutableSortedMap. The JDK's Collections.unmodifiableSortedMap(...) and Collections.unmodifiableNavigableMap(...) are agnostic on this point, because they just delegate to the underlying map.) Other implementations are encouraged to consider doing the same, and to document their behavior in this respect. Additionally, any implementations that do use the "restricted key range" concept are encouraged to document the behavior of their minus, minusAll, plus, and plusAll methods when a key is outside the restricted key range.
    • comparator() is specified by SortedMap to return "null if this map uses the natural ordering of its elements". This library's implementations never return null from that method; instead, when the map uses the natural ordering, the method returns a Comparator instance that implements the natural ordering. (This is also the behavior of Guava's ImmutableSortedMap.) Other implementations of PSortedMap are encouraged to consider doing the same, and to document their behavior in this case.
    • pollFirstEntry() and pollLastEntry() are specified by NavigableMap to mutate this map, and are not specified to be optional operations. That's obviously not an option for a PMap, so PSortedMap provides default implementations of these methods that simply throw UnsupportedOperationException, which should be the right implementation for any implementation of this interface. (This is also the behavior of the JDK's Collections.unmodifiableNavigableMap(...) and Guava's ImmutableSortedMap.)
    Since:
    3.2.0
    See Also:
    SortedMap, NavigableMap, Collections.unmodifiableSortedMap(java.util.SortedMap), Collections.unmodifiableNavigableMap(java.util.NavigableMap), PMap, PSortedSet, TreePMap
    • Method Detail

      • plus

        PSortedMap<K,​V> plus​(K key,
                                   V value)
        Specified by:
        plus in interface PMap<K,​V>
        Returns:
        a map with the mappings of this but with key mapped to value
      • plusAll

        PSortedMap<K,​V> plusAll​(java.util.Map<? extends K,​? extends V> map)
        Specified by:
        plusAll in interface PMap<K,​V>
        Returns:
        this combined with map, with map's mappings used for any keys in both map and this
      • minus

        PSortedMap<K,​V> minus​(java.lang.Object key)
        Specified by:
        minus in interface PMap<K,​V>
        Returns:
        a map with the mappings of this but with no value for key
      • minusAll

        PSortedMap<K,​V> minusAll​(java.util.Collection<?> keys)
        Specified by:
        minusAll in interface PMap<K,​V>
        Returns:
        a map with the mappings of this but with no value for any element of keys
      • descendingKeySet

        PSortedSet<K> descendingKeySet()
        Specified by:
        descendingKeySet in interface java.util.NavigableMap<K,​V>
      • descendingMap

        PSortedMap<K,​V> descendingMap()
        Specified by:
        descendingMap in interface java.util.NavigableMap<K,​V>
      • headMap

        PSortedMap<K,​V> headMap​(K toKey)
        Specified by:
        headMap in interface java.util.NavigableMap<K,​V>
        Specified by:
        headMap in interface java.util.SortedMap<K,​V>
      • headMap

        PSortedMap<K,​V> headMap​(K toKey,
                                      boolean inclusive)
        Specified by:
        headMap in interface java.util.NavigableMap<K,​V>
      • keySet

        PSortedSet<K> keySet()
        Specified by:
        keySet in interface java.util.Map<K,​V>
        Specified by:
        keySet in interface java.util.SortedMap<K,​V>
      • navigableKeySet

        PSortedSet<K> navigableKeySet()
        Specified by:
        navigableKeySet in interface java.util.NavigableMap<K,​V>
      • subMap

        PSortedMap<K,​V> subMap​(K fromKey,
                                     K toKey)
        Specified by:
        subMap in interface java.util.NavigableMap<K,​V>
        Specified by:
        subMap in interface java.util.SortedMap<K,​V>
      • subMap

        PSortedMap<K,​V> subMap​(K fromKey,
                                     boolean fromInclusive,
                                     K toKey,
                                     boolean toInclusive)
        Specified by:
        subMap in interface java.util.NavigableMap<K,​V>
      • tailMap

        PSortedMap<K,​V> tailMap​(K fromKey)
        Specified by:
        tailMap in interface java.util.NavigableMap<K,​V>
        Specified by:
        tailMap in interface java.util.SortedMap<K,​V>
      • tailMap

        PSortedMap<K,​V> tailMap​(K fromKey,
                                      boolean inclusive)
        Specified by:
        tailMap in interface java.util.NavigableMap<K,​V>
      • comparator

        java.util.Comparator<? super K> comparator()
        Specified by:
        comparator in interface java.util.SortedMap<K,​V>
        Returns:
        The comparator used to order the keys in this map. (Never null.)
      • minusFirstEntry

        PSortedMap<K,​V> minusFirstEntry()
        Returns:
        This map, minus its first mapping (the mapping with the least/lowest key).
        Throws:
        java.util.NoSuchElementException - - if this map is empty
      • minusLastEntry

        PSortedMap<K,​V> minusLastEntry()
        Returns:
        This map, minus its last mapping (the mapping with the greatest/highest key).
        Throws:
        java.util.NoSuchElementException - - if this map is empty
      • pollFirstEntry

        @Deprecated
        default java.util.Map.Entry<K,​V> pollFirstEntry()
        Deprecated.
        Unsupported operation.
        Specified by:
        pollFirstEntry in interface java.util.NavigableMap<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - - always
      • pollLastEntry

        @Deprecated
        default java.util.Map.Entry<K,​V> pollLastEntry()
        Deprecated.
        Unsupported operation.
        Specified by:
        pollLastEntry in interface java.util.NavigableMap<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - - always