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

Class ChampSet<E>

java.lang.Object
org.jhotdraw8.icollection.ChampSet<E>
Type Parameters:
E - the element type
All Implemented Interfaces:
Serializable, Iterable<E>, ImmutableCollection<E>, ImmutableSet<E>, ReadOnlyCollection<E>, ReadOnlySet<E>
public class ChampSet<E> extends Object implements ImmutableSet<E>, Serializable
Implements the ImmutableSet interface using a Compressed Hash-Array Mapped Prefix-tree (CHAMP).

Features:

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

Performance characteristics:

  • add: O(log₃₂ N)
  • remove: O(log₃₂ N
  • contains: 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 set 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 sets.

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

This set 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 set, until it has gradually replaced the nodes with exclusively owned nodes.

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

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

    • ChampSet

      protected ChampSet(@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 ChampSet<E> 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

    • copyOf

      public static <E> @NonNull ChampSet<E> copyOf(@NonNull Iterable<? extends E> c)
      Returns an immutable set that contains the provided elements.
      Type Parameters:
      E - the element type
      Parameters:
      c - an iterable
      Returns:
      an immutable set of the provided elements

    • of

      public static <E> @NonNull ChampSet<E> of()
      Returns an empty immutable set.
      Type Parameters:
      E - the element type
      Returns:
      an empty immutable set

    • ofIterator

      public static <T> ChampSet<T> ofIterator(Iterator<T> iterator)

    • of

      @SafeVarargs public static <E> @NonNull ChampSet<E> of(@NonNull E @Nullable ... elements)
      Returns an immutable set that contains the provided elements.
      Type Parameters:
      E - the element type
      Parameters:
      elements - elements
      Returns:
      an immutable set of the provided elements

    • add

      public @NonNull ChampSet<E> add(@Nullable E element)
      Description copied from interface: ImmutableSet
      Returns a copy of this set that contains all elements of this set and also the specified element.
      Specified by:
      add in interface ImmutableCollection<E>
      Specified by:
      add in interface ImmutableSet<E>
      Parameters:
      element - an element
      Returns:
      this set instance if it already contains the element, or a different set instance with the element added

    • addAll

      public @NonNull ChampSet<E> addAll(@NonNull Iterable<? extends E> c)
      Description copied from interface: ImmutableSet
      Returns a copy of this set that contains all elements of this set and also all elements of the specified collection.
      Specified by:
      addAll in interface ImmutableCollection<E>
      Specified by:
      addAll in interface ImmutableSet<E>
      Parameters:
      c - a collection to be added to this set
      Returns:
      this set instance if it already contains the elements, or a different set instance with the elements added

    • empty

      public <T> @NonNull ChampSet<T> empty()
      Returns an empty set instance that has the specified element type.
      Specified by:
      empty in interface ImmutableCollection<E>
      Specified by:
      empty in interface ImmutableSet<E>
      Type Parameters:
      T - the element type of the returned set
      Returns:
      an empty set of the specified element type.

    • contains

      public boolean contains(@Nullable Object o)
      Description copied from interface: ReadOnlyCollection
      Returns true if this collection contains the specified object.
      Specified by:
      contains in interface ReadOnlyCollection<E>
      Parameters:
      o - an object
      Returns:
      true if this collection contains the specified object

    • equals

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

      Returns true if the given object is also a read-only set and the two sets contain the same elements, ignoring the sequence of the elements.

      Implementations of this method should use ReadOnlySet.setEquals(org.jhotdraw8.icollection.readonly.ReadOnlySet<E>, java.lang.Object).

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

    • hashCode

      public int hashCode()
      Description copied from interface: ReadOnlySet
      Returns the hash code value for this set. The hash code is the sum of the hash code of its elements.

      Implementations of this method should use ReadOnlySet.iteratorToHashCode(java.util.Iterator<E>).

      Specified by:
      hashCode in interface ReadOnlySet<E>
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value for this set
      See Also:

    • iterator

      public @NonNull Iterator<E> iterator()
      Description copied from interface: ReadOnlyCollection
      Returns an iterator over the elements in this collection.
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in interface ReadOnlyCollection<E>
      Returns:
      an iterator

    • maxSize

      public int maxSize()
      Description copied from interface: ImmutableCollection
      Returns the maximal number of elements that this collection type can hold
      Specified by:
      maxSize in interface ImmutableCollection<E>
      Returns:
      the maximal size

    • remove

      public @NonNull ChampSet<E> remove(@NonNull E key)
      Description copied from interface: ImmutableSet
      Returns a copy of this set that contains all elements of this set except the specified element.
      Specified by:
      remove in interface ImmutableCollection<E>
      Specified by:
      remove in interface ImmutableSet<E>
      Parameters:
      key - an element
      Returns:
      this set instance if it already does not contain the element, or a different set instance with the element removed

    • removeAll

      public @NonNull ChampSet<E> removeAll(@NonNull Iterable<?> c)
      Description copied from interface: ImmutableSet
      Returns a copy of this set that contains all elements of this set except the elements of the specified collection.
      Specified by:
      removeAll in interface ImmutableCollection<E>
      Specified by:
      removeAll in interface ImmutableSet<E>
      Parameters:
      c - a collection with elements to be removed from this set
      Returns:
      this set instance if it already does not contain the elements, or a different set instance with the elements removed

    • retainAll

      public @NonNull ChampSet<E> retainAll(@NonNull Iterable<?> c)
      Description copied from interface: ImmutableSet
      Returns a copy of this set that contains only elements that are in this set and in the specified collection.
      Specified by:
      retainAll in interface ImmutableCollection<E>
      Specified by:
      retainAll in interface ImmutableSet<E>
      Parameters:
      c - a collection with elements to be retained in this set
      Returns:
      this set instance if it has not changed, or a different set instance with elements removed

    • size

      public int size()
      Description copied from interface: ReadOnlyCollection
      Returns the size of the collection.
      Specified by:
      size in interface ReadOnlyCollection<E>
      Returns:
      the size

    • spliterator

      public @NonNull Spliterator<E> spliterator()
      Specified by:
      spliterator in interface Iterable<E>

    • toMutable

      public @NonNull MutableChampSet<E> toMutable()
      Description copied from interface: ImmutableSet
      Returns a mutable copy of this set.
      Specified by:
      toMutable in interface ImmutableCollection<E>
      Specified by:
      toMutable in interface ImmutableSet<E>
      Returns:
      a mutable copy.

    • toString

      public @NonNull String toString()
      Overrides:
      toString in class Object