Package org.apache.commons.collections4.iterators

# Class ListIteratorWrapper<E>

java.lang.Object
org.apache.commons.collections4.iterators.ListIteratorWrapper<E>

Type Parameters:
  `E` - The type of elements in this iterator.

All Implemented Interfaces:
  `Iterator<E>`, `ListIterator<E>`, `OrderedIterator<E>`, `ResettableIterator<E>`, `ResettableListIterator<E>`

public class ListIteratorWrapper<E> extends Object implements ResettableListIterator<E>
Converts an `Iterator` into a `ResettableListIterator`. For plain `Iterator`s this is accomplished by caching the returned elements. This class can also be used to simply add `ResettableIterator` functionality to a given `ListIterator`.

The `ListIterator` interface has additional useful methods for navigation - `previous()` and the index methods. This class allows a regular `Iterator` to behave as a `ListIterator`. It achieves this by building a list internally of as the underlying iterator is traversed.

The optional operations of `ListIterator` are not supported for plain `Iterator`s.

This class implements ResettableListIterator from Commons Collections 3.2.

Since:
  2.1

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ListIteratorWrapper(Iterator<? extends E> iterator)`
  Constructs a new `ListIteratorWrapper` that will wrap the given iterator.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(E obj)`
  Throws `UnsupportedOperationException` unless the underlying `Iterator` is a `ListIterator`.
  `boolean`
  `hasNext()`
  Returns true if there are more elements in the iterator.
  `boolean`
  `hasPrevious()`
  Returns true if there are previous elements in the iterator.
  `E`
  `next()`
  Returns the next element from the iterator.
  `int`
  `nextIndex()`
  Returns the index of the next element.
  `E`
  `previous()`
  Returns the previous element.
  `int`
  `previousIndex()`
  Returns the index of the previous element.
  `void`
  `remove()`
  Removes the last element that was returned by `next()` or `previous()` from the underlying collection.
  `void`
  `reset()`
  Resets this iterator back to the position at which the iterator was created.
  `void`
  `set(E obj)`
  Throws `UnsupportedOperationException` unless the underlying `Iterator` is a `ListIterator`.

  ### 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

  - ### ListIteratorWrapper

    public ListIteratorWrapper(Iterator<? extends E> iterator)
    Constructs a new `ListIteratorWrapper` that will wrap the given iterator.
    Parameters:
      `iterator` - The iterator to wrap
    Throws:
      `NullPointerException` - if the iterator is null

- ## Method Details

  - ### add

    public void add(E obj) throws UnsupportedOperationException
    Throws `UnsupportedOperationException` unless the underlying `Iterator` is a `ListIterator`.
    Specified by:
      `add` in interface `ListIterator<E>`
    Parameters:
      `obj` - The object to add
    Throws:
      `UnsupportedOperationException` - if the underlying iterator is not of type `ListIterator`

  - ### hasNext

    public boolean hasNext()
    Returns true if there are more elements in the iterator.
    Specified by:
      `hasNext` in interface `Iterator<E>`
    Specified by:
      `hasNext` in interface `ListIterator<E>`
    Returns:
      true if there are more elements

  - ### hasPrevious

    public boolean hasPrevious()
    Returns true if there are previous elements in the iterator.
    Specified by:
      `hasPrevious` in interface `ListIterator<E>`
    Specified by:
      `hasPrevious` in interface `OrderedIterator<E>`
    Returns:
      true if there are previous elements

  - ### next

    public E next() throws NoSuchElementException
    Returns the next element from the iterator.
    Specified by:
      `next` in interface `Iterator<E>`
    Specified by:
      `next` in interface `ListIterator<E>`
    Returns:
      The next element from the iterator
    Throws:
      `NoSuchElementException` - if there are no more elements

  - ### nextIndex

    public int nextIndex()
    Returns the index of the next element.
    Specified by:
      `nextIndex` in interface `ListIterator<E>`
    Returns:
      The index of the next element

  - ### previous

    public E previous() throws NoSuchElementException
    Returns the previous element.
    Specified by:
      `previous` in interface `ListIterator<E>`
    Specified by:
      `previous` in interface `OrderedIterator<E>`
    Returns:
      The previous element
    Throws:
      `NoSuchElementException` - if there are no previous elements

  - ### previousIndex

    public int previousIndex()
    Returns the index of the previous element.
    Specified by:
      `previousIndex` in interface `ListIterator<E>`
    Returns:
      the index of the previous element

  - ### remove

    public void remove() throws IllegalStateException
    Removes the last element that was returned by `next()` or `previous()` from the underlying collection. This call can only be made once per call to `next` or `previous` and only if `add(Object)` was not called in between.
    Specified by:
      `remove` in interface `Iterator<E>`
    Specified by:
      `remove` in interface `ListIterator<E>`
    Throws:
      `IllegalStateException` - if `next` or `previous` have not been called before, or if `remove` or `add` have been called after the last call to `next` or `previous`

  - ### reset

    public void reset()
    Resets this iterator back to the position at which the iterator was created.
    Specified by:
      `reset` in interface `ResettableIterator<E>`
    Since:
      3.2

  - ### set

    public void set(E obj) throws UnsupportedOperationException
    Throws `UnsupportedOperationException` unless the underlying `Iterator` is a `ListIterator`.
    Specified by:
      `set` in interface `ListIterator<E>`
    Parameters:
      `obj` - The object to set
    Throws:
      `UnsupportedOperationException` - if the underlying iterator is not of type `ListIterator`