Package com.github.coderodde.util

Class IndexedLinkedList<E>

java.lang.Object
com.github.coderodde.util.IndexedLinkedList<E>
All Implemented Interfaces:
Serializable, Cloneable, Iterable<E>, Collection<E>, Deque<E>, List<E>, Queue<E>
public class IndexedLinkedList<E> extends Object implements Deque<E>, List<E>, Cloneable, Serializable

This class implements the indexed, heuristic doubly-linked list data structure that runs all the single-element operations in expected \(\mathcal{O}(\sqrt{n})\) time. Under the hood, the actual elements are stored in a doubly-linked list. However, we also maintain a list of so-called "fingers" stored in a random access array. Each finger F contains two data fields:

  • F.node - the actual element node,
  • F.index - the appearance index of F.node in the actual list.

For the list of size \(n\), we maintain \(\bigg \lceil \sqrt{n} \bigg \rceil + 1\) fingers. The rightmost finger in the finger list is a special end-of-list sentinel. It always has F.node = null and F.index = \(n\). The fingers are sorted by their indices. That arrangement allows simpler and faster code in the method that accesses a finger via element index; see IndexedLinkedList.FingerList.getFingerIndexImpl(int). Since number of fingers is \(\sqrt{n}\), and assuming that the fingers are evenly distributed, each finger "covers" \(n / \sqrt{n} = \sqrt{n}\) elements. In order to access an element in the actual list, we first consult the finger list for the index i of the finger fingerArray[i] that is closest to the index of the target element. This runs in \[ \mathcal{O}(\log \sqrt{n}) = \mathcal{O}(\log n^{1/2}) = \mathcal{O}(\frac{1}{2} \log n) = \mathcal{O}(\log n). \] The rest is to "rewind" the closest finger to point to the target element (which requires \(\mathcal{O}(\sqrt{n})\) on evenly distributed finger lis).

Since:
1.6 (Sep 1, 2021)
Version:
1.61 (Sep 26, 2021)
Author:
Rodion "rodde" Efremov
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    final class 
    IndexedLinkedList.BasicIterator
    This class implements a basic iterator over this list.

  • Constructor Summary

    Constructors
    Constructor
    Description
    IndexedLinkedList()
    Constructs an empty list.
    IndexedLinkedList(Collection<? extends E> c)
    Constructs a new list and copies the data in c to it.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(int index, E element)
    Inserts the specified element at the specified position in this list.
    boolean
    add(E e)
    Appends the specified element to the end of this list.
    boolean
    addAll(int index, Collection<? extends E> c)
    Inserts all of the elements in the specified collection into this list, starting at the specified position.
    boolean
    addAll(Collection<? extends E> c)
    Appends all of the elements in the specified collection to the end of this list, in the order they are returned by the specified collection's iterator.
    void
    addFirst(E e)
    Adds the element e before the head of this list.
    void
    addLast(E e)
    Adds the element e after the tail of this list.
    void
    checkInvarant()
    Checks the data structure invariant.
    void
    clear()
    Completely clears this list.
    Object
    clone()
    Returns the clone list with same content as this list.
    boolean
    contains(Object o)
    Returns true only if o is present in this list.
    boolean
    containsAll(Collection<?> c)
    Returns true only if this list contains all the elements mentioned in the c.
    Iterator<E>
    descendingIterator()
    Returns the descending iterator.
    E
    element()
    Returns the first element of this list.
    boolean
    equals(Object o)
    Returns true only if o is an instance of List and has the sane contents as this list.
    E
    get(int index)
    Returns indexth element.
    E
    getFirst()
    Returns the first element of this list.
    E
    getLast()
    Returns the last element of this list.
    int
    hashCode()
    Returns the hash code of this list.
    int
    indexOf(Object obj)
    Returns the index of the leftmost obj, or -1 if obj does not appear in this list.
    boolean
    isEmpty()
    Returns true only if this list is empty.
    Iterator<E>
    iterator()
    Returns the iterator over this list.
    int
    lastIndexOf(Object obj)
    Returns the index of the rightmost obj, or -1 if obj does not appear in this list.
    ListIterator<E>
    listIterator()
    Returns the list iterator pointing to the head element of this list.
    ListIterator<E>
    listIterator(int index)
    Returns the list iterator pointing between list[index - 1] and list[index].
    boolean
    offer(E e)
    Adds e after the tail element of this list.
    boolean
    offerFirst(E e)
    Adds e before the head element of this list.
    boolean
    offerLast(E e)
    Adds e after the tail element of this list.
    void
    optimize()
    Moves all the fingers such that they are evenly distributed.
    E
    peek()
    Takes a look at the first element in this list.
    E
    peekFirst()
    Takes a look at the first element in this list.
    E
    peekLast()
    Takes a look at the last element in this list.
    E
    poll()
    If this list is empty, does nothing else but return null.
    E
    pollFirst()
    If this list is empty, does nothing else but return null.
    E
    pollLast()
    If this list is empty, does nothing else but return null.
    E
    pop()
    Removes the first element and returns it.
    void
    push(E e)
    Adds e before the head of this list.
    E
    remove()
    Removes and returns the first element.
    E
    remove(int index)
    Removes the element residing at the given index.
    boolean
    remove(Object o)
    Removes the leftmost occurrence of o in this list.
    boolean
    removeAll(Collection<?> c)
    Removes from this list all the elements mentioned in c.
    E
    removeFirst()
    Removes the first element from this list.
    boolean
    removeFirstOccurrence(Object o)
    Removes the leftmost occurrence of o.
    boolean
    removeIf(Predicate<? super E> filter)
    Removes from this list all the elements that satisfy the given input predicate.
    E
    removeLast()
    Removes and returns the last element of this list.
    boolean
    removeLastOccurrence(Object o)
    Removes the rightmost occurrence of o.
    void
    replaceAll(UnaryOperator<E> operator)
    Replaces all the elements in this list by applying the given input operator to each of the elements.
    boolean
    retainAll(Collection<?> c)
    Remove all the elements that do not appear in c.
    E
    set(int index, E element)
    Sets the element at index index to element and returns the old element.
    int
    size()
    Returns the number of elements in this list.
    void
    sort(Comparator<? super E> c)
    Sorts stably this list into non-descending order.
    Spliterator<E>
    spliterator()
    Returns the spliterator over this list.
    List<E>
    subList(int fromIndex, int toIndex)
    Returns a sublist view list[fromIndex, fromIndex + 1, ..., toIndex - 1.
    Object[]
    toArray()
    Returns the Object array containing all the elements in this list, in the same order as they appear in the list.
    <T> T[]
    toArray(IntFunction<T[]> generator)
    Generates the array containing all the elements in this list.
    <T> T[]
    toArray(T[] a)
    If a is sufficiently large, returns the same array holding all the contents of this list.
    String
    toString()
    Returns the string representation of this list, listing all the elements.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.util.Collection

    parallelStream, stream

    Methods inherited from interface java.lang.Iterable

    forEach

  • Constructor Details

    • IndexedLinkedList

      public IndexedLinkedList()
      Constructs an empty list.

    • IndexedLinkedList

      public IndexedLinkedList(Collection<? extends E> c)
      Constructs a new list and copies the data in c to it. Runs in \(\mathcal{O}(m + \sqrt{m})\) time, where \(m = |c|\).
      Parameters:
      c - the collection to copy.

  • Method Details

    • add

      public boolean add(E e)
      Appends the specified element to the end of this list. Runs in amortized constant time.

      This method is equivalent to addLast(E).

      Specified by:
      add in interface Collection<E>
      Specified by:
      add in interface Deque<E>
      Specified by:
      add in interface List<E>
      Specified by:
      add in interface Queue<E>
      Parameters:
      e - element to be appended to this list.
      Returns:
      true (as specified by Collection.add(E)).

    • add

      public void add(int index, E element)
      Inserts the specified element at the specified position in this list. The affected finger indices will be incremented by one. A finger F is affected, if F.index >= index. Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      add in interface List<E>
      Parameters:
      index - index at which the specified element is to be inserted.
      element - element to be inserted.
      Throws:
      IndexOutOfBoundsException

    • addAll

      public boolean addAll(Collection<? extends E> c)
      Appends all of the elements in the specified collection to the end of this list, in the order they are returned by the specified collection's iterator. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this list, and it's nonempty.) Runs in \(\mathcal{O}(m + \sqrt{m + n})\), where \(m = |c|\) and \(n\) is the size of this list.
      Specified by:
      addAll in interface Collection<E>
      Specified by:
      addAll in interface Deque<E>
      Specified by:
      addAll in interface List<E>
      Parameters:
      c - collection containing elements to be added to this list.
      Returns:
      true if this list changed as a result of the call.
      Throws:
      NullPointerException - if the specified collection is null.

    • addAll

      public boolean addAll(int index, Collection<? extends E> c)
      Inserts all of the elements in the specified collection into this list, starting at the specified position. For each finger F with F.index >= index will increment F.index by 1. Runs in \(\mathcal{O}(m + \sqrt{m + n})\), where \(m = |c|\) and \(n\) is the size of this list.
      Specified by:
      addAll in interface List<E>
      Parameters:
      index - index at which to insert the first element from the specified collection.
      c - collection containing elements to be added to this list.
      Returns:
      true if this list changed as a result of the call.
      Throws:
      IndexOutOfBoundsException
      NullPointerException - if the specified collection is null

    • addFirst

      public void addFirst(E e)
      Adds the element e before the head of this list. Runs in Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      addFirst in interface Deque<E>
      Parameters:
      e - the element to add.

    • addLast

      public void addLast(E e)
      Adds the element e after the tail of this list. Runs in constant time.
      Specified by:
      addLast in interface Deque<E>
      Parameters:
      e - the element to add.

    • checkInvarant

      public void checkInvarant()
      Checks the data structure invariant. Throws IllegalStateException on invalid invariant. The invariant is valid if:
      1. All the fingers in the finger list are sorted by indices.
      2. There is no duplicate indices.
      3. The index of the leftmost finger is no less than zero.
      4. There must be an end-of-list sentinel finger F, such that F.index = size of linked list and F.node is null.
      5. Each finger F points to the ith linked list node, where i = F.index.
      Runs always in linear time.

    • clear

      public void clear()
      Completely clears this list.
      Specified by:
      clear in interface Collection<E>
      Specified by:
      clear in interface List<E>

    • clone

      public Object clone()
      Returns the clone list with same content as this list.
      Overrides:
      clone in class Object
      Returns:
      the clone list.

    • contains

      public boolean contains(Object o)
      Returns true only if o is present in this list. Runs in worst-case linear time.
      Specified by:
      contains in interface Collection<E>
      Specified by:
      contains in interface Deque<E>
      Specified by:
      contains in interface List<E>
      Parameters:
      o - the query object.

    • containsAll

      public boolean containsAll(Collection<?> c)
      Returns true only if this list contains all the elements mentioned in the c. Runs in Runs in \(\mathcal{O}(mn)\) time, where \(m = |c|\).
      Specified by:
      containsAll in interface Collection<E>
      Specified by:
      containsAll in interface List<E>
      Parameters:
      c - the query object collection.
      Returns:
      true only if this list contains all the elements in c, or false otherwise.

    • descendingIterator

      public Iterator<E> descendingIterator()
      Returns the descending iterator.
      Specified by:
      descendingIterator in interface Deque<E>
      Returns:
      the descending iterator pointing to the tail of this list.

    • element

      public E element()
      Returns the first element of this list. Runs in constant time.
      Specified by:
      element in interface Deque<E>
      Specified by:
      element in interface Queue<E>
      Returns:
      the first element of this list.
      Throws:
      NoSuchElementException - if this list is empty.

    • equals

      public boolean equals(Object o)
      Returns true only if o is an instance of List and has the sane contents as this list. Runs in worst-case linear time.
      Specified by:
      equals in interface Collection<E>
      Specified by:
      equals in interface List<E>
      Overrides:
      equals in class Object
      Returns:
      true only if o is a list with the same contents as this list.

    • get

      public E get(int index)
      Returns indexth element. Runs in worst-case Runs in worst-case \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      get in interface List<E>
      Returns:
      indexth element.
      Throws:
      IndexOutOfBoundsException - if the index is out of range 0, 1, ..., size - 1, or if this list is empty.

    • getFirst

      public E getFirst()
      Returns the first element of this list. Runs in constant time.
      Specified by:
      getFirst in interface Deque<E>
      Returns:
      the first element of this list.
      Throws:
      NoSuchElementException - if this list is empty.

    • getLast

      public E getLast()
      Returns the last element of this list. Runs in constant time.
      Specified by:
      getLast in interface Deque<E>
      Returns:
      the last element of this list.
      Throws:
      NoSuchElementException - if this list is empty.

    • hashCode

      public int hashCode()
      Returns the hash code of this list. Runs in linear time.
      Specified by:
      hashCode in interface Collection<E>
      Specified by:
      hashCode in interface List<E>
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this list.

    • indexOf

      public int indexOf(Object obj)
      Returns the index of the leftmost obj, or -1 if obj does not appear in this list. Runs in worst-case linear time.
      Specified by:
      indexOf in interface List<E>
      Returns:
      the index of the leftmost obj, or -1 if obj does not appear in this list.
      See Also:

    • isEmpty

      public boolean isEmpty()
      Returns true only if this list is empty.
      Specified by:
      isEmpty in interface Collection<E>
      Specified by:
      isEmpty in interface List<E>
      Returns:
      true only if this list is empty.

    • iterator

      public Iterator<E> iterator()
      Returns the iterator over this list.
      Specified by:
      iterator in interface Collection<E>
      Specified by:
      iterator in interface Deque<E>
      Specified by:
      iterator in interface Iterable<E>
      Specified by:
      iterator in interface List<E>
      Returns:
      the iterator over this list.

    • lastIndexOf

      public int lastIndexOf(Object obj)
      Returns the index of the rightmost obj, or -1 if obj does not appear in this list. Runs in worst-case linear time.
      Specified by:
      lastIndexOf in interface List<E>
      Returns:
      the index of the rightmost obj, or -1 if obj does not appear in this list.
      See Also:

    • listIterator

      public ListIterator<E> listIterator()
      Returns the list iterator pointing to the head element of this list.
      Specified by:
      listIterator in interface List<E>
      Returns:
      the list iterator.
      See Also:

    • listIterator

      public ListIterator<E> listIterator(int index)
      Returns the list iterator pointing between list[index - 1] and list[index].
      Specified by:
      listIterator in interface List<E>
      Parameters:
      index - the gap index. The value of zero will point before the head element.
      Returns:
      the list iterator pointing to the indexth gap.

    • offer

      public boolean offer(E e)
      Adds e after the tail element of this list. Runs in constant time.
      Specified by:
      offer in interface Deque<E>
      Specified by:
      offer in interface Queue<E>
      Parameters:
      e - the element to add.
      Returns:
      always true.

    • offerFirst

      public boolean offerFirst(E e)
      Adds e before the head element of this list. Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      offerFirst in interface Deque<E>
      Parameters:
      e - the element to add.
      Returns:
      always true.

    • offerLast

      public boolean offerLast(E e)
      Adds e after the tail element of this list. Runs in constant time.
      Specified by:
      offerLast in interface Deque<E>
      Parameters:
      e - the element to add.
      Returns:
      always true.

    • optimize

      public void optimize()
      Moves all the fingers such that they are evenly distributed. Runs in linear time.

    • peek

      public E peek()
      Takes a look at the first element in this list.
      Specified by:
      peek in interface Deque<E>
      Specified by:
      peek in interface Queue<E>
      Returns:
      the head element or null if this list is empty.

    • peekFirst

      public E peekFirst()
      Takes a look at the first element in this list.
      Specified by:
      peekFirst in interface Deque<E>
      Returns:
      the head element or null if this list is empty.

    • peekLast

      public E peekLast()
      Takes a look at the last element in this list.
      Specified by:
      peekLast in interface Deque<E>
      Returns:
      the tail element or null if this list is empty.

    • poll

      public E poll()
      If this list is empty, does nothing else but return null. Otherwise, removes the first element and returns it. Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      poll in interface Deque<E>
      Specified by:
      poll in interface Queue<E>
      Returns:
      the first element (which was removed due to the call to this method), or null if the list is empty.

    • pollFirst

      public E pollFirst()
      If this list is empty, does nothing else but return null. Otherwise, removes the first element and returns it. Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      pollFirst in interface Deque<E>
      Returns:
      the first element (which was removed due to the call to this method), or null if the list is empty.

    • pollLast

      public E pollLast()
      If this list is empty, does nothing else but return null. Otherwise, removes the last element and returns it. Runs in constant time.
      Specified by:
      pollLast in interface Deque<E>
      Returns:
      the last element (which was removed due to the call to this method), or null if the list is empty.

    • pop

      public E pop()
      Removes the first element and returns it. Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      pop in interface Deque<E>
      Returns:
      the first element.
      Throws:
      NoSuchElementException - if the list is empty.

    • push

      public void push(E e)
      Adds e before the head of this list. Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      push in interface Deque<E>

    • remove

      public E remove()
      Removes and returns the first element. Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      remove in interface Deque<E>
      Specified by:
      remove in interface Queue<E>
      Returns:
      the head element of this list.
      Throws:
      NoSuchElementException - if this list is empty.

    • remove

      public boolean remove(Object o)
      Removes the leftmost occurrence of o in this list. Runs in worst- case Runs in \(\mathcal{O}(n + \sqrt{n})\) time. \(\mathcal{O}(n)\) for iterating the list and \(\mathcal{O}(\sqrt{n})\) time for fixing the fingers.
      Specified by:
      remove in interface Collection<E>
      Specified by:
      remove in interface Deque<E>
      Specified by:
      remove in interface List<E>
      Returns:
      true only if o was located in this list and, thus, removed.

    • remove

      public E remove(int index)
      Removes the element residing at the given index. Runs in worst-case \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      remove in interface List<E>
      Parameters:
      index - the index of the element to remove.
      Returns:
      the removed element. (The one that resided at the index index.)

    • removeAll

      public boolean removeAll(Collection<?> c)
      Removes from this list all the elements mentioned in c. Runs in \(\mathcal{O}(n\sqrt{n} + fn)\) time, where \(\mathcal{O}(f)\) is the time of checking for element inclusion in c.
      Specified by:
      removeAll in interface Collection<E>
      Specified by:
      removeAll in interface List<E>
      Parameters:
      c - the collection holding all the elements to remove.
      Returns:
      true only if at least one element in c was located and removed from this list.

    • removeFirst

      public E removeFirst()
      Removes the first element from this list. Runs in \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      removeFirst in interface Deque<E>
      Returns:
      the first element.

    • removeFirstOccurrence

      public boolean removeFirstOccurrence(Object o)
      Removes the leftmost occurrence of o. Runs in worst-case \(\mathcal{O}(n)\) time.
      Specified by:
      removeFirstOccurrence in interface Deque<E>
      Returns:
      true only if o was present in the list and was successfully removed.

    • removeIf

      public boolean removeIf(Predicate<? super E> filter)
      Removes from this list all the elements that satisfy the given input predicate. Runs in \(\mathcal{O}(n\sqrt{n})\) time.
      Specified by:
      removeIf in interface Collection<E>
      Parameters:
      filter - the filtering predicate.
      Returns:
      true only if at least one element was removed.

    • removeLast

      public E removeLast()
      Removes and returns the last element of this list. Runs in constant time.
      Specified by:
      removeLast in interface Deque<E>
      Returns:
      the removed head element.
      Throws:
      NoSuchElementException - if this list is empty.

    • removeLastOccurrence

      public boolean removeLastOccurrence(Object o)
      Removes the rightmost occurrence of o. Runs in \(\mathcal{O}(n)\) time.
      Specified by:
      removeLastOccurrence in interface Deque<E>
      Parameters:
      o - the object to remove.
      Returns:
      true only if an element was actually removed.

    • replaceAll

      public void replaceAll(UnaryOperator<E> operator)
      Replaces all the elements in this list by applying the given input operator to each of the elements. Runs in linear time.
      Specified by:
      replaceAll in interface List<E>
      Parameters:
      operator - the operator mapping one element to another.

    • retainAll

      public boolean retainAll(Collection<?> c)
      Remove all the elements that do not appear in c. Runs in worst-case \(\mathcal{O}(nf + n\sqrt{n})\) time, where the inclusion check is run in \(\mathcal{O}(f)\) time.
      Specified by:
      retainAll in interface Collection<E>
      Specified by:
      retainAll in interface List<E>
      Parameters:
      c - the collection of elements to retain.
      Returns:
      true only if at least one element was removed.

    • set

      public E set(int index, E element)
      Sets the element at index index to element and returns the old element. Runs in worst-case \(\mathcal{O}(\sqrt{n})\) time.
      Specified by:
      set in interface List<E>
      Parameters:
      index - the target index.
      element - the element to set.
      Returns:
      the previous element at the given index.

    • size

      public int size()
      Returns the number of elements in this list.
      Specified by:
      size in interface Collection<E>
      Specified by:
      size in interface Deque<E>
      Specified by:
      size in interface List<E>
      Returns:
      the size of this list.

    • sort

      public void sort(Comparator<? super E> c)
      Sorts stably this list into non-descending order. Runs in \(\mathcal{O}(n \log n)\).
      Specified by:
      sort in interface List<E>
      Parameters:
      c - the element comparator.

    • spliterator

      public Spliterator<E> spliterator()
      Returns the spliterator over this list.
      Specified by:
      spliterator in interface Collection<E>
      Specified by:
      spliterator in interface Iterable<E>
      Specified by:
      spliterator in interface List<E>

    • subList

      public List<E> subList(int fromIndex, int toIndex)
      Returns a sublist view list[fromIndex, fromIndex + 1, ..., toIndex - 1.
      Specified by:
      subList in interface List<E>
      Parameters:
      fromIndex - the smallest index, inclusive.
      toIndex - the largest index, exclusive.
      Returns:
      the sublist view.

    • toArray

      public Object[] toArray()
      Returns the Object array containing all the elements in this list, in the same order as they appear in the list.
      Specified by:
      toArray in interface Collection<E>
      Specified by:
      toArray in interface List<E>
      Returns:
      the list contents in an Object array.

    • toArray

      public <T> T[] toArray(IntFunction<T[]> generator)
      Generates the array containing all the elements in this list.
      Specified by:
      toArray in interface Collection<E>
      Type Parameters:
      T - the array component type.
      Parameters:
      generator - the generator function.
      Returns:
      the list contents in an array with component type of T.

    • toArray

      public <T> T[] toArray(T[] a)
      If a is sufficiently large, returns the same array holding all the contents of this list. Also, if a is larger than the input array, sets a[s] = null, where s is the size of this list. However, if a is smaller than this list, allocates a new array of the same length, populates it with the list contents and returns it.
      Specified by:
      toArray in interface Collection<E>
      Specified by:
      toArray in interface List<E>
      Type Parameters:
      T - the element type.
      Parameters:
      a - the input array.
      Returns:
      an array holding the contents of this list.

    • toString

      public String toString()
      Returns the string representation of this list, listing all the elements.
      Overrides:
      toString in class Object
      Returns:
      the string representation of this list.