Java ListIterator

java.util.ListIterator<E> is the extension of Iterator that gives you full bidirectional control over a List. Where a plain Iterator can only move forward and remove, a ListIterator can move backward, replace elements in place, insert new elements mid-traversal, and report the current cursor position as an index. It is the only standard Java mechanism for all of these in a single object.

If you have ever needed to scan a list forward then process it backward, or replace every element during iteration without manually tracking indices, ListIterator is the right tool.

What Is ListIterator?

ListIterator<E> is an interface in java.util that extends java.util.Iterator<E>. It adds five new methods to the three that Iterator provides:

java.util.Iterator<E>                   ← base traversal
    boolean  hasNext()                  ← more elements forward?
    E        next()                     ← return current, advance forward
    void     remove()                   ← remove last returned element

java.util.ListIterator<E>               ← extends Iterator — List only
    boolean  hasPrevious()              ← more elements backward?
    E        previous()                 ← return current, advance backward
    int      nextIndex()                ← index of element next() would return
    int      previousIndex()            ← index of element previous() would return
    void     set(E element)             ← replace last returned element (no cursor shift)
    void     add(E element)             ← insert before next-to-be-returned element

The diagram below shows the cursor model. ListIterator positions a conceptual cursor between elements, not on them.

LIST CONTENTS:    [ "A"  |  "B"  |  "C"  |  "D"  |  "E" ]
                   0       1       2       3       4      (element indices)

CURSOR POSITIONS:
  ^              ^       ^       ^       ^       ^
  0              1       2       3       4       5        (cursor positions)

  nextIndex()    = index of next element next() would return
  previousIndex() = nextIndex() - 1

  Cursor at position 2:
    nextIndex()     = 2  → next() returns "C"
    previousIndex() = 1  → previous() returns "B"

  After next() when cursor is at position 2:
    cursor moves to position 3
    next() returns "C"    (element at old cursor 2)
    lastRet = 2           (remembers what was returned)

  After previous() when cursor is at position 3:
    cursor moves back to position 2
    previous() returns "C"  (element at old cursor 2)
    lastRet = 2

ListIterator is only available on List implementations. Calling list.listIterator() gives a cursor at position 0. Calling list.listIterator(int index) starts the cursor at any valid position from 0 to list.size().

Where ListIterator Fits in the Hierarchy

java.lang.Iterable<E>
    └── java.util.Collection<E>
            └── java.util.List<E>
                    ├── ArrayList   ← supports listIterator()
                    ├── LinkedList  ← supports listIterator()
                    └── Vector      ← supports listIterator() (legacy)

java.util.Iterator<E>              ← base interface
    └── java.util.ListIterator<E>  ← List-specific extension

  Note: Set, Queue, Map views do NOT support ListIterator.
  Only List implementations have a listIterator() method.

When to Use ListIterator

The decision is direct. Use ListIterator when all of these are true: the collection is a List, and at least one of the following operations is needed during traversal:

• ›Backward traversal — scanning a list in reverse without reversing the list itself
• ›In-place replacement — set(newElement) replaces an element without a separate list.set(index, value) call
• ›Mid-traversal insertion — add(newElement) inserts before the next element without index bookkeeping
• ›Current position awareness — nextIndex() and previousIndex() tell you exactly where the cursor is

Use plain Iterator when only forward traversal with optional removal is needed. Use for-each when traversal is read-only. Use removeIf() for conditional bulk removal. Use a standard index loop when random access by position is required alongside traversal.

How ListIterator Works Internally

ListIterator for ArrayList is implemented as an inner class called ListItr that extends Itr (the regular iterator inner class). It adds three fields beyond the base cursor:

ARRAYLIST'S ListItr INTERNAL FIELDS:

  From Itr (parent):
    int cursor           ← index of next element that next() will return
    int lastRet = -1     ← index of last element returned by next() or previous()
    int expectedModCount ← snapshot of modCount at iterator creation

  Added by ListItr:
    (no new fields — ListItr uses cursor and lastRet differently)

  CURSOR SEMANTICS:
    next():
      1. Check modCount == expectedModCount → CME if changed outside iterator
      2. result = elementData[cursor]
      3. lastRet = cursor
      4. cursor++
      5. return result

    previous():
      1. Check modCount == expectedModCount → CME if changed outside iterator
      2. cursor--
      3. result = elementData[cursor]
      4. lastRet = cursor
      5. return result

    set(element):
      1. Check lastRet >= 0 → IllegalStateException if no prior next/previous
      2. Check modCount == expectedModCount → CME if stale
      3. ArrayList.this.set(lastRet, element)   ← no cursor change
      4. (modCount NOT incremented — set() is not structural)

    add(element):
      1. Check modCount == expectedModCount → CME if stale
      2. ArrayList.this.add(cursor, element)   ← inserts at current position
      3. cursor++                              ← skip the added element on next next()
      4. lastRet = -1                          ← prevents set/remove after add
      5. expectedModCount = modCount           ← sync after structural change

KEY INSIGHT:
  set() is NOT structural — it does not change size or modCount.
  add() IS structural — it updates expectedModCount after the change.
  remove() IS structural — it updates expectedModCount after the change.
  This is why set() after add() or after remove() throws IllegalStateException —
  lastRet is reset to -1 by both add() and remove(), making the "last returned"
  position undefined.

Core Operations with Examples

Forward and Backward Traversal

The foundational ListIterator capability — scanning in both directions. The cursor position persists between hasNext()/next() and hasPrevious()/previous() calls, so you can switch direction at any point.

Output:
=== Forward pass ===
  [0] Churchgate
  [1] Marine Lines
  [2] Charni Road
  [3] Grant Road
  [4] Mumbai Central
  [5] Mahalaxmi

=== Backward pass (cursor at end after forward) ===
  [5] Mahalaxmi
  [4] Mumbai Central
  [3] Grant Road
  [2] Charni Road
  [1] Marine Lines
  [0] Churchgate

=== Traversal starting at index 3 ===
  nextIndex()     = 3
  previousIndex() = 2
  Grant Road
  Mumbai Central
  Mahalaxmi

In-Place Replacement with set()

set(element) replaces the element most recently returned by next() or previous() without moving the cursor. This is the correct way to transform every element in a list during traversal — cleaner and more efficient than tracking an index manually.

Output:
Before: [laptop, wireless mouse, mechanical keyboard, monitor, usb hub, webcam]
After capitalise: [Laptop, Wireless mouse, Mechanical keyboard, Monitor, Usb hub, Webcam]

After backward set(): [Tata Salt [OFFER], Amul Butter [OFFER], Aashirvaad Atta [OFFER], Fortune Oil [OFFER]]

set() after add() throws: IllegalStateException

Mid-Traversal Insertion with add()

add(element) inserts the new element immediately before the element that next() would return next. The cursor advances past the inserted element, so next() after add() skips it and returns the element that was originally next.

Output:
Before: [STANDARD: Send report, STANDARD: Update DB, URGENT: Fix login bug, STANDARD: Deploy feature]
After insertions:
  LOG: Before - Send report
  STANDARD: Send report
  LOG: Before - Update DB
  STANDARD: Update DB
  URGENT: Fix login bug
  LOG: Before - Deploy feature
  STANDARD: Deploy feature

nextIndex before next()    : 0
nextIndex after next()     : 1
nextIndex after add(20)    : 2
previousIndex after add(20): 1
List after add: [10, 20, 30, 50]
next() after add returns   : 30

Safe Removal with remove()

remove() on a ListIterator behaves like Iterator.remove() — it removes the last element returned by next() or previous(). It cannot be called consecutively without an intervening next() or previous().

Output:
Original scores: [95, 42, 88, 15, 76, 33, 91, 60, 8, 100]
After removing below 50: [95, 88, 76, 91, 60, 100]
After removing top 2 (>=90): [88, 76, 60]

Double remove() throws: IllegalStateException

ListIterator vs Iterator

The key practical differences: ListIterator is needed when any of these is required — backward scanning, in-place replacement during traversal, or insertion at the current cursor position. For everything else, Iterator or for-each is sufficient.

Real-World Example — Meesho Product Feed Normaliser

A product feed normaliser at Meesho processes a batch of seller-uploaded product listings. Each listing must be scanned twice: a forward pass to normalise and flag issues, and a backward pass to insert placeholder entries for missing categories. Using ListIterator for both passes avoids rebuilding the list or maintaining separate index counters.

Output:
==================================================================
  ORIGINAL FEED (7 listings)
==================================================================
    cotton kurti set    Fashion       Rs.   899.00
  BRASS DIYA            HomeDecor     Rs.    79.00
  organic face serum    Beauty        Rs.  1199.00
  phone case            Electronics   Rs.     0.50
  stainless steel tiffin Kitchen      Rs.   349.00
  branded handbag       Fashion       Rs. 750000.00
  yoga mat anti slip    Sports        Rs.   599.00
==================================================================

==================================================================
  AFTER FORWARD NORMALISATION (7 listings)
==================================================================
  Cotton kurti set      Fashion       Rs.   899.00
  Brass diya            HomeDecor     Rs.    79.00
  Organic face serum    Beauty        Rs.  1199.00
  Phone case            Electronics   Rs.     0.50  [FLAG]
  Stainless steel tiffin Kitchen      Rs.   349.00
  Branded handbag       Fashion       Rs. 750000.00  [FLAG]
  Yoga mat anti slip    Sports        Rs.   599.00
==================================================================

==================================================================
  AFTER BACKWARD PLACEHOLDER INSERTION (9 listings)
==================================================================
  Cotton kurti set      Fashion       Rs.   899.00
  Brass diya            HomeDecor     Rs.    79.00
  Organic face serum    Beauty        Rs.  1199.00
  REVIEW REQUIRED       Electronics   Rs.     0.00
  Phone case            Electronics   Rs.     0.50  [FLAG]
  Stainless steel tiffin Kitchen      Rs.   349.00
  REVIEW REQUIRED       Fashion       Rs.     0.00
  Branded handbag       Fashion       Rs. 750000.00  [FLAG]
  Yoga mat anti slip    Sports        Rs.   599.00
==================================================================

  Flagged listings: 2 | Placeholders inserted: 2

Performance Considerations

Key insight for LinkedList: add() and remove() at the current position are O(1) for LinkedList's ListIterator because it holds a direct Node reference — no traversal needed for the modification. For ArrayList, the same operations are O(n) because elements must shift. When a traversal pattern involves many mid-list insertions or removals, LinkedList + ListIterator is genuinely faster than ArrayList + ListIterator.

Memory: A ListIterator object is heavier than a plain Iterator by a few fields (the extra add flag tracking) but still lightweight — a few dozen bytes regardless of the list size.

Best Practices

Use listIterator(fromIndex) when only part of the list needs processing. Creating a ListIterator at position 0 and calling next() to skip to a known start position is O(n) for LinkedList. Calling list.listIterator(fromIndex) directly is O(1) — it constructs the cursor at the right position immediately for ArrayList and O(n/2) at worst for LinkedList. Skipping elements manually wastes time and makes intent less clear.

Never call set() immediately after add() or remove(). Both operations reset lastRet to -1, which makes the "last returned element" undefined. A subsequent set() call throws IllegalStateException. If you need to add an element and then update it, add it with the desired final value in the first place.

Prefer ListIterator over manual index loops for bidirectional scans on large LinkedLists. A for loop with linkedList.get(i) on a LinkedList is O(n) per access — the full loop is O(n²). ListIterator on LinkedList is O(n) total for a full traversal because it holds a direct Node reference and never re-traverses. This is one of the few cases where LinkedList genuinely outperforms ArrayList.

Keep the traversal direction consistent within a single pass. Mixing next() and previous() calls unpredictably in the same traversal produces confusing cursor behaviour and hard-to-debug off-by-one errors. If a single pass needs both directions, finish the full forward sweep before switching to backward, or use two separate ListIterator instances with defined starting positions.

Common Mistakes

Mistake 1 — Calling set() After add() or remove()

Mistake 2 — Expecting next() to Return an Element Added with add()

Output:
next after add: Y

Mistake 3 — Using ListIterator on a Set or Queue

Mistake 4 — Structural Modification Outside the ListIterator

Interview Questions

Q1. What is the difference between Iterator and ListIterator in Java?

Iterator is the base traversal interface — forward-only, available on any Collection, three methods: hasNext(), next(), remove(). ListIterator extends Iterator and is specific to List — it adds backward traversal with hasPrevious() and previous(), cursor position awareness with nextIndex() and previousIndex(), in-place replacement with set(element), and mid-traversal insertion with add(element). ListIterator can also be started at any position via list.listIterator(index). It is available only on ArrayList, LinkedList, and Vector.

Q2. What does set() do in ListIterator and when does it throw?

set(element) replaces the element most recently returned by next() or previous(). The cursor does not move — only the element at lastRet is replaced. It throws IllegalStateException in two cases: if neither next() nor previous() has been called since the iterator was created, or if remove() or add() was called after the last next()/previous() (both reset lastRet to -1). set() is not a structural change — it does not increment modCount — so it does not invalidate the iterator.

Q3. What does add() do to the cursor position in ListIterator?

add(element) inserts the new element immediately before the element that would have been returned by next(). The cursor advances past the inserted element, so a subsequent next() call returns the element that was originally at the cursor position — not the inserted element. previousIndex() after add() returns the index of the inserted element, so calling previous() immediately after add() returns the inserted element. add() also resets lastRet to -1, preventing set() or remove() from following it.

Q4. Why is ListIterator only available on List and not Set or Queue?

ListIterator requires the collection to have a stable, integer-based positional model — nextIndex() and previousIndex() must return meaningful values, and listIterator(index) must construct the cursor at a specific position. Set has no defined ordering for most implementations and no index-based access. Queue has a defined order but no get(index) semantic. Only List guarantees a stable, sequential, zero-based index for all positions, which makes the positional cursor model of ListIterator coherent.

Q5. When would you use ListIterator over a standard index loop on ArrayList?

Use ListIterator over an index loop on ArrayList when: (1) bidirectional traversal is needed without reversing the list, (2) in-place replacement with set() is cleaner than list.set(i, value) with a manually tracked index, (3) mid-traversal insertion with add() is needed and you want the iterator to handle index bookkeeping, or (4) the code operates on List<E> generically without knowing whether it is ArrayList or LinkedList. For pure ArrayList with simple forward access, an index loop is equally efficient and sometimes more readable.

Q6. How does ListIterator handle ConcurrentModificationException compared to Iterator?

Exactly the same mechanism. ListIterator inherits the modCount/expectedModCount fail-fast behaviour from the underlying collection's iterator implementation. Structural changes outside the ListIterator — calling list.add() or list.remove() directly — increment modCount without updating the iterator's expectedModCount, causing ConcurrentModificationException on the next next() or previous() call. The ListIterator's own add() and remove() methods update expectedModCount after the structural change, so they are safe.

FAQs

Can you use ListIterator to reverse a List in Java?

Not directly — ListIterator does not reverse a list, it traverses backward. To reverse, use Collections.reverse(list) for in-place reversal, or iterate backward with list.listIterator(list.size()) and collect into a new list. ListIterator's backward traversal is useful when you need to process elements in reverse without changing the original order.

What happens if you call previous() at the start of the list?

previous() throws NoSuchElementException when the cursor is at position 0 — hasPrevious() returns false at that point. The pattern is the same as next() at the end: always guard previous() with a hasPrevious() check in a while loop.

Does ListIterator work with immutable lists like List.of()?

List.of() returns an immutable list. Calling listIterator() on it creates a ListIterator — hasNext(), next(), hasPrevious(), previous(), nextIndex(), and previousIndex() all work. However, add(), remove(), and set() throw UnsupportedOperationException because the list does not support modification. Read-only traversal in both directions works fine.

Is there a ListIterator equivalent for Map?

No. Map does not support ListIterator. The map equivalent for controlled bidirectional traversal is NavigableMap — TreeMap's headMap(), tailMap(), descendingMap(), and descendingKeySet() provide range views and reverse-order iteration. For entry-level iteration, map.entrySet().iterator() is the standard approach.

Can set() and add() be called in the same iteration step?

add() followed by set() throws IllegalStateException because add() resets lastRet to -1. set() followed by add() is valid — set() does not reset lastRet. If you need both for the same logical position, call set() first, then add(). The inserted element will appear after the replaced element in forward order.

What is the time complexity of creating a ListIterator at a specific index?

For ArrayList, list.listIterator(index) is O(1) — it simply sets the cursor integer to index. For LinkedList, it is O(min(index, size - index)) — the implementation traverses from the closer end (head or tail) to reach the starting position. For a 1,000-element LinkedList, starting at index 500 requires 500 node traversals.

Summary

ListIterator<E> is the full-featured traversal interface for Java List implementations. It extends Iterator with six additional methods: backward traversal (hasPrevious(), previous()), cursor position reporting (nextIndex(), previousIndex()), in-place replacement (set(element)), and mid-traversal insertion (add(element)).

The cursor sits between elements, not on them. next() returns the element at the cursor and advances forward; previous() steps back and returns the element it passes. set() replaces the last-returned element without moving the cursor. add() inserts before the current forward position and advances the cursor past the inserted element — so the inserted element is never returned again by the same next() call.

For interviews: know the full method list and what distinguishes ListIterator from Iterator, explain when set() throws IllegalStateException, describe what add() does to the cursor position, and clarify why ListIterator is List-only. These questions appear in technical interviews both as standalone questions on Java collections and as part of data-structure traversal problems.

What to Read Next