org.graalvm.collections

Interface EconomicMap<K,V>

All Superinterfaces:

UnmodifiableEconomicMap<K,V>

All Known Implementing Classes:

EconomicMapWrap

public interface EconomicMap<K,V>
extends UnmodifiableEconomicMap<K,V>

Memory efficient map data structure that dynamically changes its representation depending on the number of entries and is specially optimized for small number of entries. It keeps elements in a linear list without any hashing when the number of entries is small. Should an actual hash data structure be necessary, it tries to fit the hash value into as few bytes as possible. In contrast to HashMap, it avoids allocating an extra node object per entry and rather keeps values always in a plain array. See EconomicMapImpl for implementation details and exact thresholds when its representation changes. It supports a null value, but it does not support adding or looking up a null key. Operations get and put provide constant-time performance on average if repeatedly performed. They can however trigger an operation growing or compressing the data structure, which is linear in the number of elements. Iteration is also linear in the number of elements. The implementation is not synchronized. If multiple threads want to access the data structure, it requires manual synchronization, for example using Collections.synchronizedMap(java.util.Map<K, V>). There is also no extra precaution to detect concurrent modification while iterating. Different strategies for the equality comparison can be configured by providing a Equivalence configuration object.

Since:

19.0

Method Summary

Modifier and Type	Method and Description
void	clear() Removes all of the mappings from this map.
static <K,V> EconomicMap<K,V>	create() Creates a new map that guarantees insertion order on the key set with the default Equivalence.DEFAULT comparison strategy for keys.
static <K,V> EconomicMap<K,V>	create(Equivalence strategy) Creates a new map that guarantees insertion order on the key set with the given comparison strategy for keys.
static <K,V> EconomicMap<K,V>	create(Equivalence strategy, int initialCapacity) Creates a new map that guarantees insertion order on the key set and initializes with a specified capacity.
static <K,V> EconomicMap<K,V>	create(Equivalence strategy, UnmodifiableEconomicMap<K,V> m) Creates a new map that guarantees insertion order on the key set and copies all elements from the specified existing map.
static <K,V> EconomicMap<K,V>	create(int initialCapacity) Creates a new map that guarantees insertion order on the key set with the default Equivalence.DEFAULT comparison strategy for keys and initializes with a specified capacity.
static <K,V> EconomicMap<K,V>	create(UnmodifiableEconomicMap<K,V> m) Creates a new map that guarantees insertion order on the key set with the default Equivalence.DEFAULT comparison strategy for keys and copies all elements from the specified existing map.
MapCursor<K,V>	getEntries() Returns a MapCursor view of the mappings contained in this map.
V	put(K key, V value) Associates value with key in this map.
default void	putAll(EconomicMap<K,V> other) Copies all of the mappings from other to this map.
default void	putAll(UnmodifiableEconomicMap<? extends K,? extends V> other) Copies all of the mappings from other to this map.
default V	putIfAbsent(K key, V value) If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value.
V	removeKey(K key) Removes the mapping for key from this map if it is present.
void	replaceAll(BiFunction<? super K,? super V,? extends V> function) Replaces each entry's value with the result of invoking function on that entry until all entries have been processed or the function throws an exception.
static <K,V> EconomicMap<K,V>	wrapMap(Map<K,V> map) Wraps an existing Map as an EconomicMap.

Methods inherited from interface org.graalvm.collections.UnmodifiableEconomicMap

containsKey, get, get, getKeys, getValues, isEmpty, size

Method Detail

put

V put(K key,
      V value)

Associates value with key in this map. If the map previously contained a mapping for key, the old value is replaced by value. While the value may be null, the key must not be {code null}.

Returns:

the previous value associated with key, or null if there was no mapping for key.

Since:

19.0

putIfAbsent

default V putIfAbsent(K key,
                      V value)

If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, else returns the current value.

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

the previous value associated with the specified key, or null if there was no mapping for the key. (A null return can also indicate that the map previously associated null with the key, if the implementation supports null values.)

Since:

20.2

putAll

default void putAll(EconomicMap<K,V> other)

Copies all of the mappings from other to this map.

Since:

19.0

putAll

default void putAll(UnmodifiableEconomicMap<? extends K,? extends V> other)

Copies all of the mappings from other to this map.

Since:

19.0

clear

void clear()

Removes all of the mappings from this map. The map will be empty after this call returns.

Since:

19.0

removeKey

V removeKey(K key)

Removes the mapping for key from this map if it is present. The map will not contain a mapping for key once the call returns. The key must not be null.

Returns:

the previous value associated with key, or null if there was no mapping for key.

Since:

19.0

getEntries

MapCursor<K,V> getEntries()

Returns a MapCursor view of the mappings contained in this map.

Specified by:

getEntries in interface UnmodifiableEconomicMap<K,V>

Since:

19.0

replaceAll

void replaceAll(BiFunction<? super K,? super V,? extends V> function)

Replaces each entry's value with the result of invoking function on that entry until all entries have been processed or the function throws an exception. Exceptions thrown by the function are relayed to the caller.

Since:

19.0

create

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

Creates a new map that guarantees insertion order on the key set with the default Equivalence.DEFAULT comparison strategy for keys.

Since:

19.0

create

static <K,V> EconomicMap<K,V> create(int initialCapacity)

Creates a new map that guarantees insertion order on the key set with the default Equivalence.DEFAULT comparison strategy for keys and initializes with a specified capacity.

Since:

19.0

create

static <K,V> EconomicMap<K,V> create(Equivalence strategy)

Creates a new map that guarantees insertion order on the key set with the given comparison strategy for keys.

Since:

19.0

create

static <K,V> EconomicMap<K,V> create(UnmodifiableEconomicMap<K,V> m)

Creates a new map that guarantees insertion order on the key set with the default Equivalence.DEFAULT comparison strategy for keys and copies all elements from the specified existing map.

Since:

19.0

create

static <K,V> EconomicMap<K,V> create(Equivalence strategy,
                                     UnmodifiableEconomicMap<K,V> m)

Creates a new map that guarantees insertion order on the key set and copies all elements from the specified existing map.

Since:

19.0

create

static <K,V> EconomicMap<K,V> create(Equivalence strategy,
                                     int initialCapacity)

Creates a new map that guarantees insertion order on the key set and initializes with a specified capacity.

Since:

19.0

wrapMap

static <K,V> EconomicMap<K,V> wrapMap(Map<K,V> map)

Wraps an existing Map as an EconomicMap.

Since:

19.0