The for-each Loop in Java (Enhanced for Loop)

The for-each loop, also called the enhanced for loop, runs a block of code once for each item in an array or a collection, handing you the items one at a time in a variable. You write it as for (String name : names)and read it aloud as “for each name in names”. This page shows it with arrays, lists and maps, when a counting for loop is the better choice, and what the for-each loop cannot do. Every example runs in the page.

Press Run and step through it. On the first pass fruit holds "apple", on the second "banana", on the third "cherry", and then the loop ends by itself. The program prints I like apple, I like banana and I like cherry.

The header has three parts:

• String fruit declares the loop variable. Its type has to fit the items (a String array gives String items), and you choose its name.
• The colon reads as “in”.
• fruits is what you loop over: an array, or any object whose class implements Iterable, which every collection does, from ArrayList to HashSet.

There is no counter to manage, so the loop cannot step past the end of the array. The Java Language Specification calls this loop the enhanced for statement, the second form of the for statement next to the counting loop. With while and do-while, that makes Java's three loop statements, which the loops lesson teaches from the start.

For-each loop with an ArrayList#

A list works the same way as an array. This loop adds up a list of scores:

It prints Total: 247. The list holds Integer objects while score is a plain int: Java unboxes each value as it comes out of the list. Writing for (Integer score : scores) works too.

Using var in the loop header#

Since Java 10 you can write var in place of the type and let Java work it out from what you loop over. In for (var score : scores), score is an Integer, and over a String[] array, var means String. It saves the most typing on long types, such as the map entries below.

Loop over a Map with for-each#

Writing for (String key : stock) over a map does not compile: javac stops with for-each not applicable to expression type, because a Map is not Iterable. It hands out three views that are: entrySet() for the key and value pairs, keySet() for the keys and values() for the values.

Each entry is a Map.Entry, a pair with getKey() and getValue(). With var the first header shrinks to for (var entry : stock.entrySet()). A TreeMap keeps its keys sorted, so the program prints apples: 12, pears: 4 and plums: 0, then the three names on one line, then In stock: 16. A HashMaploops the same way, but in an order that comes from the keys' hash codes, which need not be the order you put them in; a LinkedHashMap keeps that order.

For loop vs for-each loop: which to use#

Use the for-each loop when you need each item and nothing else. Use the counting loop, the one with a counter such as i, when the position matters:

• You need the index, for example to number the items or to compare each one with the one before it.
• You go backwards, or skip items, as an update of i = i + 2 does.
• You replace items: prices[i] = 0; changes the array, and assigning to a for-each variable does not.
• You walk two arrays side by side, reading names[i] and scores[i] together.

Key idea

Reach for the for-each loop by default, and switch to the counting loop as soon as you need to know where you are.

How to get the index in a for-each loop#

The for-each loop hides the index, so there is none to ask for. When you need a position, keep your own counter, or switch to the counting loop. Both loops below number the same three names:

The first loop prints 1. Ada, 2. Grace and 3. Linus. The counter starts at 1 because people count from one, and place++ at the end of the body moves it on for the next pass. The second loop prints podium[0] = Ada and so on, because indexes start at 0. If you catch yourself keeping a counter and also reading podium[place - 1], the counting loop is the clearer choice.

Can a for-each loop change the array?#

No. The loop variable holds a copy of the current item, so assigning a new value to it changes the variable and leaves the array as it was. Step through this and watch name change while names stays the same:

The first line printed is [ada, grace, linus]. Each pass made a new, uppercase string and stored it in name, and the next pass overwrote it. Java gives no error and no warning for that loop. The counting loop writes through the index, names[i] = ..., so the second line is [ADA, GRACE, LINUS]. On an ArrayList, do the same with list.set(i, ...) in a counting loop, or in one call with list.replaceAll(s -> s.toUpperCase()).

Changing an object through the loop variable does work#

When the items are objects, the loop variable refers to the same object the list holds. Assigning to the variable still leaves the list alone, but changing a field through it changes the object itself:

It prints Dune: 7 and Emma: 5. In the memory view, book points at the same Book object as the list slot it came from, so the change is there when the second loop reads the list. Methods follow the same rule with their arguments, as the methods lesson shows under pass by value.

Key idea

Assigning to the loop variable never changes the array or list. Changing a field of the object it refers to does, because the variable and the list point at the same object.

Removing items in a for-each loop: ConcurrentModificationException#

Calling remove on a list while a for-each loop walks it stops the program with a ConcurrentModificationException. Run this one to the end:

Java stops at the for line with Exception in thread "main" java.util.ConcurrentModificationException, and the last line never runs. A for-each loop walks a list with a hidden iterator, an object that remembers where it is, and the iterator checks that the list has not changed each time it fetches the next item. Removing "skit" changed the list behind its back. Adding inside the loop fails the same way. The name mentions concurrency, but one thread is enough to cause it.

Two safe ways: Iterator.remove() and removeIf()#

Write the iterator loop yourself, so you can reach the iterator, and remove through it. Or hand the whole job to removeIf. This program does each on its own copy of the list:

Both lines print [intro, hit, outro]. it.next() returns the next song, and it.remove() removes the one it just returned while keeping the iterator in step, so nothing is skipped and nothing throws. removeIf, from Java 8, runs that loop for you. You give it the rule as a lambda, a small function written inline: song -> song.equals("skit")reads as “given a song, remove it if it is skit”. When the rule fits on one line, removeIf is the shorter choice.

Nested for-each loops over a 2D array#

A 2D array in Java is an array of arrays, so each item of the outer array is a whole row with the type int[]. The outer loop takes one row at a time, and an inner loop walks that row:

row holds one inner array per pass, and seat holds each number in it, nine passes of the inner loop in all. The program prints 6 of 9 seats are taken. Rows of different lengths are fine too, because the inner loop always walks the row it was given.

What the for-each loop does underneath#

The Java Language Specification (section 14.14.2) defines the for-each loop by rewriting it as an ordinary for loop, and the rewrite depends on what you loop over:

• Over an array, Java evaluates the array once, then runs a hidden index from 0 up to length - 1, and at the start of each pass copies the item at that index into your variable.
• Over anything else, Java calls iterator() once, then asks the iterator hasNext() before every pass and, while the answer is true, calls next() and stores the result in your variable. That is the same loop as the Iterator example above.

That explains the rules on this page. Your variable gets a copy, so assigning to it changes nothing else. The iterator's next() is where a changed list is noticed. And the loop accepts exactly two things: arrays, and objects whose class implements the Iterable interface. A Map does not, which is why you loop over its entrySet().

Make your own class work in a for-each loop#

Implement Iterable<T> and your own objects work in a for-each loop. The one method you write is iterator(), which returns an Iterator<T>: an object with hasNext() and next(). This Countdown counts down from a number. Step through it and watch the loop call hasNext() and next() on every pass:

It prints 3, 2 and 1 on separate lines, then Liftoff!. The loop called iterator() once, next() three times and hasNext() four times: the fourth answer, false, ended it. next() throws NoSuchElementException when nothing is left, as the Iterator documentation asks, in case other code calls it without checking first. The Collections Framework lesson covers iterators in depth.

Is the for-each loop slower than a for loop?#

Not over an array: the specification defines it as the same counting loop you would write yourself. Over a list it uses the list's iterator, and a real difference shows up with a LinkedList. Its documentation says that reaching a position means walking from the nearer end of the list, so a counting loop that calls get(i) walks further and further as the list grows, while the for-each loop steps from each item straight to the next. On an ArrayList, get(i) takes the same short time at any position, so either loop is fine.

The for-each loop vs the forEach() method#

Since Java 8, collections also have a forEach()method. You pass it a lambda, and it runs the lambda once for each item, in the same order a for-each loop would. A map's forEach() hands the lambda both the key and the value:

The first call prints Hi, Ada, Hi, Grace and Hi, Linus. The second prints the three names: System.out::println is a method reference, a shorter way to write name -> System.out.println(name). The map prints Ada is 36 and Grace is 85.

Use the for-each loop by default. forEach() fits when the whole body is one short action, such as printing each item.