Java ArrayList.listIterator()

In Java, the ArrayList.listIterator() returns a ListIterator that iterates over the elements of the current list. A ListIterator is a bi-directional iterator that is fail-fast in nature. By default, elements returned by the list iterator are in proper sequence.

1. ArrayList.listIterator() Method

The listIterator() method is overloaded and comes in two variants:

• ListIterator listIterator() – Returns a list iterator over the elements in this list.
• ListIterator listIterator(int index) – Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list. The specified index indicates the first element that would be returned by an initial call to next. An initial call to previous would return the element with the specified index minus one.

Method parameter – index of the first element to be returned from the list iterator.
Method returns – a list iterator over the elements.
Method throws – IndexOutOfBoundsException – if the index is out of range (less than 0 or greater than list size).

2. Example

The following Java program iterates an ArrayList using a list iterator obtained through listIterator() method and iterates the list in the forward and backward directions.

ArrayList<String> alphabets = new ArrayList<>(Arrays.asList("A", "B", "C", "D"));
 
ListIterator<String> listItr = alphabets.listIterator();
 
System.out.println("===========Forward=========");
 
while(listItr.hasNext()) {
    System.out.println(listItr.next());
}
 
System.out.println("===========Backward=========");
 
while(listItr.hasPrevious()) {
    System.out.println(listItr.previous());
}

Program output.

===========Forward=========
A
B
C
D

===========Backward=========
D
C
B
A

3. Add and Remove Elements during Iteration

ListIterator supports adding and removing elements in the list while we are iterating over it.

• listIterator.add(Element e) – The element is inserted immediately before the element that would be returned by next() or after the element that would be returned previous() method.
• listIterator.remove() – Removes from the list the last element that was returned by next() or previous() method.

ArrayList<String> alphabets = new ArrayList<>(Arrays.asList("A", "B", "C", "D"));
 
ListIterator<String> listItr = alphabets.listIterator();
 
listItr.next(); //A
listItr.next();   //B
 
listItr.add("E");       
 
System.out.println(alphabets); //["A", "B", "E", "C", "D"]
 
listItr.next();   //C
 
listItr.remove();       
 
System.out.println(alphabets); //["A", "B", "E", "D"]

4. ListIterator is Fail fast

ListIterator is fail fast. It means if we modify the arraylist after the list iterator is created, then it will throw ConcurrentModificationException on next() or previous() method call.

ArrayList<String> alphabets = new ArrayList<>(Arrays.asList("A", "B", "C", "D"));

ListIterator<String> listItr = alphabets.listIterator();

listItr.next();     //A
listItr.next();     //B
   
alphabets.add("E");       

System.out.println(alphabets);  //["A", "B", "C", "D", "E"]

System.out.println(listItr.next());     //Error

Program output.

A
B
[A, B, C, D, E]
Exception in thread "main" java.util.ConcurrentModificationException
	at java.util.ArrayList$Itr.checkForComodification(ArrayList.java:901)
	at java.util.ArrayList$Itr.next(ArrayList.java:851)
	at com.howtodoinjava.example.ArrayListExample.main(ArrayListExample.java:22)

5. Differences between Iterator and ListIterator

That’s all for the ArrayList listIterator() in Java.

Happy Learning !!