Tech and Media Labs
This site uses cookies to improve the user experience.


Java Iterable

Jakob Jenkov
Last update: 2019-01-30

The Java Iterable interface (java.lang.Iterable) is one of the root interfaces of the Java Collections API. A class that implements the Java Iterable interface can be iterated with the Java for-each loop. By iterating I mean that its internal elements can be iterated. You will see examples of this later in this tutorial.

Implementations of Iterable in Java

There are several classes in Java that implements the Java Iterable interface. These classes can thus have their internal elements iterated via the Java for-each loop.

There are also several Java interfaces that extends the Iterable interface. Classes implementing an interface which extends the Iterable interface thus also implement the Iterable interface. Such classes can also be used with the for-each loop.

The Collection interface extends Iterable, so all subtypes of Collection also implement the Iterable interface. For instance, both the Java List and Set interfaces extend the Collection interface, and thereby also the Iterable interface.

Using an Iterable With the for-each Loop

As mentioned several times earlier, an object of a class that implements the Iterable can be used with the Java for-each loop. Since the Java List interface extends the Collection interface, and the Collection interface extends the Iterable interface, a List object can be used with the for-each loop. Here is an example of using a List object with the for-each loop:

List list = new ArrayList();

list.add("one");
list.add("two");
list.add("three");

for(Object o : list){
    System.out.println(o.toString());
}

This example first creates a new List and adds 3 elements to it. Then it uses a for-each loop to iterate the elements of the List, and print out the toString() value of each element.

Iterable Interface Definition

The Java Iterable interface has only one method named iterator(). This method must return a Java Iterator which can be used to iterate the elements of the object implementing the Iterable interface. Obtaining the Iterator happens behind the scenes, so you don't see that done. The Java compiler takes care of generating the code for that, when you use a Iterable with the for-each loop.

Here is how the Java Iterable interface is defined:

public interface Iterable<T> {
  public Iterator<T> iterator();    
}

Implementing the Iterable Interface

How you implement this Iterable interface so that you can use it with the for-each loop, is explained in the text Implementing the Iterable Interface, in my Java Generics tutorial.

Here I will just show you a simple Iterable implementation example though:

public class Persons implements Iterable {
    private List<Person> persons = new ArrayList<Person>();    
    
    public Iterator<Person> iterator() {
        return this.persons.iterator();
    }
}

An instance of Persons can be used with the Java for-each loop like this:

Persons persons = ... //obtain Persons instance with Person objects inside.

for(Person person : persons) {
    // do something with person object.
}

Iterable Performance

If you are writing some code that needs to iterate a collection lots of times in a tight loop, let's say iterate a Java List thousands of times per second, iterating the List via the Java for-each loop is slower than iterating the list via a standard for-loop as seen here: () .

for(int i=0; i<list.size(); i++) {
    Object obj = list.get(i);
}

The reason the for-each loop is slower is, that each iteration will call the List iterator() method, which will create a new Iterator object. Creating a new object thousands, perhaps even millions of times per second does have a small performance penalty compared to just iterating the List using a standard for-loop.

For most standard business applications where collections are iterated occasionally, this performance difference is irrelevant. It only matters for very tight loops that are executed thousands of times per second.

Jakob Jenkov




Copyright  Jenkov Aps
Close TOC