Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Collections

The ListIterator interface

Reference for java.util.ListIterator: move forward and backward through a list, replace, insert and remove elements while iterating.

ListIterator<E> extends Iterator<E> for lists. Besides walking forward it can walk backward, tell you the index of the elements around it, and modify the list as it goes: replace the last returned element with set() or insert a new one with add().

Think of the iterator's position as a cursor that sits between elements. next() returns the element after the cursor and moves it forward; previous() returns the element before the cursor and moves it back. You get one from list.listIterator() or list.listIterator(startIndex).

Java
ListIterator<String> it = list.listIterator();
while (it.hasNext()) {
    String s = it.next();
    it.set(s.toUpperCase());
}

Try it

Java Forward, backward and set

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Inserting and removing during iteration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public interface ListIterator<E> extends Iterator<E> {
    boolean hasNext();
    E next();
    boolean hasPrevious();
    E previous();
    int nextIndex();
    int previousIndex();
    void remove();
    void set(E e);
    void add(E e);
}
Method Description
hasNext(), next() Forward traversal. next() throws NoSuchElementException at the end.
hasPrevious(), previous() Backward traversal. previous() throws NoSuchElementException at the start.
nextIndex() Index of the element next() would return, or the list size at the end.
previousIndex() Index of the element previous() would return, or -1 at the start.
set(E e) Replaces the element last returned by next() or previous().
add(E e) Inserts the element immediately before the one next() would return (and after the one previous() would return). The cursor moves past it.
remove() Removes the element last returned by next() or previous().

Usage notes

  • set() and remove() apply to the last returned element, and each needs a next() or previous() call since the previous add() or remove(). Otherwise IllegalStateException.
  • add() can be called any number of times in a row, unlike remove(); each element goes in front of the cursor.
  • Optional operations: set, add and remove throw UnsupportedOperationException on lists that do not support them (List.of, Arrays.asList for add/remove).
  • Fail-fast, like Iterator: changing the list structurally by other means causes ConcurrentModificationException.
  • Cost: on an ArrayList, add and remove shift elements (O(n)); on a LinkedList they are O(1) at the cursor, which is where ListIterator shines.
  • Starting position: listIterator(list.size()) starts at the end for a reverse walk. For read-only reverse iteration on Java 21+ you can also use list.reversed().
  • Only lists have it. For sets and queues use plain Iterator.