The iter Package

iter holds two function types and two functions. Everything in Go that hands back a sequence, maps.Keys and slices.All included, is shaped by what is on this page.

Examples

An iterator is a function that takes yield and calls it once per element.

// Words returns an iterator over the whitespace-separated words in s.
func Words(s string) iter.Seq[string] {
    return func(yield func(string) bool) {
        for _, w := range strings.Fields(s) {
            if !yield(w) {
                return
            }
        }
    }
}

func main() {
    for w := range Words("the quick brown fox") {
        if w == "brown" {
            break
        }
        fmt.Println(w)
    }
}

Output

the
quick

Seq2 yields two values, so the range loop has two variables.

type Inventory struct {
    stock map[string]int
}

// All returns an iterator over every item and its count.
func (inv *Inventory) All() iter.Seq2[string, int] {
    return func(yield func(string, int) bool) {
        for _, name := range []string{"bolt", "nut", "washer"} {
            if !yield(name, inv.stock[name]) {
                return
            }
        }
    }
}

func main() {
    inv := &Inventory{stock: map[string]int{"bolt": 12, "nut": 30, "washer": 0}}
    for name, count := range inv.All() {
        fmt.Printf("%-7s %d\n", name, count)
    }
}

Output

bolt    12
nut     30
washer  0

Zipping two sequences needs one of them driven by hand.

// Zip pairs values from two sequences, stopping at the shorter one.
func Zip[A, B any](as iter.Seq[A], bs iter.Seq[B]) iter.Seq2[A, B] {
    return func(yield func(A, B) bool) {
        nextB, stop := iter.Pull(bs)
        defer stop()
        for a := range as {
            b, ok := nextB()
            if !ok {
                return
            }
            if !yield(a, b) {
                return
            }
        }
    }
}

func main() {
    names := slices.Values([]string{"alice", "bob", "carol"})
    scores := slices.Values([]int{91, 84})
    for name, score := range Zip(names, scores) {
        fmt.Println(name, score)
    }
}

Output

alice 91
bob 84

Types

Type	Description
type Seq[V any] func(yield func(V) bool)	A sequence of single values. A range loop over one of these calls it.
Input `yield`, supplied by the range loop. Call it once per element. Output Each element of the sequence, handed to `yield` one at a time. Behavior `yield` returns `false` when the loop wants to stop, which is what a `break` or an early `return` in the loop body turns into. Return from the iterator as soon as it does. Calling `yield` again after it returned `false` panics. Use when A function or method hands back a sequence. The convention is to name the method `All`, and to name it for the sequence when a type has more than one. Every iterator you write has the same three layers: a function returning a `Seq`, a closure taking `yield`, and a loop that calls it. The check on `yield`'s return is the part that makes a `break` in the caller work. `func Lines(r io.Reader) iter.Seq[string] { return func(yield func(string) bool) { sc := bufio.NewScanner(r) for sc.Scan() { if !yield(sc.Text()) { return } } } }`
type Seq2[K, V any] func(yield func(K, V) bool)	A sequence of pairs. Key and value, or index and value.
Input `yield`, taking two values instead of one. Output Each pair in the sequence, handed to `yield` one pair at a time. Behavior The same contract as `Seq`. Stop the moment `yield` returns `false`. Use when The elements come in twos. `maps.All` is a `Seq2` of key and value, and a sequence over a slice would pair index with element.

Functions

Function	Description
Pull[V any](seq Seq[V]) (next func() (V, bool), stop func())	Turns a sequence into a next() you call yourself.
Input `seq`, the sequence to walk. Output `next`, returning the following value and whether there was one. `stop`, which ends the walk and lets the iterator run its own cleanup. Behavior Once the sequence is finished `next` reports `false` and keeps reporting it. `stop` is safe to call more than once, and safe to call from the same goroutine at any point. Use when Two sequences have to advance in step, or a value has to be inspected before you decide whether to ask for another. A range loop does neither. A pulled iterator is paused between calls, holding whatever the sequence opened. `stop` is what lets it finish and release that, so it belongs on a `defer` on the line after the `Pull`. `next, stop := iter.Pull(seq) defer stop() first, ok := next() if !ok { return errors.New("empty sequence") }`
Pull2[K, V any](seq Seq2[K, V]) (next func() (K, V, bool), stop func()) `next, stop := iter.Pull2(seq)`	The same, for a sequence of pairs.
Input `seq`, the sequence of pairs to walk. Output `next`, returning the key, the value, and whether there was a pair. `stop`, which ends the walk. Behavior Identical to `Pull` in every other respect, the deferred `stop` included.

The yield contract

Check what yield returns. A false means the loop body ran a break, a return, or a goto, and the iterator has to return there and then.

One more call panics. Once yield has returned false, calling it again takes the program down. This is why the check is written as an early return rather than a flag you test later.

Say so when a sequence runs once. An iterator over a network stream or a scanner cannot be restarted, and the caller has no way to tell from the type. Document it on the function that returns it.

slices All, Values, Collect, and Sorted move between a slice and a sequence.maps Keys, Values, and All are the sequences a map hands out.For loops The range loop is what calls an iterator.Generics Seq is a generic function type, so an iterator works for any element.

Previous io/ioutil Next Topic log

The iter Package

Examples

Types

Functions

The yield contract

Related