Java: Iterators

The List and Set collections provide iterators, which are objects that allow going over all the elements of a collection. The java.util.Iterator interface provides for one-way traversal and java.util.ListIterator provides two-way traversal. Iterator is a replacement for the Enumeration class which was used before collections were added to Java.

Creating an Iterator

Iterators are created by calling the iterator() or listIterator() method of a List or Set.

Iterator Methods

Iterator defines three methods, one of which is optional.

Result	Method	Description
`b =`	`it.hasNext()`	`true` if there are more elements for the iterator.
`obj =`	`it.next()`	Returns the next object. If a generic list is being accessed, the iterator will return something of the list's type. Pre-generic Java iterators always returned type `Object`, so a downcast was usually required.
	`it.remove()`	Removes the most recent element that was returned by `next`. Not all collections support `delete`. An UnsupportedOperationException will be thrown if the collection does not support remove().

Example with Java 5 generics

An iterator might be used as follows.

ArrayList<String> alist = new ArrayList<String>();
// . . . Add Strings to alist

for (Iterator<String> it = alist.iterator(); it.hasNext(); ) {
    String s = it.next();  // No downcasting required.
    System.out.println(s);
}

Example Pre Java 5

An iterator might be used as follows.

ArrayList alist = new ArrayList();
// . . . Add Strings to alist

for (Iterator it = alist.iterator(); it.hasNext(); ) {
    String s = (String)it.next();  // Downcasting is required pre Java 5.
    System.out.println(s);
}

ListIterator methods

ListIterator is implemented only by the classes that implement the List interface (ArrayList, LinkedList, and Vector). ListIterator provides the following.

Result	Method	Description
Forward iteration
`b =`	`it.hasNext()`	`true` if there is a next element in the collection.
`obj =`	`it.next()`	Returns the next object.
Backward iteration
`b =`	`it.hasPrevious()`	`true` if there is a previous element.
`obj =`	`it.previous()`	Returns the previous element.
Getting the index of an element
`i =`	`it.nextIndex()`	Returns index of element that would be returned by subsequent call to next().
`i =`	`it.previousIndex()`	Returns index of element that would be returned by subsequent call to previous().
Optional modification methods. UnsupportedOperationException thrown if unsupported.
	`it.add(obj)`	Inserts obj in collection before the next element to be returned by `next()` and after an element that would be returned by `previous()`.
	`it.set()`	Replaces the most recent element that was returned by `next` or `previous()`.
	`it.remove()`	Removes the most recent element that was returned by `next()` or `previous()`.

BAD BAD BAD

Q: What does this loop do?

ArrayList<String> alist = new ArrayList<String>();
// . . . Add Strings to alist

int i = 0;
for (Iterator<String> it = alist.iterator(); it.hasNext(); ) {
    System.out.println(alist.get(i++));
}

A: It throws an exception when it goes beyond the end.

After hasNext() returns true, the only way to advance the iterator is to call next(). But the element is retrived with get(), so the iterator is never advanced. hasNext() will continue to always be true (ie, there is a first element), and eventually the get() will request something beyond the end of the ArrayList. Use either the iterator scheme.

for (Iterator<String> it = alist.iterator(); it.hasNext(); ) {
    System.out.println(it.next());
}

Or the indexing scheme, but don't mix them.

for (int i=0; i < alist.size(); i++) {
    System.out.println(alist.get(i));
}