Package com.globalmentor.collections.iterators

Class AbstractListIterator<I,E>

java.lang.Object
com.globalmentor.collections.iterators.AbstractListIterator<I,E>
Type Parameters:
I - The type of item returned by the iterator, which may or may not be the type of element contained in the list.
E - The type of element contained in the list.
All Implemented Interfaces:
Iterator<I>, ListIterator<I>
Direct Known Subclasses:
DefaultListIterator
public abstract class AbstractListIterator<I,E> extends Object implements ListIterator<I>
A default list iterator that can iterate over a given list. The iterator provides a way to return only a subset of list items by overriding the isIncluded(int) method. The results of this iterator are undefined if the underlying list is modified. Every concrete subclass must call updateIncludedIndexes() after superclass initialization has taken place.
Author:
Garret Wilson

  • Constructor Summary

    Constructors
    Constructor
    Description
    AbstractListIterator(List<E> list)
    List constructor starting at the first index.
    AbstractListIterator(List<E> list, int index)
    List and index constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(I object)
    Inserts the specified element into the list.
    protected abstract void
    addItem(int index, I item)
    Inserts an element at the given position in the list.
    protected abstract I
    getItem(int index)
    Retrieves an item representing the element at the given position in the list.
    protected final List<E>
    getList()
     
    protected int
    getNextIncludedIndex(int index)
    Determines the next index to be included after the given index.
    protected int
    getPreviousIncludedIndex(int index)
    Determines the previous index to be included before the given index.
    boolean
    hasNext()
     
    boolean
    hasPrevious()
     
    protected abstract boolean
    isIncluded(int index)
    Determines whether the item at the given index should be included.
    I
    next()
    Returns the next element in the list.
    int
    nextIndex()
     
    I
    previous()
    Returns the previous element in the list.
    int
    previousIndex()
     
    void
    remove()
    Removes from the list the last element that was returned by next() or previous().
    void
    set(I object)
    Replaces the last element returned by next() or previous() with the specified element.
    protected abstract I
    setItem(int index, I item)
    Sets the element at the given position in the list.
    protected void
    updateIncludedIndexes()
    Ensures that the current next and previous indexes are included.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface java.util.Iterator

    forEachRemaining

  • Constructor Details

    • AbstractListIterator

      public AbstractListIterator(List<E> list)
      List constructor starting at the first index.
      Parameters:
      list - The list over which to iterate.
      Throws:
      NullPointerException - if the given list is null.

    • AbstractListIterator

      public AbstractListIterator(List<E> list, int index)
      List and index constructor.
      Parameters:
      list - The list over which to iterate.
      index - The index of first value to be returned from the list iterator (by a call to the next() method).
      Throws:
      NullPointerException - if the given list is null.
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

  • Method Details

    • getList

      protected final List<E> getList()
      Returns:
      The list over which to iterate.

    • updateIncludedIndexes

      protected void updateIncludedIndexes()
      Ensures that the current next and previous indexes are included. This method must be called whenever the indexes need to be recalculated, such as after the iterator is initialized.

    • getNextIncludedIndex

      protected int getNextIncludedIndex(int index)
      Determines the next index to be included after the given index.
      Parameters:
      index - The index, which may be -1, before the next index to be included.
      Returns:
      The index of the next item to be included after the given index, or List.size() if there is no next index.
      See Also:

    • getPreviousIncludedIndex

      protected int getPreviousIncludedIndex(int index)
      Determines the previous index to be included before the given index.
      Parameters:
      index - The index, which may be List.size(), after the previous index to be included.
      Returns:
      The index of the previous item to be included before the given index, or -1 if there is no previous index.
      See Also:

    • isIncluded

      protected abstract boolean isIncluded(int index)
      Determines whether the item at the given index should be included.
      Parameters:
      index - The index of the item to check.
      Returns:
      true if the item at the given index should be included in the iteration, else false if it should be ignored.

    • hasNext

      public boolean hasNext()
      Specified by:
      hasNext in interface Iterator<I>
      Specified by:
      hasNext in interface ListIterator<I>
      Returns:
      true if the list iterator has more elements when traversing the list in the forward direction.

    • next

      public I next()
      Returns the next element in the list.
      Specified by:
      next in interface Iterator<I>
      Specified by:
      next in interface ListIterator<I>
      Returns:
      The next element in the list.
      Throws:
      NoSuchElementException - if the iteration has no next element.

    • hasPrevious

      public boolean hasPrevious()
      Specified by:
      hasPrevious in interface ListIterator<I>
      Returns:
      true if the list iterator has more elements when traversing the list in the reverse direction.

    • previous

      public I previous()
      Returns the previous element in the list.
      Specified by:
      previous in interface ListIterator<I>
      Returns:
      The previous element in the list.
      Throws:
      NoSuchElementException - if the iteration has no previous element.

    • nextIndex

      public int nextIndex()
      Specified by:
      nextIndex in interface ListIterator<I>
      Returns:
      The index of the element that would be returned by a subsequent call to next(), or list size if list iterator is at end of list.

    • previousIndex

      public int previousIndex()
      Specified by:
      previousIndex in interface ListIterator<I>
      Returns:
      The index of the element that would be returned by a subsequent call to previous(), or -1 if list iterator is at beginning of list.

    • remove

      public void remove()
      Removes from the list the last element that was returned by next() or previous().
      Specified by:
      remove in interface Iterator<I>
      Specified by:
      remove in interface ListIterator<I>
      Throws:
      IllegalStateException - neither next() nor previous() have been called, or remove() or add(Object) have been called after the last call to next() or previous().

    • set

      public void set(I object)
      Replaces the last element returned by next() or previous() with the specified element.
      Specified by:
      set in interface ListIterator<I>
      Parameters:
      object - The element with which to replace the last element returned by next() or previous().
      Throws:
      UnsupportedOperationException - if the set(Object) operation is not supported by this list iterator.
      ClassCastException - if the class of the specified element prevents it from being added to this list.
      IllegalArgumentException - if some aspect of the specified element prevents it from being added to this list.
      IllegalStateException - neither next() nor previous() have been called, or remove() or add(Object) have been called after the last call to next() or previous().

    • add

      public void add(I object)
      Inserts the specified element into the list. The element is inserted immediately before the next element that would be returned by next(), if any, and after the next element that would be returned by previous(), if any. (If the list contains no elements, the new element becomes the sole element on the list.) The new element is inserted before the implicit cursor: a subsequent call to next() would be unaffected, and a subsequent call to previous() would return the new element. (This call increases by one the value that would be returned by a call to nextIndex() or previousIndex().)
      Specified by:
      add in interface ListIterator<I>
      Parameters:
      object - The element to insert.
      Throws:
      UnsupportedOperationException - if the add(Object) operation is not supported by this list iterator.
      ClassCastException - if the class of the specified element prevents it from being added to this list.
      IllegalArgumentException - if some aspect of this element prevents it from being added to this list.

    • getItem

      protected abstract I getItem(int index)
      Retrieves an item representing the element at the given position in the list.
      Parameters:
      index - The list index
      Returns:
      An item representing the element at the given index in the list
      Throws:
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

    • setItem

      protected abstract I setItem(int index, I item)
      Sets the element at the given position in the list.
      Parameters:
      index - The list index
      item - The item representing the element to be stored at the specified position.
      Returns:
      An item representing the element previously at the specified position.
      Throws:
      UnsupportedOperationException - if the set(Object) operation is not supported by this list iterator.
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

    • addItem

      protected abstract void addItem(int index, I item)
      Inserts an element at the given position in the list.
      Parameters:
      index - The list index
      item - The item representing the element to be inserted at the specified position.
      Throws:
      UnsupportedOperationException - if the add(Object) operation is not supported by this list iterator.
      IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).