- Type Parameters:
K
- the type of keys maintained by this mapV
- the type of mapped values
- All Superinterfaces:
Map<K,
,V> NavigableMap<K,
,V> PMap<K,
,V> SortedMap<K,
V>
- All Known Implementing Classes:
TreePMap
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:
-
Nested Class Summary
-
Method Summary
Modifier and TypeMethodDescriptionComparator
<? super K> PSortedMap
<K, V> PSortedMap
<K, V> PSortedMap
<K, V> keySet()
PSortedMap
<K, V> PSortedMap
<K, V> minusAll
(Collection<?> keys) PSortedMap
<K, V> PSortedMap
<K, V> PSortedMap
<K, V> PSortedMap
<K, V> Deprecated.Unsupported operation.Deprecated.Unsupported operation.PSortedMap
<K, V> PSortedMap
<K, V> PSortedMap
<K, V> PSortedMap
<K, V> Methods inherited from interface java.util.Map
compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, putIfAbsent, remove, replace, replace, replaceAll, size
Methods inherited from interface java.util.NavigableMap
ceilingEntry, ceilingKey, firstEntry, floorEntry, floorKey, higherEntry, higherKey, lastEntry, lowerEntry, lowerKey
-
Method Details
-
plus
-
plusAll
-
minus
-
minusAll
-
descendingKeySet
PSortedSet<K> descendingKeySet()- Specified by:
descendingKeySet
in interfaceNavigableMap<K,
V>
-
descendingMap
PSortedMap<K,V> descendingMap()- Specified by:
descendingMap
in interfaceNavigableMap<K,
V>
-
headMap
-
headMap
- Specified by:
headMap
in interfaceNavigableMap<K,
V>
-
keySet
PSortedSet<K> keySet() -
subMap
-
subMap
- Specified by:
subMap
in interfaceNavigableMap<K,
V>
-
tailMap
-
tailMap
- Specified by:
tailMap
in interfaceNavigableMap<K,
V>
-
comparator
Comparator<? super K> comparator()- Specified by:
comparator
in interfaceSortedMap<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:
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:
NoSuchElementException
- - if this map is empty
-
pollFirstEntry
Deprecated.Unsupported operation.- Specified by:
pollFirstEntry
in interfaceNavigableMap<K,
V> - Throws:
UnsupportedOperationException
- - always
-
pollLastEntry
Deprecated.Unsupported operation.- Specified by:
pollLastEntry
in interfaceNavigableMap<K,
V> - Throws:
UnsupportedOperationException
- - always
-