org.apache.commons.collections.iterators

## Class ArrayListIterator

- java.lang.Object
- - org.apache.commons.collections.iterators.ArrayIterator
  - - org.apache.commons.collections.iterators.ArrayListIterator

- All Implemented Interfaces:
    Iterator, ListIterator, ResettableIterator, ResettableListIterator

      public class ArrayListIterator
      extends ArrayIterator
      implements ListIterator, ResettableListIterator

  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:
    Commons Collections 3.0
  Version:
    $Revision: 647116 $ $Date: 2008-04-11 13:23:08 +0200 (Fri, 11 Apr 2008) $
  Author:
    Neil O'Toole, Stephen Colebourne, Phil Steitz
  See Also:
    `ArrayIterator`, `Iterator`, `ListIterator`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `lastItemIndex` Holds the index of the last item returned by a call to `next()` or `previous()`.

    - ### Fields inherited from class org.apache.commons.collections.iterators.ArrayIterator

      `array, endIndex, index, startIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ArrayListIterator()` Constructor for use with `setArray`.
    `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)` Construct an ArrayListIterator that will iterate over a range of values in the specified array.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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.
    `Object` | `next()` Gets the next element from the array.
    `int` | `nextIndex()` Gets the next index to be retrieved.
    `Object` | `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.collections.iterators.ArrayIterator

      `checkBound, getArray, hasNext, remove, setArray`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

      `hasNext, remove`

- - ### Field Detail

    - #### lastItemIndex

          protected int lastItemIndex

      Holds the index of the last item returned by a call to `next()` or `previous()`. This is set to `-1` if neither method has yet been invoked. `lastItemIndex` is used to to implement the `set(java.lang.Object)` method.

  - ### Constructor Detail

    - #### ArrayListIterator

          public ArrayListIterator()

      Constructor for use with `setArray`.

      Using this constructor, the iterator is equivalent to an empty iterator until `ArrayIterator.setArray(Object)` is called to establish the array to iterate over.

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

      Construct 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 Detail

    - #### hasPrevious

          public boolean hasPrevious()

      Returns true if there are previous elements to return from the array.
      Specified by:
        `hasPrevious` in interface `ListIterator`
      Returns:
        true if there is a previous element to return

    - #### previous

          public Object previous()

      Gets the previous element from the array.
      Specified by:
        `previous` in interface `ListIterator`
      Returns:
        the previous element
      Throws:
        `NoSuchElementException` - if there is no previous element

    - #### next

          public Object next()

      Gets the next element from the array.
      Specified by:
        `next` in interface `Iterator`
      Specified by:
        `next` in interface `ListIterator`
      Overrides:
        `next` in class `ArrayIterator`
      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`
      Returns:
        the index of the item to be retrieved next

    - #### previousIndex

          public int previousIndex()

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

    - #### 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`
      Throws:
        `UnsupportedOperationException` - always thrown.
      See Also:
        `ListIterator.set(java.lang.Object)`

    - #### 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`
      See Also:
        `ListIterator.set(java.lang.Object)`

    - #### reset

          public void reset()

      Resets the iterator back to the start index.
      Specified by:
        `reset` in interface `ResettableIterator`
      Specified by:
        `reset` in interface `ResettableListIterator`
      Overrides:
        `reset` in class `ArrayIterator`

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.