Class PeekingIterator<E>

  • Type Parameters:
    E - the type of elements returned by this iterator.
    All Implemented Interfaces:
    LookaheadIterator<E>, java.util.Iterator<E>, java.util.ListIterator<E>

    public class PeekingIterator<E>
    extends java.lang.Object
    implements java.util.ListIterator<E>, LookaheadIterator<E>
    Decorates an iterator to support one-element lookahead while iterating.

    The decorator supports the removal operation, but an IllegalStateException will be thrown if remove(), #add(), #set()} is called directly after a call to peek() or element().

    Since:
    4.0
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private boolean exhausted
      Indicates that the decorated iterator is exhausted.
      private java.util.ListIterator<E> iterator
      The iterator being decorated.
      private E slot
      The current slot for lookahead.
      private boolean slotFilled
      Indicates if the lookahead slot is filled.
    • Constructor Summary

      Constructors 
      Constructor Description
      PeekingIterator​(java.util.List<E> list)
      Constructor.
      PeekingIterator​(java.util.ListIterator<E> iterator)
      Constructor.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(E e)  
      int currentIndex()  
      E element()
      Returns the next element in iteration without advancing the underlying iterator.
      private void fill()  
      boolean hasNext()  
      boolean hasPrevious()  
      E next()  
      int nextIndex()  
      E peek()
      Returns the next element in iteration without advancing the underlying iterator.
      <E> PeekingIterator<E> peekingIterator​(java.util.ListIterator<E> iterator)
      Decorates the specified iterator to support one-element lookahead.
      E previous()  
      int previousIndex()  
      void remove()
      void set​(E e)  
      • 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
    • Field Detail

      • iterator

        private final java.util.ListIterator<E> iterator
        The iterator being decorated.
      • exhausted

        private boolean exhausted
        Indicates that the decorated iterator is exhausted.
      • slotFilled

        private boolean slotFilled
        Indicates if the lookahead slot is filled.
      • slot

        private E slot
        The current slot for lookahead.
    • Constructor Detail

      • PeekingIterator

        public PeekingIterator​(java.util.ListIterator<E> iterator)
        Constructor.
        Parameters:
        iterator - the iterator to decorate
      • PeekingIterator

        public PeekingIterator​(java.util.List<E> list)
        Constructor.
        Parameters:
        list - the provider of the iterator to decorate
    • Method Detail

      • peekingIterator

        public <E> PeekingIterator<E> peekingIterator​(java.util.ListIterator<E> iterator)
        Decorates the specified iterator to support one-element lookahead.

        If the iterator is already a PeekingIterator it is returned directly.

        Type Parameters:
        E - the element type
        Parameters:
        iterator - the iterator to decorate
        Returns:
        a new peeking iterator
        Throws:
        java.lang.NullPointerException - if the iterator is null
      • fill

        private void fill()
      • hasNext

        public boolean hasNext()
        Specified by:
        hasNext in interface java.util.Iterator<E>
        Specified by:
        hasNext in interface java.util.ListIterator<E>
      • peek

        public E peek()
        Returns the next element in iteration without advancing the underlying iterator. If the iterator is already exhausted, null will be returned.

        Note: this method does not throw a NoSuchElementException if the iterator is already exhausted. If you want such a behavior, use element() instead.

        The rationale behind this is to follow the Queue interface which uses the same terminology.

        Specified by:
        peek in interface LookaheadIterator<E>
        Returns:
        the next element from the iterator
      • element

        public E element()
        Returns the next element in iteration without advancing the underlying iterator. If the iterator is already exhausted, null will be returned.
        Specified by:
        element in interface LookaheadIterator<E>
        Returns:
        the next element from the iterator
        Throws:
        java.util.NoSuchElementException - if the iterator is already exhausted according to hasNext()
      • next

        public E next()
        Specified by:
        next in interface java.util.Iterator<E>
        Specified by:
        next in interface java.util.ListIterator<E>
      • remove

        public void remove()
        Specified by:
        remove in interface java.util.Iterator<E>
        Specified by:
        remove in interface java.util.ListIterator<E>
        Throws:
        java.lang.IllegalStateException - if peek() or element() has been called prior to the call to remove()
      • hasPrevious

        public boolean hasPrevious()
        Specified by:
        hasPrevious in interface java.util.ListIterator<E>
      • previous

        public E previous()
        Specified by:
        previous in interface java.util.ListIterator<E>
      • nextIndex

        public int nextIndex()
        Specified by:
        nextIndex in interface java.util.ListIterator<E>
      • currentIndex

        public int currentIndex()
      • previousIndex

        public int previousIndex()
        Specified by:
        previousIndex in interface java.util.ListIterator<E>
      • set

        public void set​(E e)
        Specified by:
        set in interface java.util.ListIterator<E>
      • add

        public void add​(E e)
        Specified by:
        add in interface java.util.ListIterator<E>