Module org.jhotdraw8.icollection
Package org.jhotdraw8.icollection

Class ChampMap<K,V>

java.lang.Object
org.jhotdraw8.icollection.ChampMap<K,V>
Type Parameters:
K - the key type
V - the value type
All Implemented Interfaces:
Serializable, Iterable<Map.Entry<K,V>>, ImmutableMap<K,V>, ReadOnlyMap<K,V>
public class ChampMap<K,V> extends Object implements ImmutableMap<K,V>, Serializable
Implements the ImmutableMap interface using a Compressed Hash-Array Mapped Prefix-tree (CHAMP).

Features:

  • supports up to 231 - 1 entries
  • allows null keys and null values
  • is immutable
  • is thread-safe
  • does not guarantee a specific iteration order

Performance characteristics:

  • put: O(log₃₂ N)
  • remove: O(log₃₂ N)
  • containsKey: O(log₃₂ N)
  • toMutable: O(1) + O(log₃₂ N) distributed across subsequent updates in the mutable copy
  • clone: O(1)
  • iterator.next(): O(1)

Implementation details:

This map performs read and write operations of single elements in O(log₃₂ N) time, and in O(log₃₂ N) space.

The CHAMP trie contains nodes that may be shared with other maps.

If a write operation is performed on a node, then this map creates a copy of the node and of all parent nodes up to the root (copy-path-on-write).

This map can create a mutable copy of itself in O(1) time and O(1) space using method toMutable(). The mutable copy shares its nodes with this map, until it has gradually replaced the nodes with exclusively owned nodes.

All operations on this map can be performed concurrently, without a need for synchronisation.

The immutable version of this map extends from the non-public class ChampBitmapIndexNode. This design safes 16 bytes for every instance, and reduces the number of redirections for finding an element in the collection by 1.

References:

Portions of the code in this class has been derived from 'The Capsule Hash Trie Collections Library'.

Michael J. Steindorfer (2017). Efficient Immutable Collections.
michael.steindorfer.name
The Capsule Hash Trie Collections Library.
Copyright (c) Michael Steindorfer. BSD-2-Clause License
github.com
See Also:

  • Constructor Details

    • ChampMap

      protected ChampMap(@NonNull PrivateData privateData)
      Creates a new instance with the provided privateData data object.

      This constructor is intended to be called from a constructor of the subclass, that is called from method newInstance(PrivateData).

      Parameters:
      privateData - an privateData data object

  • Method Details

    • newInstance

      protected @NonNull ChampMap<K,V> newInstance(@NonNull PrivateData privateData)
      Creates a new instance with the provided privateData object as its internal data structure.

      Subclasses must override this method, and return a new instance of their subclass!

      Parameters:
      privateData - the internal data structure needed by this class for creating the instance.
      Returns:
      a new instance of the subclass

    • characteristics

      public int characteristics()
      Description copied from interface: ReadOnlyMap
      Returns the spliterator characteristics of the key set. This implementation returns Spliterator.SIZED|Spliterator.DISTINCT.
      Specified by:
      characteristics in interface ReadOnlyMap<K,V>
      Returns:
      characteristics.

    • copyOf

      public static <K, V> @NonNull ChampMap<K,V> copyOf(@NonNull Iterable<? extends Map.Entry<? extends K,? extends V>> c)
      Returns an immutable copy of the provided map.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      c - a map
      Returns:
      an immutable copy

    • copyOf

      public static <K, V> @NonNull ChampMap<K,V> copyOf(@NonNull Map<? extends K,? extends V> map)
      Returns an immutable copy of the provided map.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - a map
      Returns:
      an immutable copy

    • of

      public static <K, V> @NonNull ChampMap<K,V> of()
      Returns an empty immutable map.
      Type Parameters:
      K - the key type
      V - the value type
      Returns:
      an empty immutable map

    • clear

      public @NonNull ChampMap<K,V> clear()
      Returns a copy of this map that is empty.
      Specified by:
      clear in interface ImmutableMap<K,V>
      Returns:
      this set instance if it is already empty, or a different set instance that is empty.

    • containsKey

      public boolean containsKey(@Nullable Object o)
      Returns true if this map contains a entry for the specified key.
      Specified by:
      containsKey in interface ReadOnlyMap<K,V>
      Parameters:
      o - a key
      Returns:
      true if this map contains a entry for the specified key

    • equals

      public boolean equals(@Nullable Object other)
      Description copied from interface: ReadOnlyMap
      Compares the specified object with this map for equality.

      Returns true if the given object is also a read-only map and the two maps represent the same entries, ignorig the sequence of the map entries.

      Specified by:
      equals in interface ReadOnlyMap<K,V>
      Overrides:
      equals in class Object
      Parameters:
      other - an object
      Returns:
      true if the object is equal to this map

    • get

      public @Nullable V get(Object o)
      Description copied from interface: ReadOnlyMap
      Returns the value to which the key is mapped, or null if this map contains no entry for the key.
      Specified by:
      get in interface ReadOnlyMap<K,V>
      Parameters:
      o - a key
      Returns:
      the mapped value or null

    • hashCode

      public int hashCode()
      Description copied from interface: ReadOnlyMap
      Returns the hash code value for this map. The hash code is the sum of the hash code of its entries.
      Specified by:
      hashCode in interface ReadOnlyMap<K,V>
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value for this map
      See Also:

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: ReadOnlyMap
      Returns true if this map contains no entries.
      Specified by:
      isEmpty in interface ReadOnlyMap<K,V>
      Returns:
      true if empty

    • iterator

      public @NonNull Iterator<Map.Entry<K,V>> iterator()
      Description copied from interface: ReadOnlyMap
      Returns an iterator over the entries contained in this map.
      Specified by:
      iterator in interface Iterable<K>
      Specified by:
      iterator in interface ReadOnlyMap<K,V>
      Returns:
      an iterator

    • maxSize

      public int maxSize()
      Description copied from interface: ImmutableMap
      Returns the maximal number of entries that this map type can hold
      Specified by:
      maxSize in interface ImmutableMap<K,V>
      Returns:
      the maximal size

    • put

      public @NonNull ChampMap<K,V> put(@NonNull K key, @Nullable V value)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with the specified entry added or updated.
      Specified by:
      put in interface ImmutableMap<K,V>
      Parameters:
      key - the key of the entry
      value - the value of the entry
      Returns:
      this map instance if it already contains the same entry, or a different map instance with the entry added or updated

    • putAll

      public @NonNull ChampMap<K,V> putAll(@NonNull Map<? extends K,? extends V> m)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with entries from the specified map added or updated.
      Specified by:
      putAll in interface ImmutableMap<K,V>
      Parameters:
      m - another map
      Returns:
      this map instance if it already contains the same entries, or a different map instance with the entries added or updated

    • putAll

      public @NonNull ChampMap<K,V> putAll(@NonNull Iterable<? extends Map.Entry<? extends K,? extends V>> c)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with entries from the specified map added or updated.
      Specified by:
      putAll in interface ImmutableMap<K,V>
      Parameters:
      c - another map
      Returns:
      this map instance if it already contains the same entries, or a different map instance with the entries added or updated

    • remove

      public @NonNull ChampMap<K,V> remove(@NonNull K key)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map with the specified entry removed.
      Specified by:
      remove in interface ImmutableMap<K,V>
      Parameters:
      key - the key of the entry
      Returns:
      this map instance if it already does not contain the entry, or a different map instance with the entry removed

    • removeAll

      public @NonNull ChampMap<K,V> removeAll(@NonNull Iterable<? extends K> c)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains all entries of this map except the entries of the specified collection.
      Specified by:
      removeAll in interface ImmutableMap<K,V>
      Parameters:
      c - a collection with keys of entries to be removed from this map
      Returns:
      this map instance if it already does not contain the entries, or a different map instance with the entries removed

    • retainAll

      public @NonNull ChampMap<K,V> retainAll(@NonNull Iterable<? extends K> c)
      Description copied from interface: ImmutableMap
      Returns a copy of this map that contains only entries that are in this map and in the specified collection.
      Specified by:
      retainAll in interface ImmutableMap<K,V>
      Parameters:
      c - a collection with keys of entries to be retained in this map
      Returns:
      this map instance if it has not changed, or a different map instance with entries removed

    • readOnlyKeySet

      public @NonNull ReadOnlySet<K> readOnlyKeySet()
      Description copied from interface: ReadOnlyMap
      Returns a ReadOnlySet view to the keys contained in this map.
      Specified by:
      readOnlyKeySet in interface ReadOnlyMap<K,V>
      Returns:
      a read-only view

    • size

      public int size()
      Description copied from interface: ReadOnlyMap
      Returns the number of entries contained in this map..
      Specified by:
      size in interface ReadOnlyMap<K,V>
      Returns:
      the number of entries

    • spliterator

      public @NonNull Spliterator<Map.Entry<K,V>> spliterator()
      Description copied from interface: ReadOnlyMap
      Returns a spliterator over the entries contained in this map.
      Specified by:
      spliterator in interface Iterable<K>
      Specified by:
      spliterator in interface ReadOnlyMap<K,V>
      Returns:
      a spliterator

    • toMutable

      public @NonNull MutableChampMap<K,V> toMutable()
      Creates a mutable copy of this map.
      Specified by:
      toMutable in interface ImmutableMap<K,V>
      Returns:
      a mutable CHAMP map

    • asMap

      public @NonNull MutableChampMap<K,V> asMap()
      Description copied from interface: ReadOnlyMap
      Wraps this map in the Map interface - without copying.
      Specified by:
      asMap in interface ReadOnlyMap<K,V>
      Returns:
      the wrapped map

    • toString

      public @NonNull String toString()
      Returns a string representation of this map.

      The string representation is consistent with the one produced by AbstractMap.toString().

      Overrides:
      toString in class Object
      Returns:
      a string representation