Top Description Methods
org.pcollections

public Interface PSortedMap<K, V>

extends PMap<K, V>, NavigableMap<K, V>
Known Direct Implementers
org.pcollections.TreePMap
Type Parameters
<K>
the type of keys maintained by this map
<V>
the type of mapped values
Imports
java.util.Collection, .Comparator, .Map, .NavigableMap, .NoSuchElementException
An immutable, persistent map from keys of type K to values of type V, with keys arranged in sorted order (according to some java.util.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 java.util.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 java.util.SortedMap for more information.)

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

Author
Ran Ari-Gur
Since
3.2.0
See Also
java.util.SortedMap, java.util.NavigableMap, java.util.Collections#unmodifiableSortedMap(java.util.SortedMap), java.util.Collections#unmodifiableNavigableMap(java.util.NavigableMap), org.pcollections.PMap, org.pcollections.PSortedSet, org.pcollections.TreePMap

Method Summary

Modifier and TypeMethod and Description
public Comparator<? super K>

Returns:

The comparator used to order the keys in this map. (Never null.)
comparator()

Redeclares java.util.SortedMap.comparator.

Returns the comparator used to order the keys in this map, or null if this map uses the natural ordering of its keys.

public PSortedSet<K>
descendingKeySet()

Redeclares java.util.NavigableMap.descendingKeySet.

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

public PSortedMap<K, V>
descendingMap()

Redeclares java.util.NavigableMap.descendingMap.

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

public PSortedMap<K, V>
headMap(K
high endpoint (exclusive) of the keys in the returned map
toKey)

Redeclares java.util.NavigableMap.headMap.

Returns a view of the portion of this map whose keys are strictly less than toKey.

public PSortedMap<K, V>
headMap(K
high endpoint of the keys in the returned map
toKey, boolean
true if the high endpoint is to be included in the returned view
inclusive)

Redeclares java.util.NavigableMap.headMap.

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

public PSortedSet<K>
keySet()

Redeclares java.util.Map.keySet, java.util.SortedMap.keySet.

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

public PSortedMap<K, V>
minus(Object key)

Redeclares org.pcollections.PMap.minus.

public PSortedMap<K, V>
minusAll(Collection<?> keys)

Redeclares org.pcollections.PMap.minusAll.

public PSortedMap<K, V>

Returns:

This map, minus its first mapping (the mapping with the least/lowest key).
minusFirstEntry()

public PSortedMap<K, V>

Returns:

This map, minus its last mapping (the mapping with the greatest/highest key).
minusLastEntry()

public PSortedMap<K, V>
plus(K key, V value)

Redeclares org.pcollections.PMap.plus.

public PSortedMap<K, V>
plusAll(Map<? extends K, ? extends V> map)

Redeclares org.pcollections.PMap.plusAll.

public default Map.Entry<K, V>
pollFirstEntry()

Implements java.util.NavigableMap.pollFirstEntry.

Deprecated Unsupported operation.

Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty (optional operation).

public default Map.Entry<K, V>
pollLastEntry()

Implements java.util.NavigableMap.pollLastEntry.

Deprecated Unsupported operation.

Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty (optional operation).

public PSortedMap<K, V>
subMap(K
low endpoint (inclusive) of the keys in the returned map
fromKey, K
high endpoint (exclusive) of the keys in the returned map
toKey)

Redeclares java.util.NavigableMap.subMap.

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

public PSortedMap<K, V>
subMap(K
low endpoint of the keys in the returned map
fromKey, boolean
true if the low endpoint is to be included in the returned view
fromInclusive, K
high endpoint of the keys in the returned map
toKey, boolean
true if the high endpoint is to be included in the returned view
toInclusive)

Redeclares java.util.NavigableMap.subMap.

Returns a view of the portion of this map whose keys range from fromKey to toKey.

public PSortedMap<K, V>
tailMap(K
low endpoint (inclusive) of the keys in the returned map
fromKey)

Redeclares java.util.NavigableMap.tailMap.

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

public PSortedMap<K, V>
tailMap(K
low endpoint of the keys in the returned map
fromKey, boolean
true if the low endpoint is to be included in the returned view
inclusive)

Redeclares java.util.NavigableMap.tailMap.

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

Inherited from java.util.NavigableMap:
ceilingEntryceilingKeyfirstEntryfloorEntryfloorKeyhigherEntryhigherKeylastEntrylowerEntrylowerKeyreversed
Inherited from org.pcollections.PMap:
clearputputAllremove

Method Detail

comparatorback to summary
public Comparator<? super K> comparator()

Redeclares java.util.SortedMap.comparator.

Doc from java.util.SortedMap.comparator.

Returns the comparator used to order the keys in this map, or null if this map uses the natural ordering of its keys.

Returns:Comparator<? super K>

The comparator used to order the keys in this map. (Never null.)

Annotations
@Override
descendingKeySetback to summary
public PSortedSet<K> descendingKeySet()

Redeclares java.util.NavigableMap.descendingKeySet.

Doc from java.util.NavigableMap.descendingKeySet.

Returns a reverse order 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 remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Returns:PSortedSet<K>

a reverse order navigable set view of the keys in this map

Annotations
@Override
descendingMapback to summary
public PSortedMap<K, V> descendingMap()

Redeclares java.util.NavigableMap.descendingMap.

Doc from 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 remove operation), the results of the iteration are undefined.

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

Returns:PSortedMap<K, V>

a reverse order view of this map

Annotations
@Override
headMapback to summary
public PSortedMap<K, V> headMap(K toKey)

Redeclares java.util.NavigableMap.headMap.

Doc from java.util.NavigableMap.headMap.

Returns a view of the portion of this map whose keys are strictly less than 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 IllegalArgumentException on an attempt to insert a key outside its range.

Equivalent to headMap(toKey, false).

Parameters
toKey:K

Doc from java.util.SortedMap.headMap.

high endpoint (exclusive) of the keys in the returned map

Returns:PSortedMap<K, V>

Doc from java.util.SortedMap.headMap.

a view of the portion of this map whose keys are strictly less than toKey

Annotations
@Override
headMapback to summary
public PSortedMap<K, V> headMap(K toKey, boolean inclusive)

Redeclares java.util.NavigableMap.headMap.

Doc from java.util.NavigableMap.headMap.

Returns a view of the portion of this map whose keys are less than (or equal to, if inclusive is true) 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 IllegalArgumentException on an attempt to insert a key outside its range.

Parameters
toKey:K

high endpoint of the keys in the returned map

inclusive:boolean

true if the high endpoint is to be included in the returned view

Returns:PSortedMap<K, V>

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

Annotations
@Override
keySetback to summary
public PSortedSet<K> keySet()

Redeclares java.util.Map.keySet, java.util.SortedMap.keySet.

Doc from java.util.Map.keySet.

Returns a Set view of the keys contained in this map. 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 remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Returns:PSortedSet<K>

a set view of the keys contained in this map

Annotations
@Override
minusback to summary
public PSortedMap<K, V> minus(Object key)

Redeclares org.pcollections.PMap.minus.

Returns:PSortedMap<K, V>

Doc from org.pcollections.PMap.minus.

a map with the mappings of this but with no value for key

Annotations
@Override
minusAllback to summary
public PSortedMap<K, V> minusAll(Collection<?> keys)

Redeclares org.pcollections.PMap.minusAll.

Returns:PSortedMap<K, V>

Doc from org.pcollections.PMap.minusAll.

a map with the mappings of this but with no value for any element of keys

Annotations
@Override
minusFirstEntryback to summary
public PSortedMap<K, V> minusFirstEntry()
Returns:PSortedMap<K, V>

This map, minus its first mapping (the mapping with the least/lowest key).

Exceptions
NoSuchElementException:
- if this map is empty
minusLastEntryback to summary
public PSortedMap<K, V> minusLastEntry()
Returns:PSortedMap<K, V>

This map, minus its last mapping (the mapping with the greatest/highest key).

Exceptions
NoSuchElementException:
- if this map is empty
navigableKeySetback to summary
public PSortedSet<K> navigableKeySet()

Redeclares java.util.NavigableMap.navigableKeySet.

Doc from java.util.NavigableMap.navigableKeySet.

Returns a 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 remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Returns:PSortedSet<K>

a navigable set view of the keys in this map

Annotations
@Override
plusback to summary
public PSortedMap<K, V> plus(K key, V value)

Redeclares org.pcollections.PMap.plus.

Returns:PSortedMap<K, V>

Doc from org.pcollections.PMap.plus.

a map with the mappings of this but with key mapped to value

Annotations
@Override
plusAllback to summary
public PSortedMap<K, V> plusAll(Map<? extends K, ? extends V> map)

Redeclares org.pcollections.PMap.plusAll.

Returns:PSortedMap<K, V>

Doc from org.pcollections.PMap.plusAll.

this combined with map, with map's mappings used for any keys in both map and this

Annotations
@Override
pollFirstEntryback to summary
public default Map.Entry<K, V> pollFirstEntry()

Implements java.util.NavigableMap.pollFirstEntry.

Doc from java.util.NavigableMap.pollFirstEntry.

Deprecated

Unsupported operation.

Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty (optional operation).

Returns:Map.Entry<K, V>

the removed first entry of this map, or null if this map is empty

Annotations
@Deprecated
@Override
Exceptions
UnsupportedOperationException:
- always
pollLastEntryback to summary
public default Map.Entry<K, V> pollLastEntry()

Implements java.util.NavigableMap.pollLastEntry.

Doc from java.util.NavigableMap.pollLastEntry.

Deprecated

Unsupported operation.

Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty (optional operation).

Returns:Map.Entry<K, V>

the removed last entry of this map, or null if this map is empty

Annotations
@Deprecated
@Override
Exceptions
UnsupportedOperationException:
- always
subMapback to summary
public PSortedMap<K, V> subMap(K fromKey, K toKey)

Redeclares java.util.NavigableMap.subMap.

Doc from java.util.NavigableMap.subMap.

Returns a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive. (If fromKey and toKey are equal, the returned map is empty.) 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 IllegalArgumentException on an attempt to insert a key outside its range.

Equivalent to subMap(fromKey, true, toKey, false).

Parameters
fromKey:K

Doc from java.util.SortedMap.subMap.

low endpoint (inclusive) of the keys in the returned map

toKey:K

Doc from java.util.SortedMap.subMap.

high endpoint (exclusive) of the keys in the returned map

Returns:PSortedMap<K, V>

Doc from java.util.SortedMap.subMap.

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

Annotations
@Override
subMapback to summary
public PSortedMap<K, V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)

Redeclares java.util.NavigableMap.subMap.

Doc from java.util.NavigableMap.subMap.

Returns a view of the portion of this map whose keys range from fromKey to toKey. If fromKey and toKey are equal, the returned map is empty unless fromInclusive and toInclusive 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 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.

Parameters
fromKey:K

low endpoint of the keys in the returned map

fromInclusive:boolean

true if the low endpoint is to be included in the returned view

toKey:K

high endpoint of the keys in the returned map

toInclusive:boolean

true if the high endpoint is to be included in the returned view

Returns:PSortedMap<K, V>

a view of the portion of this map whose keys range from fromKey to toKey

Annotations
@Override
tailMapback to summary
public PSortedMap<K, V> tailMap(K fromKey)

Redeclares java.util.NavigableMap.tailMap.

Doc from java.util.NavigableMap.tailMap.

Returns a view of the portion of this map whose keys are greater than or equal to 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 IllegalArgumentException on an attempt to insert a key outside its range.

Equivalent to tailMap(fromKey, true).

Parameters
fromKey:K

Doc from java.util.SortedMap.tailMap.

low endpoint (inclusive) of the keys in the returned map

Returns:PSortedMap<K, V>

Doc from java.util.SortedMap.tailMap.

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

Annotations
@Override
tailMapback to summary
public PSortedMap<K, V> tailMap(K fromKey, boolean inclusive)

Redeclares java.util.NavigableMap.tailMap.

Doc from java.util.NavigableMap.tailMap.

Returns a view of the portion of this map whose keys are greater than (or equal to, if inclusive is true) 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 IllegalArgumentException on an attempt to insert a key outside its range.

Parameters
fromKey:K

low endpoint of the keys in the returned map

inclusive:boolean

true if the low endpoint is to be included in the returned view

Returns:PSortedMap<K, V>

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

Annotations
@Override