Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.util
Interface ListIterator<E>

All Superinterfaces:
  Iterator<E>

    public interface ListIterator<E>

extends 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()`. An iterator for a list of length `n` has `n+1` possible cursor positions, as illustrated by the carets (`^`) below:

                          Element(0)   Element(1)   Element(2)   ... Element(n-1)
     cursor positions:  ^            ^            ^            ^                  ^

Note that the `remove()` and `set(Object)` 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()` or `previous()`.

This interface is a member of the Java Collections Framework.

Since:
  1.2
See Also:
  `Collection`, `List`, `Iterator`, `Enumeration`, `List.listIterator()`

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

Method Detail

### 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` in interface `Iterator<E>`
  Returns:
    `true` if the list iterator has more elements when traversing the list in the forward direction.

### 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` in interface `Iterator<E>`
  Returns:
    the next element in the list.
  Throws:
    `NoSuchElementException` - if the iteration has no next element.

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

    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` - if the iteration has no previous element.

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

    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

    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` in interface `Iterator<E>`
  Throws:
    `UnsupportedOperationException` - if the `remove` operation is not supported by this list iterator.
    `IllegalStateException` - neither `next` nor `previous` have been called, or `remove` or `add` have been called after the last call to `next` or `previous`.

### set

    void set(E e)

  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:
    `e` - the element with which to replace the last element returned by `next` or `previous`.
  Throws:
    `UnsupportedOperationException` - if the `set` operation is not supported by this list iterator.
    `ClassCastException` - if the class of the specified element prevents it from being added to this list.
    `IllegalArgumentException` - if some aspect of the specified element prevents it from being added to this list.
    `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

    void add(E e)

  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:
    `e` - the element to insert.
  Throws:
    `UnsupportedOperationException` - if the `add` method is not supported by this list iterator.
    `ClassCastException` - if the class of the specified element prevents it from being added to this list.
    `IllegalArgumentException` - if some aspect of this element prevents it from being added to this list.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.