Package org.sosy_lab.common.collect

Interface OrderStatisticMap<K,V extends @Nullable Object>

Type Parameters:

K - the type of the keys of this map

V - the type of the values of this map

All Superinterfaces:

Map<K,V>, NavigableMap<K,V>, SortedMap<K,V>

public interface OrderStatisticMap<K,V extends @Nullable Object>
extends NavigableMap<K,V>

A NavigableMap that allows two additional operations: receiving (and deleting) an entry by its rank, and getting the rank of an entry.

Implementations should adhere to all contracts of the NavigableMap interface.

Implementing classes should provide two means for comparing elements:

1. Using the natural ordering over the keys. In this case, all keys of the map have to implement the Comparable interface.
2. Using a Comparator to create an order over the keys of the map.

In both cases, the used compare-method should be consistent with equals, i.e., compare(k, l) == 0 => k.equals(l), so that the Map interface is correctly implemented. If the used compare-method is not consistent with equals, the Map contract is not fulfilled (See the SortedMap interface for a more detailed description).

See Also:

Map, SortedMap

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K extends Object,V extends Object>

Method Summary

Modifier and Type	Method	Description
static <K,V> OrderStatisticMap<K,V>	create()	Creates a new empty OrderStatisticMap using natural ordering.
static <K,V> OrderStatisticMap<K,V>	create(Comparator<? super K> pComparator)	Creates a new empty OrderStatisticMap using the given comparator over its keys.
static <K,V> OrderStatisticMap<K,V>	createWithNaturalOrder(Map<? extends K,? extends V> pMap)	Creates a new OrderStatisticSet containing the same entries as the given map, using natural ordering over its keys.
static <K,V> OrderStatisticMap<K,V>	createWithSameOrder(SortedMap<K,? extends V> pSortedMap)	Creates a new OrderStatisticMap containing the same entries and using the same order over keys as the given SortedMap.
OrderStatisticSet<K>	descendingKeySet()
OrderStatisticMap<K,V>	descendingMap()
Map.Entry<K,V>	getEntryByRank(int pIndex)	Returns the entry of this map with the given rank.
default K	getKeyByRank(int pIndex)	Returns the key of this map with the given rank.
OrderStatisticMap<K,V>	headMap(K toKey)
OrderStatisticMap<K,V>	headMap(K toKey, boolean inclusive)
OrderStatisticSet<K>	navigableKeySet()
int	rankOf(K pObj)	Return the rank of the entry with the given key in this map.
K	removeByRank(int pIndex)	Remove the entry of this map with the given rank and return its key.
OrderStatisticMap<K,V>	subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)
OrderStatisticMap<K,V>	subMap(K fromKey, K toKey)
OrderStatisticMap<K,V>	tailMap(K fromKey)
OrderStatisticMap<K,V>	tailMap(K fromKey, boolean inclusive)

Methods inherited from interface java.util.Map

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size

Methods inherited from interface java.util.NavigableMap

ceilingEntry, ceilingKey, firstEntry, floorEntry, floorKey, higherEntry, higherKey, lastEntry, lowerEntry, lowerKey, pollFirstEntry, pollLastEntry

Methods inherited from interface java.util.SortedMap

comparator, entrySet, firstKey, keySet, lastKey, values

Method Detail

getKeyByRank

default K getKeyByRank(int pIndex)

Returns the key of this map with the given rank. The lowest key in the map has rank == 0, the largest key in the set has rank == size - 1.

If this OrderStatisticMap is a view on some backing OrderStatisticMap (as created, e.g., by descendingMap() or headMap(Object)), the returned rank is in relation to the keys in the view, not in relation to the keys in the backing set. Thus, one can always expect that key of rank 0 is the first key in this map, and key of rank Map.size() - 1 is the last.

Parameters:

pIndex - the rank of the key to return

Returns:

the key of this map with the given rank

Throws:

IndexOutOfBoundsException - if the given rank is out of the range of this map (i.e., pRank < 0 || pRank >= size)

getEntryByRank

Map.Entry<K,V> getEntryByRank(int pIndex)

Returns the entry of this map with the given rank. The lowest entry in the set has rank == 0, the largest entry in the set has rank == size - 1.

If this OrderStatisticMap is a view on some backing OrderStatisticMap (as created, e.g., by descendingMap() or headMap(Object)), the returned rank is in relation to the entries in the view, not in relation to the entries in the backing set. Thus, one can always expect that entry of rank 0 is the first entry in this map, and entry of rank Map.size() - 1 is the last.

Parameters:

pIndex - the rank of the entry to return

Returns:

the entry of this map with the given rank

Throws:

IndexOutOfBoundsException - if the given rank is out of the range of this map (i.e., pRank < 0 || pRank >= size)

removeByRank

@CanIgnoreReturnValue
K removeByRank(int pIndex)

Remove the entry of this map with the given rank and return its key.

The lowest entry in the map has rank == 0, the largest entry in the map has rank == size - 1.

If this OrderStatisticMap is a view on some backing OrderStatisticMap (as created, e.g., by descendingMap() or headMap(Object)), the returned rank is in relation to the entries in the view, not in relation to the entries in the backing set. Thus, one can always expect that entry of rank 0 is the first entry in this map, and entry of rank Map.size() - 1 is the last.

Parameters:

pIndex - the rank of the element to remove

Returns:

the removed element

Throws:

IndexOutOfBoundsException - if the given rank is out of the range of this set (i.e., pRank < 0 || pRank >= size)

See Also:

getKeyByRank(int)

rankOf

int rankOf(K pObj)

Return the rank of the entry with the given key in this map. Returns -1 if the key does not exist in the map.

The lowest entry in the set has rank == 0, the largest entry in the set has rank == size - 1.

If this OrderStatisticMap is a view on some backing OrderStatisticMap (as created, e.g., by descendingMap() or headMap(Object)), the returned rank is in relation to the entries in the view, not in relation to the entries in the backing set. Thus, one can always expect that key of rank 0 is the first key in this map, and key of rank Map.size() - 1 is the last.

Parameters:

pObj - the key of the entry to return the rank for

Returns:

the rank of the entry with the given key in the map, or -1 if the key is not in the set

Throws:

NullPointerException - if the given key is null

descendingMap

OrderStatisticMap<K,V> descendingMap()

Specified by:

descendingMap in interface NavigableMap<K,V extends @Nullable Object>

navigableKeySet

OrderStatisticSet<K> navigableKeySet()

Specified by:

navigableKeySet in interface NavigableMap<K,V extends @Nullable Object>

descendingKeySet

OrderStatisticSet<K> descendingKeySet()

Specified by:

descendingKeySet in interface NavigableMap<K,V extends @Nullable Object>

subMap

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

Specified by:

subMap in interface NavigableMap<K,V extends @Nullable Object>

headMap

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

Specified by:

headMap in interface NavigableMap<K,V extends @Nullable Object>

tailMap

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

Specified by:

tailMap in interface NavigableMap<K,V extends @Nullable Object>

subMap

OrderStatisticMap<K,V> subMap(K fromKey,
                                    K toKey)

Specified by:

subMap in interface NavigableMap<K,V extends @Nullable Object>

Specified by:

subMap in interface SortedMap<K,V extends @Nullable Object>

headMap

OrderStatisticMap<K,V> headMap(K toKey)

Specified by:

headMap in interface NavigableMap<K,V extends @Nullable Object>

Specified by:

headMap in interface SortedMap<K,V extends @Nullable Object>

tailMap

OrderStatisticMap<K,V> tailMap(K fromKey)

Specified by:

tailMap in interface NavigableMap<K,V extends @Nullable Object>

Specified by:

tailMap in interface SortedMap<K,V extends @Nullable Object>

create

static <K,V> OrderStatisticMap<K,V> create()

Creates a new empty OrderStatisticMap using natural ordering. The returned map guarantees performance only in O(n) for the operations specific to the OrderStatisticMap interface.

create

static <K,V> OrderStatisticMap<K,V> create(Comparator<? super K> pComparator)

Creates a new empty OrderStatisticMap using the given comparator over its keys. The returned map guarantees performance only in O(n) for the operations specific to the OrderStatisticMap interface.

createWithNaturalOrder

static <K,V> OrderStatisticMap<K,V> createWithNaturalOrder(Map<? extends K,? extends V> pMap)

Creates a new OrderStatisticSet containing the same entries as the given map, using natural ordering over its keys. The returned map guarantees performance only in O(n) for the operations specific to the OrderStatisticMap interface.

createWithSameOrder

static <K,V> OrderStatisticMap<K,V> createWithSameOrder(SortedMap<K,? extends V> pSortedMap)

Creates a new OrderStatisticMap containing the same entries and using the same order over keys as the given SortedMap. The returned map guarantees performance only in O(n) for the operations specific to the OrderStatisticMap interface.

Type Parameters:

K - type of the keys of the given and new map

V - type of the values of the given and new map

Parameters:

pSortedMap - map to use entries and ordering of

Returns:

a new OrderStatisticMap containing the same entries and using the same order over keys as the given map