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

Class VectorList<E>

java.lang.Object
org.jhotdraw8.icollection.VectorList<E>
Type Parameters:
E - the element type
All Implemented Interfaces:
Serializable, Iterable<E>, ImmutableCollection<E>, ImmutableList<E>, ImmutableSequencedCollection<E>, ReadOnlyCollection<E>, ReadOnlyList<E>, ReadOnlySequencedCollection<E>
public class VectorList<E> extends Object implements ImmutableList<E>, Serializable
Implements the ImmutableList interface using a bit-mapped trie (Vector).

The code has been derived from Vavr Vector.java.

Features:

  • supports up to 231 - 1 elements
  • allows null elements
  • is immutable
  • is thread-safe
  • iterates in the order of the list

Performance characteristics:

  • addLast: O(log₃₂ N)
  • set: O(log₃₂ N)
  • removeAt: O(N)
  • removeFirst,removeLast: O(log₃₂ N)
  • contains: O(N)
  • toMutable: O(1)
  • clone: O(1)
  • iterator creation: O(log₃₂ N)
  • iterator.next: O(1)
  • getFirst, getLast: O(log₃₂ N)
  • reversed: O(N)

References:

For a similar design, see 'Vector.java' in vavr. The internal data structure of this class is licensed from vavr.

Vector.java. Copyright 2023 (c) vavr. MIT License.
github.com
See Also:

  • Constructor Details

    • VectorList

      protected VectorList()
      Constructs a new empty list.

    • VectorList

      protected VectorList(@Nullable Iterable<? extends E> iterable)
      Constructs a new list that contains all the elements of the specified iterable.
      Parameters:
      iterable - an iterable

    • VectorList

      protected VectorList(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 VectorList<E> newInstance(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

    • of

      public static <T> VectorList<T> of()

    • of

      @SafeVarargs public static <T> VectorList<T> of(T... t)

    • ofIterator

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

    • ofStream

      public static <T> VectorList<T> ofStream(Stream<T> stream)

    • copyOf

      public static <T> VectorList<T> copyOf(Iterable<? extends T> iterable)

    • empty

      public <T> VectorList<T> empty()
      Description copied from interface: ImmutableList
      Returns a copy of this list that is empty.
      Specified by:
      empty in interface ImmutableCollection<E>
      Specified by:
      empty in interface ImmutableList<E>
      Specified by:
      empty in interface ImmutableSequencedCollection<E>
      Type Parameters:
      T - the element type of the returned collection
      Returns:
      this list instance if it is already empty, or a different list instance that is empty.

    • add

      public VectorList<E> add(E element)
      Description copied from interface: ImmutableList
      Returns a copy of this list that contains all elements of this list and the specified element appended to the end of the list.
      Specified by:
      add in interface ImmutableCollection<E>
      Specified by:
      add in interface ImmutableList<E>
      Specified by:
      add in interface ImmutableSequencedCollection<E>
      Parameters:
      element - an element
      Returns:
      a different list instance with the element added

    • add

      public VectorList<E> add(int index, E element)
      Description copied from interface: ImmutableList
      Returns a copy of this list that contains all elements of this list and the specified element appended to the end of the list.
      Specified by:
      add in interface ImmutableList<E>
      Parameters:
      index - the insertion index
      element - an element
      Returns:
      a different list instance with the element added

    • addAll

      public VectorList<E> addAll(Iterable<? extends E> c)
      Description copied from interface: ImmutableList
      Returns a copy of this list that contains all elements of this list and all elements of the specified collection appended.
      Specified by:
      addAll in interface ImmutableCollection<E>
      Specified by:
      addAll in interface ImmutableList<E>
      Specified by:
      addAll in interface ImmutableSequencedCollection<E>
      Parameters:
      c - a collection to be added to this list
      Returns:
      a different list instance with the elements added

    • addFirst

      public VectorList<E> addFirst(@Nullable E element)
      Description copied from interface: ImmutableSequencedCollection
      Returns a copy of this collection that contains all elements of this collection and also the specified element as the first element in the iteration order.

      A collection may prevent that the same element can be added more than once.

      If the iteration order is based on an ordering relation of the elements, then the element is only the first in a sequence of elements with the same ordering relation; which is not necessarily the first in the total iteration order.

      Specified by:
      addFirst in interface ImmutableList<E>
      Specified by:
      addFirst in interface ImmutableSequencedCollection<E>
      Parameters:
      element - an element
      Returns:
      this collection instance if it already contains the element as the first in the iteration order, or a different collection instance with the element added as the first in the iteration order

    • addLast

      public VectorList<E> addLast(@Nullable E element)
      Description copied from interface: ImmutableSequencedCollection
      Returns a copy of this collection that contains all elements of this collection and also the specified element as the last element in the iteration order.

      A collection may prevent that the same element can be added more than once.

      If the iteration order is based on an ordering relation of the elements, then the element is only the last in a sequence of elements with the same ordering relation; which is not necessarily the last in the total iteration order.

      Specified by:
      addLast in interface ImmutableList<E>
      Specified by:
      addLast in interface ImmutableSequencedCollection<E>
      Parameters:
      element - an element
      Returns:
      this collection instance if it already contains the element as the last in the iteration order, or a different collection instance with the element added as the last in the iteration order

    • addAll

      public VectorList<E> addAll(int index, Iterable<? extends E> c)
      Description copied from interface: ImmutableList
      Returns a copy of this list that contains all elements of this list and all elements of the specified collection appended.
      Specified by:
      addAll in interface ImmutableList<E>
      Parameters:
      index - the insertion index
      c - a collection to be added to this list
      Returns:
      a different list instance with the elements added

    • readOnlyReversed

      public ReadOnlySequencedCollection<E> readOnlyReversed()
      Description copied from interface: ReadOnlySequencedCollection
      Returns a reversed-order view of this collection. Changes to the underlying collection are visible in the reversed view.
      Specified by:
      readOnlyReversed in interface ReadOnlySequencedCollection<E>
      Returns:
      a reversed-order view of this collection

    • reverse

      public VectorList<E> reverse()
      Description copied from interface: ImmutableList
      Returns a reversed copy of this list.

      This operation may be implemented in O(N).

      Use ReadOnlySequencedCollection.readOnlyReversed() if you only need to iterate in the reversed sequence over this list.

      Specified by:
      reverse in interface ImmutableList<E>
      Returns:
      a reversed copy of this list.

    • remove

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

    • removeAt

      public VectorList<E> removeAt(int index)
      Description copied from interface: ImmutableList
      Returns a copy of this list that contains all elements of this list except the element at the specified index
      Specified by:
      removeAt in interface ImmutableList<E>
      Parameters:
      index - an index
      Returns:
      a different list instance with the element removed

    • removeFirst

      public VectorList<E> removeFirst()
      Description copied from interface: ImmutableSequencedCollection
      Returns a copy of this set that contains all elements of this set except the first.
      Specified by:
      removeFirst in interface ImmutableList<E>
      Specified by:
      removeFirst in interface ImmutableSequencedCollection<E>
      Returns:
      a new set instance with the first element removed

    • removeLast

      public VectorList<E> removeLast()
      Description copied from interface: ImmutableSequencedCollection
      Returns a copy of this set that contains all elements of this set except the last.
      Specified by:
      removeLast in interface ImmutableList<E>
      Specified by:
      removeLast in interface ImmutableSequencedCollection<E>
      Returns:
      a new set instance with the last element removed

    • retainAll

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

    • removeRange

      public VectorList<E> removeRange(int fromIndex, int toIndex)
      Description copied from interface: ImmutableList
      Returns a copy of this list that contains all elements of this list except the elements in the specified range.
      Specified by:
      removeRange in interface ImmutableList<E>
      Parameters:
      fromIndex - from index (inclusive) of the sub-list
      toIndex - to index (exclusive) of the sub-list
      Returns:
      a different list instance with the element removed

    • removeAll

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

    • set

      public VectorList<E> set(int index, E element)
      Description copied from interface: ImmutableList
      Returns a copy of this list that contains all elements of this list and the specified element replaced.
      Specified by:
      set in interface ImmutableList<E>
      Parameters:
      element - an element
      Returns:
      this list instance if it has not changed, or a different list instance with the element changed

    • get

      public E get(int index)
      Description copied from interface: ReadOnlyList
      Returns the element at the specified position in this list.
      Specified by:
      get in interface ReadOnlyList<E>
      Parameters:
      index - the index of the element
      Returns:
      the element

    • readOnlySubList

      public VectorList<E> readOnlySubList(int fromIndex, int toIndex)
      Description copied from interface: ImmutableList
      Returns a copy of this list that contains only the elements in the given index range.
      Specified by:
      readOnlySubList in interface ImmutableList<E>
      Specified by:
      readOnlySubList in interface ReadOnlyList<E>
      Parameters:
      fromIndex - from index (inclusive) of the sub-list
      toIndex - to index (exclusive) of the sub-list
      Returns:
      this list instance if it has not changed, or a different list instance with the element changed

    • 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

    • indexOf

      public int indexOf(Object o, int fromIndex)

    • contains

      public boolean contains(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

    • hashCode

      public int hashCode()
      Description copied from interface: ReadOnlyList
      Returns the hash code value for this list. The hash code is the result of the calculation described in List.hashCode().

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

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

    • toMutable

      public MutableVectorList<E> toMutable()
      Description copied from interface: ImmutableList
      Returns a mutable copy of this list.
      Specified by:
      toMutable in interface ImmutableCollection<E>
      Specified by:
      toMutable in interface ImmutableList<E>
      Returns:
      a mutable copy.

    • iterator

      public Iterator<E> iterator()
      Description copied from interface: ReadOnlyList
      Returns an iterator over elements of type E.
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in interface ReadOnlyCollection<E>
      Specified by:
      iterator in interface ReadOnlyList<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

    • spliterator

      public Spliterator<E> spliterator()
      Description copied from interface: ReadOnlyList
      Returns a spliterator over elements of type E.
      Specified by:
      spliterator in interface Iterable<E>
      Specified by:
      spliterator in interface ReadOnlyList<E>
      Returns:
      an iterator.

    • equals

      public boolean equals(Object obj)
      Description copied from interface: ReadOnlyList
      Compares the specified object with this list for equality.

      Returns true if the given object is also a read-only list and the two lists contain the same elements in the same sequence.

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

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

    • toString

      public String toString()
      Returns a string representation of this list.

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

      Overrides:
      toString in class Object
      Returns:
      a string representation