Skip to content
Tutorials Center
My learning

Topics

Lesson 59 of 147 ยท Generics

Iterators: range over Functions

Learn Go iterators from scratch - iter.Seq and Seq2, writing yield functions, early exit rules, lazy Filter/Map/Take pipelines, slices and maps helpers, iter.Pull, and iterators vs channels.

A for range loop works over slices, maps, strings, channels and integers. Since Go 1.23 it also works over functions. That one addition lets any collection (a tree, a database cursor, the lines of a file, an infinite sequence) offer a plain for loop to its callers, without building a slice first and without starting a goroutine.

An iterator in Go is just a function that hands its values to a callback, conventionally called yield. The standard iter package gives the two shapes a name, and the slices, maps and strings packages already return iterators from many of their functions. Iterators rely on generics for their types and on closures for their state, so this lesson is where the previous chapters come together. We look at how to write them, the rules for stopping early, how to compose them into lazy pipelines, the "pull" style with iter.Pull, and when a channel is the better choice.

The shape of an iterator

The iter package defines two generic function types:

Go
type Seq[V any] func(yield func(V) bool)
type Seq2[K, V any] func(yield func(K, V) bool)

A Seq[V] is a function that calls yield(v) once for each value. Seq2[K, V] yields pairs, like the index and value of a slice. The bool that yield returns means "keep going": it is true while the loop wants more values and false once the loop has stopped, for example because of a break, a return or a panic. An iterator must stop calling yield the moment it returns false.

Go Your first iterators

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Notice what is not happening: Fib does not build a list of Fibonacci numbers, which would never finish. It computes the next value only when the loop asks for it. The loop body is compiled into the yield function, so break simply makes yield return false.

A function that returns an iterator (Count(4)) is the usual way to write one, because it lets you pass parameters and keep state in the closure. Methods that return iterators are common too, as you will see with All() on a collection.

Two values: iter.Seq2

Seq2 is what for i, v := range needs. It works the same way, with two arguments to yield:

Go Iterating over pairs with Seq2

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Early exit: the rules iterators must follow

When the loop body ends with break, return, goto out of the loop, or a panic, the compiler-generated yield returns false. Your iterator then has two obligations: stop calling yield and clean up. Deferred calls inside the iterator function still run, which makes iterators a good place to close files or release locks:

Go Cleanup runs even when the loop breaks early

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

If an iterator ignores the false and calls yield again, the runtime catches it and panics, because the loop body it would be running no longer exists:

Go Calling yield after it returned false (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The program prints 1 and then dies with panic: runtime error: range function continued iteration after function for loop body returned false. Always write if !yield(...) { return }.

Do not call yield from another goroutine, and do not store yield for later. The loop body runs inside your iterator function's call stack; calling it after the iterator has returned panics with a similar message.

Iterating over your own data structures

The biggest win is for data structures that are not flat. A binary tree has no obvious for loop. With an iterator, the tree decides how it is walked and the caller just writes for v := range tree.All(). A recursive walk needs a small trick: the helper returns false as soon as yield does, so the recursion unwinds immediately:

Go In-order iteration over a binary search tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The expression n.left.walk(yield) && yield(n.value) && n.right.walk(yield) relies on short-circuiting. If the left subtree stops, yield is never called for this node, and the false bubbles up to the top.

Composing iterators: Filter, Map and Take

Because an iterator is just a value (a function), you can write functions that take one and return another. Each stage is lazy: it pulls one value at a time from the stage before it, so nothing is computed until the final loop asks for it, and a Take(3) over an infinite sequence stops the whole chain.

Go A lazy pipeline: Filter, Map, Take

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Read the output carefully. The checks and the results are interleaved: value 1 is checked and dropped, value 2 is checked, squared and printed, and so on. Once Take has produced three values it returns, which makes yield return false in Map, then in Filter, then in Naturals, and the infinite sequence stops. No intermediate slice was ever built.

The standard library intentionally did not add iter.Filter or iter.Map in Go 1.23, to keep the first release small. Writing them yourself takes a few lines, as above. For slices, slices.Collect, slices.Sorted and the other helpers below cover most needs.

Iterators in the standard library

Go 1.23 added iterator functions to the packages you already use. Most follow a naming pattern: functions that return an iterator are named for what they yield (All, Values, Keys, Backward, Chunk), and functions that consume one start with Collect, Sorted or Insert.

Go slices, maps and strings iterators

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

slices.Collect turns any iter.Seq into a new slice, and slices.Sorted collects and sorts in one step. Together with maps.Keys they replace the old "copy the keys into a slice, then sort" loop. strings.SplitSeq, strings.Lines and strings.FieldsSeq arrived in Go 1.24; the older strings.Split and strings.Fields still return slices.

Pull iterators: iter.Pull

The iterators so far are push iterators: the iterator drives, and the loop body is called back. That is perfect for a for range loop, but awkward when you need to walk two sequences side by side, or take one value at a time at moments you choose. iter.Pull converts a push iterator into a pair of functions, next and stop, which you call yourself:

Go iter.Pull: merging two sorted sequences

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

next returns the next value and true, or the zero value and false once the sequence ends. Call stop when you are finished, even if you did not reach the end; it lets the underlying iterator run its cleanup. The usual idiom is defer stop() right after iter.Pull. There is also iter.Pull2 for Seq2. Under the hood, iter.Pull runs the iterator on a coroutine, which is far cheaper than a goroutine plus channels but still slower than a plain for range, so prefer push iterators unless you need the pull style.

Iterators or channels?

Before Go 1.23 the standard way to give a stream of values to a caller was a channel filled by a goroutine. Iterators are usually better for sequential data:

Iterator (iter.Seq) Channel with a goroutine
Runs in the caller's goroutine a separate goroutine
Cost per value a function call a channel send and receive (synchronization)
Early break the iterator is told and cleans up the producer blocks forever unless you add a done channel
Errors and panics propagate normally to the caller must be sent over the channel
Concurrency none by itself producer and consumer overlap

The leak in the "Early break" row is real. Here is the channel version abandoned halfway, next to an iterator:

Go Breaking out of a channel producer leaks a goroutine

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Use a channel when producer and consumer should genuinely run at the same time (a worker pool, a pipeline stage with real work, events arriving from outside). Use an iterator when you simply need to walk data in order. You will meet channels in depth in Channels and the pipeline patterns in Concurrency Patterns.

Design tips

  • Name iterator methods All, Values, Keys or Backward, as the standard library does. All() on a collection should yield the same pairs range would on a built-in of the same kind.
  • Return iter.Seq rather than a slice when callers might stop early or the collection is large. Return a slice when the data is already in memory and callers usually need all of it.
  • Do not hide expensive work. If getting each value costs a network call, say so in the doc comment; the loop looks free but is not.
  • Iterators can only report errors by yielding them. Either use iter.Seq2[T, error] and check err in every loop, or store the error in the receiver and expose an Err() method like bufio.Scanner does.
  • Make each range a fresh walk. Ranging over the same Seq twice should normally produce the same values twice; if an iterator can only be consumed once (for example it reads from a network stream), say so in its doc comment.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the bool returned by yield tell the iterator?

    yield returns true while the loop wants more values. After a break, return or panic in the loop body it returns false, and the iterator must stop.
  2. 2. What happens if an iterator calls yield again after it returned false?

    The runtime detects the misuse and panics with a message that the range function continued iteration after the loop body returned false.
  3. 3. Which type does for i, v := range seq need seq to be?

    Two loop variables need an iter.Seq2, whose yield function takes two arguments. A Seq[V] allows at most one variable.
  4. 4. Why is slices.Sorted(maps.Keys(m)) the idiomatic way to list sorted map keys?

    maps.Keys yields keys in random order; slices.Sorted collects them into a new slice and sorts it.
  5. 5. When should you use iter.Pull instead of a plain for range loop?

    Pull turns a push iterator into next and stop functions, which is useful when you must consume several sequences in lockstep. Remember to call stop.

Summary

  • An iterator is a function that calls a yield callback: iter.Seq[V] for single values, iter.Seq2[K, V] for pairs. for range accepts such functions (Go 1.23).
  • yield returns false when the loop stopped; the iterator must then return without calling it again, or the runtime panics. Deferred cleanup in the iterator still runs.
  • Iterators are lazy and can be infinite; compose them with small Filter, Map and Take functions.
  • The standard library offers slices.All/Values/Backward/Chunk/Collect/Sorted, maps.Keys/Values/All/Collect/Insert and strings.SplitSeq/Lines/FieldsSeq.
  • iter.Pull turns a push iterator into next and stop for manual, lockstep iteration; always call stop.
  • Prefer iterators over channels for sequential data; use channels when producer and consumer must run concurrently.

Next: Errors as Values starts the Errors chapter with the error interface and the if err != nil idiom.