This
interface is an extension of Iterator for use with
ordered collections, or lists. It defines methods to iterate forward
and backward through a list, to determine the list index of the
elements being iterated, and, for mutable lists, to safely insert,
delete, and edit elements in the list while the iteration is in
progress. For some lists, notably LinkedList,
using an iterator to enumerate the list's elements
may be substantially more efficient than looping through the list by
index and calling get( ) repeatedly.
Like the Iterator interface,
ListIterator has been made generic in Java 5.0.
The type variable E represents the type of
the elements on the list.
hasNext( )
and next( ) are the most commonly used methods of
ListIterator; they iterate forward through the
list. See Iterator for details. In addition to
these two methods, however, ListIterator also
defines hasPrevious( ) and previous(
) that allow you to iterate backward through the list.
previous( ) returns the previous element on the
list or throws a NoSuchElementException if there
is no previous element. hasPrevious( ) returns
TRue if a subsequent call to previous(
) returns an object. nextIndex( ) and
previousIndex( ) return the index of the object
that would be returned by a subsequent call to next(
) or previous( ). If next(
) or previous( ) throw a
NoSuchElementException, nextIndex(
) returns the size of the list, and previousIndex(
) returns -1.
ListIterator
defines three optionally supported methods that provide a safe way to
modify the contents of the underlying list while the iteration is in
progress. add( ) inserts a new object into the
list, immediately before the object that would be returned by a
subsequent call to next( ). Calling add(
) does not affect the value that is returned by
next( ), however. If you call previous(
) immediately after calling add( ), the
method returns the object you just added. remove(
) deletes from the list the object most recently returned
by next( ) or previous( ). You
can only call remove( ) once per call to
next( ) or previous( ). If you
have called add( ), you must call next(
) or previous( ) again before calling
remove( ). set( ) replaces the
object most recently returned by next( ) or
previous( ) with the specified object. If you have
called add( ) or remove( ), you
must call next( ) or previous(
) again before calling set( ). Remember
that support for the add( ), remove(
), and set( ) methods is optional.
Iterators for immutable lists never support them, of course. An
unsupported method throws a
java.lang.UnsupportedOperationException when
called. Also, when an iterator is in use, all modifications should be
made through the iterator rather than to the list itself. If the
underlying list is modified while an iteration is ongoing, the
ListIterator may fail to operate correctly or may
throw a ConcurrentModificationException.
public interface ListIterator<E> extends Iterator<E> {
// Public Instance Methods
void add(E o);
boolean hasNext( );
boolean hasPrevious( );
E next( );
int nextIndex( );
E previous( );
int previousIndex( );
void remove( );
void set(E o);
}
