Package com.globalmentor.collections.iterators

Class 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:
    java.util.Iterator<I>, java.util.ListIterator<I>
    Direct Known Subclasses:
    DefaultListIterator
    public abstract class AbstractListIterator<I,​E>
extends java.lang.Object
implements java.util.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​(java.util.List<E> list)
      List constructor starting at the first index.
      AbstractListIterator​(java.util.List<E> list, int index)
      List and index constructor.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      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 java.util.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 Detail

      • AbstractListIterator

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

      • AbstractListIterator

        public AbstractListIterator​(java.util.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:
        java.lang.NullPointerException - if the given list is null.
        java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).

    • Method Detail

      • getList

        protected final java.util.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:
        isIncluded(int)

      • 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(int)

      • 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 java.util.Iterator<I>
        Specified by:
        hasNext in interface java.util.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 java.util.Iterator<I>
        Specified by:
        next in interface java.util.ListIterator<I>
        Returns:
        The next element in the list.
        Throws:
        java.util.NoSuchElementException - if the iteration has no next element.

      • hasPrevious

        public boolean hasPrevious()
        Specified by:
        hasPrevious in interface java.util.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 java.util.ListIterator<I>
        Returns:
        The previous element in the list.
        Throws:
        java.util.NoSuchElementException - if the iteration has no previous element.

      • nextIndex

        public int nextIndex()
        Specified by:
        nextIndex in interface java.util.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 java.util.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 java.util.Iterator<I>
        Specified by:
        remove in interface java.util.ListIterator<I>
        Throws:
        java.lang.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 java.util.ListIterator<I>
        Parameters:
        object - The element with which to replace the last element returned by next() or previous().
        Throws:
        java.lang.UnsupportedOperationException - if the set(Object) operation is not supported by this list iterator.
        java.lang.ClassCastException - if the class of the specified element prevents it from being added to this list.
        java.lang.IllegalArgumentException - if some aspect of the specified element prevents it from being added to this list.
        java.lang.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 java.util.ListIterator<I>
        Parameters:
        object - The element to insert.
        Throws:
        java.lang.UnsupportedOperationException - if the add(Object) operation is not supported by this list iterator.
        java.lang.ClassCastException - if the class of the specified element prevents it from being added to this list.
        java.lang.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:
        java.lang.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:
        java.lang.UnsupportedOperationException - if the set(Object) operation is not supported by this list iterator.
        java.lang.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:
        java.lang.UnsupportedOperationException - if the add(Object) operation is not supported by this list iterator.
        java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size()).