Package org.apache.commons.collections4.iterators

# Class ArrayListIterator<E>

java.lang.Object
org.apache.commons.collections4.iterators.ArrayIterator<E>
org.apache.commons.collections4.iterators.ArrayListIterator<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 ArrayListIterator<E> extends ArrayIterator<E> implements ResettableListIterator<E>
Implements a `ListIterator` over an array.

The array can be either an array of object or of primitives. If you know that you have an object array, the `ObjectArrayListIterator` class is a better choice, as it will perform better.

This iterator does not support `add(Object)` or `ArrayIterator.remove()`, as the array cannot be changed in size. The `set(Object)` method is supported however.

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ArrayListIterator(Object array)`
  Constructs an ArrayListIterator that will iterate over the values in the specified array.
  `ArrayListIterator(Object array, int startIndex)`
  Constructs an ArrayListIterator that will iterate over the values in the specified array from a specific start index.
  `ArrayListIterator(Object array, int startIndex, int endIndex)`
  Constructs an ArrayListIterator that will iterate over a range of values in the specified array.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(Object o)`
  This iterator does not support modification of its backing collection, and so will always throw an `UnsupportedOperationException` when this method is invoked.
  `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(Object o)`
  Sets the element under the cursor.

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

  `checkBound, 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

  - ### ArrayListIterator

    public ArrayListIterator(Object array)
    Constructs an ArrayListIterator that will iterate over the values in the specified array.
    Parameters:
      `array` - the array to iterate over
    Throws:
      `IllegalArgumentException` - if `array` is not an array.
      `NullPointerException` - if `array` is `null`

  - ### ArrayListIterator

    public ArrayListIterator(Object array, int startIndex)
    Constructs an ArrayListIterator that will iterate over the values in the specified array from a specific start index.
    Parameters:
      `array` - the array to iterate over
      `startIndex` - the index to start iterating at
    Throws:
      `IllegalArgumentException` - if `array` is not an array.
      `NullPointerException` - if `array` is `null`
      `IndexOutOfBoundsException` - if the start index is out of bounds

  - ### ArrayListIterator

    public ArrayListIterator(Object array, int startIndex, int endIndex)
    Constructs an ArrayListIterator that will iterate over a range of values in the specified array.
    Parameters:
      `array` - the array to iterate over
      `startIndex` - the index to start iterating at
      `endIndex` - the index (exclusive) to finish iterating at
    Throws:
      `IllegalArgumentException` - if `array` is not an array.
      `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(Object o)
    This iterator does not support modification of its backing collection, and so will always throw an `UnsupportedOperationException` when this method is invoked.
    Specified by:
      `add` in interface `ListIterator<E>`
    Parameters:
      `o` - the element to add
    Throws:
      `UnsupportedOperationException` - always thrown.
    See Also:
      - `ListIterator.set(E)`

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

  - ### set

    public void set(Object o)
    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:
      `o` - the element to set
    Throws:
      `IllegalStateException` - if `next()` or `previous()` has not been called before `set(Object)`
    See Also:
      - `ListIterator.set(E)`