java.util
Interface ListIterator<E>

All Superinterfaces:
Iterator sample code for java.util.Iterator definition code for java.util.Iterator <E>

public interface ListIterator<E>
extends Iterator sample code for java.util.Iterator definition code for java.util.Iterator <E>

An iterator for lists that allows the programmer to traverse the list in either direction, modify the list during iteration, and obtain the iterator's current position in the list. A ListIterator has no current element; its cursor position always lies between the element that would be returned by a call to previous() and the element that would be returned by a call to next(). In a list of length n, there are n+1 valid index values, from 0 to n, inclusive.


          Element(0)   Element(1)   Element(2)   ... Element(n)   
        ^            ^            ^            ^               ^
 Index: 0            1            2            3               n+1

 

Note that the remove() sample code for java.util.ListIterator.remove() definition code for java.util.ListIterator.remove() and set(Object) sample code for java.util.ListIterator.set(E) definition code for java.util.ListIterator.set(E) methods are not defined in terms of the cursor position; they are defined to operate on the last element returned by a call to next() sample code for java.util.ListIterator.next() definition code for java.util.ListIterator.next() or previous() sample code for java.util.ListIterator.previous() definition code for java.util.ListIterator.previous() .

This interface is a member of the Java Collections Framework.

Since:
1.2
See Also:
Collection sample code for java.util.Collection definition code for java.util.Collection , List sample code for java.util.List definition code for java.util.List , Iterator sample code for java.util.Iterator definition code for java.util.Iterator , Enumeration sample code for java.util.Enumeration definition code for java.util.Enumeration

Method Summary
 void add sample code for java.util.ListIterator.add(E) definition code for java.util.ListIterator.add(E) (E o)
          Inserts the specified element into the list (optional operation).
 boolean hasNext sample code for java.util.ListIterator.hasNext() definition code for java.util.ListIterator.hasNext() ()
          Returns true if this list iterator has more elements when traversing the list in the forward direction.
 boolean hasPrevious sample code for java.util.ListIterator.hasPrevious() definition code for java.util.ListIterator.hasPrevious() ()
          Returns true if this list iterator has more elements when traversing the list in the reverse direction.
 E next sample code for java.util.ListIterator.next() definition code for java.util.ListIterator.next() ()
          Returns the next element in the list.
 int nextIndex sample code for java.util.ListIterator.nextIndex() definition code for java.util.ListIterator.nextIndex() ()
          Returns the index of the element that would be returned by a subsequent call to next.
 E previous sample code for java.util.ListIterator.previous() definition code for java.util.ListIterator.previous() ()
          Returns the previous element in the list.
 int previousIndex sample code for java.util.ListIterator.previousIndex() definition code for java.util.ListIterator.previousIndex() ()
          Returns the index of the element that would be returned by a subsequent call to previous.
 void remove sample code for java.util.ListIterator.remove() definition code for java.util.ListIterator.remove() ()
          Removes from the list the last element that was returned by next or previous (optional operation).
 void set sample code for java.util.ListIterator.set(E) definition code for java.util.ListIterator.set(E) (E o)
          Replaces the last element returned by next or previous with the specified element (optional operation).
 

Method Detail

hasNext sample code for java.util.ListIterator.hasNext() definition code for java.util.ListIterator.hasNext()

boolean hasNext()
Returns true if this list iterator has more elements when traversing the list in the forward direction. (In other words, returns true if next would return an element rather than throwing an exception.)

Specified by:
hasNext sample code for java.util.Iterator.hasNext() definition code for java.util.Iterator.hasNext() in interface Iterator sample code for java.util.Iterator definition code for java.util.Iterator <E>
Returns:
true if the list iterator has more elements when traversing the list in the forward direction.

next sample code for java.util.ListIterator.next() definition code for java.util.ListIterator.next()

E next()
Returns the next element in the list. This method may be called repeatedly to iterate through the list, or intermixed with calls to previous to go back and forth. (Note that alternating calls to next and previous will return the same element repeatedly.)

Specified by:
next sample code for java.util.Iterator.next() definition code for java.util.Iterator.next() in interface Iterator sample code for java.util.Iterator definition code for java.util.Iterator <E>
Returns:
the next element in the list.
Throws:
NoSuchElementException sample code for java.util.NoSuchElementException definition code for java.util.NoSuchElementException - if the iteration has no next element.

hasPrevious sample code for java.util.ListIterator.hasPrevious() definition code for java.util.ListIterator.hasPrevious()

boolean hasPrevious()
Returns true if this list iterator has more elements when traversing the list in the reverse direction. (In other words, returns true if previous would return an element rather than throwing an exception.)

Returns:
true if the list iterator has more elements when traversing the list in the reverse direction.

previous sample code for java.util.ListIterator.previous() definition code for java.util.ListIterator.previous()

E previous()
Returns the previous element in the list. This method may be called repeatedly to iterate through the list backwards, or intermixed with calls to next to go back and forth. (Note that alternating calls to next and previous will return the same element repeatedly.)

Returns:
the previous element in the list.
Throws:
NoSuchElementException sample code for java.util.NoSuchElementException definition code for java.util.NoSuchElementException - if the iteration has no previous element.

nextIndex sample code for java.util.ListIterator.nextIndex() definition code for java.util.ListIterator.nextIndex()

int nextIndex()
Returns the index of the element that would be returned by a subsequent call to next. (Returns list size if the list iterator is at the end of the list.)

Returns:
the index of the element that would be returned by a subsequent call to next, or list size if list iterator is at end of list.

previousIndex sample code for java.util.ListIterator.previousIndex() definition code for java.util.ListIterator.previousIndex()

int previousIndex()
Returns the index of the element that would be returned by a subsequent call to previous. (Returns -1 if the list iterator is at the beginning of the list.)

Returns:
the index of the element that would be returned by a subsequent call to previous, or -1 if list iterator is at beginning of list.

remove sample code for java.util.ListIterator.remove() definition code for java.util.ListIterator.remove()

void remove()
Removes from the list the last element that was returned by next or previous (optional operation). This call can only be made once per call to next or previous. It can be made only if ListIterator.add has not been called after the last call to next or previous.

Specified by:
remove sample code for java.util.Iterator.remove() definition code for java.util.Iterator.remove() in interface Iterator sample code for java.util.Iterator definition code for java.util.Iterator <E>
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - if the remove operation is not supported by this list iterator.
IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException - neither next nor previous have been called, or remove or add have been called after the last call to * next or previous.

set sample code for java.util.ListIterator.set(E) definition code for java.util.ListIterator.set(E)

void set(E o)
Replaces the last element returned by next or previous with the specified element (optional operation). This call can be made only if neither ListIterator.remove nor ListIterator.add have been called after the last call to next or previous.

Parameters:
o - the element with which to replace the last element returned by next or previous.
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - if the set operation is not supported by this list iterator.
ClassCastException sample code for java.lang.ClassCastException definition code for java.lang.ClassCastException - if the class of the specified element prevents it from being added to this list.
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if some aspect of the specified element prevents it from being added to this list.
IllegalStateException sample code for java.lang.IllegalStateException definition code for java.lang.IllegalStateException - if neither next nor previous have been called, or remove or add have been called after the last call to next or previous.

add sample code for java.util.ListIterator.add(E) definition code for java.util.ListIterator.add(E)

void add(E o)
Inserts the specified element into the list (optional operation). The element is inserted immediately before the next element that would be returned by next, if any, and after the next element that would be returned by previous, if any. (If the list contains no elements, the new element becomes the sole element on the list.) The new element is inserted before the implicit cursor: a subsequent call to next would be unaffected, and a subsequent call to previous would return the new element. (This call increases by one the value that would be returned by a call to nextIndex or previousIndex.)

Parameters:
o - the element to insert.
Throws:
UnsupportedOperationException sample code for java.lang.UnsupportedOperationException definition code for java.lang.UnsupportedOperationException - if the add method is not supported by this list iterator.
ClassCastException sample code for java.lang.ClassCastException definition code for java.lang.ClassCastException - if the class of the specified element prevents it from being added to this list.
IllegalArgumentException sample code for java.lang.IllegalArgumentException definition code for java.lang.IllegalArgumentException - if some aspect of this element prevents it from being added to this list.