org.apache.commons.collections.iterators
Class ArrayListIterator<E>

java.lang.Object
  org.apache.commons.collections.iterators.ArrayIterator<E>
      org.apache.commons.collections.iterators.ArrayListIterator<E>

All Implemented Interfaces:

Iterator<E>, ListIterator<E>, ResettableIterator<E>, ResettableListIterator<E>

public class ArrayListIterator<E>
extends ArrayIterator<E>
implements ListIterator<E>, 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:

Commons Collections 3.0

Version:

$Revision: 1.1.1.1 $ $Date: 2005/05/23 04:34:47 $

Author:

Neil O'Toole, Stephen Colebourne, Matt Hall, John Watkinson, Phil Steitz

See Also:

ArrayIterator, Iterator, ListIterator

Field Summary

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

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

void	add(E 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(E 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

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(E) 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<E>

Returns:

true if there is a previous element to return

previous

public E previous()

Gets the previous element from the array.

Specified by:

previous in interface ListIterator<E>

Returns:

the previous element

Throws:

NoSuchElementException - if there is no previous element

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

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

add

public void add(E 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>

Throws:

UnsupportedOperationException - always thrown.

See Also:

ListIterator.set(E)

set

public void set(E 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>

See Also:

ListIterator.set(E)

reset

public void reset()

Resets the iterator back to the start index.

Specified by:

reset in interface ResettableIterator<E>

Specified by:

reset in interface ResettableListIterator<E>

Overrides:

reset in class ArrayIterator<E>