Package 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 Details

    • 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

    • emptyCursor

      static <K, V> MapCursor<K,V> emptyCursor()
      Return an empty MapCursor.
      Since:
      22.0

    • emptyMap

      static <K, V> EconomicMap<K,V> emptyMap()
      Return an empty, unmodifiable EconomicMap.
      Since:
      22.2

    • of

      static <K, V> EconomicMap<K,V> of(K key1, V value1)
      Creates an EconomicMap with one mapping.
      Parameters:
      key1 - the key of the first mapping
      value1 - the value of the first mapping
      Returns:
      a map with the mapping
      Since:
      23.0

    • of

      static <K, V> EconomicMap<K,V> of(K key1, V value1, K key2, V value2)
      Creates an EconomicMap with two mappings.
      Parameters:
      key1 - the key of the first mapping
      value1 - the value of the first mapping
      key2 - the key of the second mapping
      value2 - the value of the second mapping
      Returns:
      a map with two mappings
      Since:
      23.0