Package org.apache.commons.collections4.iterators

# Class ObjectArrayListIterator<E>

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

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

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

public class ObjectArrayListIterator<E> extends ObjectArrayIterator<E> implements ResettableListIterator<E>
Implements a `ListIterator` over an array of objects.

This iterator does not support `add(E)` or `ObjectArrayIterator.remove()`, as the object array cannot be structurally modified. The `set(E)` method is supported however.

The iterator implements a `reset()` method, allowing the reset of the iterator back to the start if required.

Since:
  3.0
See Also:
  - `ObjectArrayIterator`
  - `Iterator`
  - `ListIterator`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ObjectArrayListIterator(E... array)`
  Constructs an ObjectArrayListIterator that will iterate over the values in the specified array.
  `ObjectArrayListIterator(E[] array, int start)`
  Constructs an ObjectArrayListIterator that will iterate over the values in the specified array from a specific start index.
  `ObjectArrayListIterator(E[] array, int start, int end)`
  Constructs an ObjectArrayListIterator that will iterate over a range of values in the specified array.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(E obj)`
  Always throws `UnsupportedOperationException`.
  `boolean`
  `hasPrevious()`
  Returns true if there are previous elements to return from the array.
  `E`
  `next()`
  Gets the next element from the array.
  `int`
  `nextIndex()`
  Gets the next index to be retrieved.
  `E`
  `previous()`
  Gets the previous element from the array.
  `int`
  `previousIndex()`
  Gets the index of the item to be retrieved if `previous()` is called.
  `void`
  `reset()`
  Resets the iterator back to the start index.
  `void`
  `set(E obj)`
  Sets the element under the cursor.

  ### Methods inherited from class org.apache.commons.collections4.iterators.ObjectArrayIterator

  `getArray, getEndIndex, getStartIndex, hasNext, remove`

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

  ### Methods inherited from interface java.util.ListIterator

  `hasNext, remove`

- ## Constructor Details

  - ### ObjectArrayListIterator

    public ObjectArrayListIterator(E... array)
    Constructs an ObjectArrayListIterator that will iterate over the values in the specified array.
    Parameters:
      `array` - The array to iterate over
    Throws:
      `NullPointerException` - if `array` is `null`

  - ### ObjectArrayListIterator

    public ObjectArrayListIterator(E[] array, int start)
    Constructs an ObjectArrayListIterator that will iterate over the values in the specified array from a specific start index.
    Parameters:
      `array` - The array to iterate over
      `start` - The index to start iterating at
    Throws:
      `NullPointerException` - if `array` is `null`
      `IndexOutOfBoundsException` - if the start index is out of bounds

  - ### ObjectArrayListIterator

    public ObjectArrayListIterator(E[] array, int start, int end)
    Constructs an ObjectArrayListIterator that will iterate over a range of values in the specified array.
    Parameters:
      `array` - The array to iterate over
      `start` - The index to start iterating at
      `end` - The index (exclusive) to finish iterating at
    Throws:
      `IndexOutOfBoundsException` - if the start or end index is out of bounds
      `IllegalArgumentException` - if end index is before the start
      `NullPointerException` - if `array` is `null`

- ## Method Details

  - ### add

    public void add(E obj)
    Always throws `UnsupportedOperationException`.
    Specified by:
      `add` in interface `ListIterator<E>`
    Parameters:
      `obj` - Ignored.
    Throws:
      `UnsupportedOperationException` - Always thrown.

  - ### hasPrevious

    public boolean hasPrevious()
    Returns true if there are previous elements to return from the array.
    Specified by:
      `hasPrevious` in interface `ListIterator<E>`
    Specified by:
      `hasPrevious` in interface `OrderedIterator<E>`
    Returns:
      true if there is a previous element to return

  - ### next

    public E next()
    Gets the next element from the array.
    Specified by:
      `next` in interface `Iterator<E>`
    Specified by:
      `next` in interface `ListIterator<E>`
    Overrides:
      `next` in class `ObjectArrayIterator<E>`
    Returns:
      The next element
    Throws:
      `NoSuchElementException` - if there is no next element

  - ### nextIndex

    public int nextIndex()
    Gets the next index to be retrieved.
    Specified by:
      `nextIndex` in interface `ListIterator<E>`
    Returns:
      The index of the item to be retrieved next

  - ### previous

    public E previous()
    Gets the previous element from the array.
    Specified by:
      `previous` in interface `ListIterator<E>`
    Specified by:
      `previous` in interface `OrderedIterator<E>`
    Returns:
      The previous element
    Throws:
      `NoSuchElementException` - if there is no previous element

  - ### previousIndex

    public int previousIndex()
    Gets the index of the item to be retrieved if `previous()` is called.
    Specified by:
      `previousIndex` in interface `ListIterator<E>`
    Returns:
      The index of the item to be retrieved next

  - ### reset

    public void reset()
    Resets the iterator back to the start index.
    Specified by:
      `reset` in interface `ResettableIterator<E>`
    Overrides:
      `reset` in class `ObjectArrayIterator<E>`

  - ### set

    public void set(E obj)
    Sets the element under the cursor.

    This method sets the element that was returned by the last call to `next()` of `previous()`.

    Note: `ListIterator` implementations that support `add()` and `remove()` only allow `set()` to be called once per call to `next()` or `previous` (see the `ListIterator` Javadoc for more details). Since this implementation does not support `add()` or `remove()`, `set()` may be called as often as desired.

    Specified by:
      `set` in interface `ListIterator<E>`
    Parameters:
      `obj` - The object to set into the array
    Throws:
      `IllegalStateException` - if next() has not yet been called.
      `ClassCastException` - if the object type is unsuitable for the array