Class ArrayMap<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this map
    V - the type of mapped values
    All Implemented Interfaces:
    java.lang.Cloneable, java.util.Map<K,​V>

    public class ArrayMap<K,​V>
    extends java.util.AbstractMap<K,​V>
    implements java.lang.Cloneable
    Memory-efficient map of keys to values with list-style random-access semantics.

    Supports null keys and values. Conceptually, the keys and values are stored in a simpler array in order to minimize memory use and provide for fast access to a key/value at a certain index (for example getKey(int)). However, traditional mapping operations like get(Object) and put(Object, Object) are slower because they need to look up all key/value pairs in the worst case.

    Implementation is not thread-safe. For a thread-safe choice instead use an implementation of ConcurrentMap.

    Since:
    1.0
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      (package private) class  ArrayMap.Entry  
      (package private) class  ArrayMap.EntryIterator  
      (package private) class  ArrayMap.EntrySet  
      • Nested classes/interfaces inherited from class java.util.AbstractMap

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.Object[] data  
      (package private) int size  
    • Constructor Summary

      Constructors 
      Constructor Description
      ArrayMap()  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(K key, V value)
      Adds the key/value mapping at the end of the list.
      void clear()  
      ArrayMap<K,​V> clone()  
      boolean containsKey​(java.lang.Object key)
      Returns whether there is a mapping for the given key.
      boolean containsValue​(java.lang.Object value)  
      static <K,​V>
      ArrayMap<K,​V>
      create()
      Returns a new instance of an array map with initial capacity of zero.
      static <K,​V>
      ArrayMap<K,​V>
      create​(int initialCapacity)
      Returns a new instance of an array map of the given initial capacity.
      void ensureCapacity​(int minCapacity)
      Ensures that the capacity of the internal arrays is at least a given capacity.
      java.util.Set<java.util.Map.Entry<K,​V>> entrySet()  
      V get​(java.lang.Object key)
      Returns the value set for the given key or null if there is no such mapping or if the mapping value is null.
      private int getDataIndexOfKey​(java.lang.Object key)
      Returns the data index of the given key or -2 if there is no such key.
      int getIndexOfKey​(K key)
      Returns the index of the given key or -1 if there is no such key.
      K getKey​(int index)
      Returns the key at the given index or null if out of bounds.
      V getValue​(int index)
      Returns the value at the given index or null if out of bounds.
      static <K,​V>
      ArrayMap<K,​V>
      of​(java.lang.Object... keyValuePairs)
      Returns a new instance of an array map of the given key value pairs in alternating order.
      V put​(K key, V value)
      Sets the value for the given key, overriding any existing value.
      V remove​(int index)
      Removes the key/value mapping at the given index, or ignored if the index is out of bounds.
      V remove​(java.lang.Object key)
      Removes the key-value pair of the given key, or ignore if the key cannot be found.
      private V removeFromDataIndexOfKey​(int dataIndexOfKey)
      Removes the key/value mapping at the given data index of key, or ignored if the index is out of bounds.
      V set​(int index, K key, V value)
      Sets the key/value mapping at the given index, overriding any existing key/value mapping.
      V set​(int index, V value)
      Sets the value at the given index, overriding any existing value mapping.
      private void setData​(int dataIndexOfKey, K key, V value)  
      private void setDataCapacity​(int newDataCapacity)  
      int size()
      Returns the number of key-value pairs set.
      void trim()
      Trims the internal array storage to minimize memory usage.
      private V valueAtDataIndex​(int dataIndex)  
      • Methods inherited from class java.util.AbstractMap

        equals, hashCode, isEmpty, keySet, putAll, toString, values
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll
    • Field Detail

      • size

        int size
      • data

        private java.lang.Object[] data
    • Constructor Detail

      • ArrayMap

        public ArrayMap()
    • Method Detail

      • create

        public static <K,​V> ArrayMap<K,​V> create()
        Returns a new instance of an array map with initial capacity of zero. Equivalent to calling the default constructor, except without the need to specify the type parameters. For example: ArrayMap<String, String> map = ArrayMap.create();.
      • create

        public static <K,​V> ArrayMap<K,​V> create​(int initialCapacity)
        Returns a new instance of an array map of the given initial capacity. For example: ArrayMap<String, String> map = ArrayMap.create(8);.
      • of

        public static <K,​V> ArrayMap<K,​V> of​(java.lang.Object... keyValuePairs)
        Returns a new instance of an array map of the given key value pairs in alternating order. For example: ArrayMap<String, String> map = ArrayMap.of("key1", "value1", "key2", "value2", ...);.

        WARNING: there is no compile-time checking of the keyValuePairs parameter to ensure that the keys or values have the correct type, so if the wrong type is passed in, any problems will occur at runtime. Also, there is no checking that the keys are unique, which the caller must ensure is true.

      • size

        public final int size()
        Returns the number of key-value pairs set.
        Specified by:
        size in interface java.util.Map<K,​V>
        Overrides:
        size in class java.util.AbstractMap<K,​V>
      • getKey

        public final K getKey​(int index)
        Returns the key at the given index or null if out of bounds.
      • getValue

        public final V getValue​(int index)
        Returns the value at the given index or null if out of bounds.
      • set

        public final V set​(int index,
                           K key,
                           V value)
        Sets the key/value mapping at the given index, overriding any existing key/value mapping.

        There is no checking done to ensure that the key does not already exist. Therefore, this method is dangerous to call unless the caller can be certain the key does not already exist in the map.

        Returns:
        previous value or null for none
        Throws:
        java.lang.IndexOutOfBoundsException - if index is negative
      • set

        public final V set​(int index,
                           V value)
        Sets the value at the given index, overriding any existing value mapping.
        Returns:
        previous value or null for none
        Throws:
        java.lang.IndexOutOfBoundsException - if index is negative or >= size
      • add

        public final void add​(K key,
                              V value)
        Adds the key/value mapping at the end of the list. Behaves identically to set(size(), key, value).
        Throws:
        java.lang.IndexOutOfBoundsException - if index is negative
      • remove

        public final V remove​(int index)
        Removes the key/value mapping at the given index, or ignored if the index is out of bounds.
        Returns:
        previous value or null for none
      • containsKey

        public final boolean containsKey​(java.lang.Object key)
        Returns whether there is a mapping for the given key.
        Specified by:
        containsKey in interface java.util.Map<K,​V>
        Overrides:
        containsKey in class java.util.AbstractMap<K,​V>
      • getIndexOfKey

        public final int getIndexOfKey​(K key)
        Returns the index of the given key or -1 if there is no such key.
      • get

        public final V get​(java.lang.Object key)
        Returns the value set for the given key or null if there is no such mapping or if the mapping value is null.
        Specified by:
        get in interface java.util.Map<K,​V>
        Overrides:
        get in class java.util.AbstractMap<K,​V>
      • put

        public final V put​(K key,
                           V value)
        Sets the value for the given key, overriding any existing value.
        Specified by:
        put in interface java.util.Map<K,​V>
        Overrides:
        put in class java.util.AbstractMap<K,​V>
        Returns:
        previous value or null for none
      • remove

        public final V remove​(java.lang.Object key)
        Removes the key-value pair of the given key, or ignore if the key cannot be found.
        Specified by:
        remove in interface java.util.Map<K,​V>
        Overrides:
        remove in class java.util.AbstractMap<K,​V>
        Returns:
        previous value or null for none
      • trim

        public final void trim()
        Trims the internal array storage to minimize memory usage.
      • ensureCapacity

        public final void ensureCapacity​(int minCapacity)
        Ensures that the capacity of the internal arrays is at least a given capacity.
      • setDataCapacity

        private void setDataCapacity​(int newDataCapacity)
      • setData

        private void setData​(int dataIndexOfKey,
                             K key,
                             V value)
      • valueAtDataIndex

        private V valueAtDataIndex​(int dataIndex)
      • getDataIndexOfKey

        private int getDataIndexOfKey​(java.lang.Object key)
        Returns the data index of the given key or -2 if there is no such key.
      • removeFromDataIndexOfKey

        private V removeFromDataIndexOfKey​(int dataIndexOfKey)
        Removes the key/value mapping at the given data index of key, or ignored if the index is out of bounds.
      • clear

        public void clear()
        Specified by:
        clear in interface java.util.Map<K,​V>
        Overrides:
        clear in class java.util.AbstractMap<K,​V>
      • containsValue

        public final boolean containsValue​(java.lang.Object value)
        Specified by:
        containsValue in interface java.util.Map<K,​V>
        Overrides:
        containsValue in class java.util.AbstractMap<K,​V>
      • entrySet

        public final java.util.Set<java.util.Map.Entry<K,​V>> entrySet()
        Specified by:
        entrySet in interface java.util.Map<K,​V>
        Specified by:
        entrySet in class java.util.AbstractMap<K,​V>
      • clone

        public ArrayMap<K,​V> clone()
        Overrides:
        clone in class java.util.AbstractMap<K,​V>