iter.Seq and iter.Seq2

## The declaration Go's `iter` package contains almost nothing: two type declarations and two functions. The two types are ```go type Seq[V any] func(yield func(V) bool) type Seq2[K, V any] func(yield func(K, V) bool) ``` That is the whole definition of an iterator in Go. An `iter.Seq[V]` value is a **function value**. It is not an object with a `Next` method, not an interface, not a channel, and not a lazy collection holding buffered elements. If you come from a language where iteration is an interface with `hasNext`/`next` or a class implementing `IEnumerable`, this is the single adjustment to make: Go turned the relationship inside out. ## Push, not pull In the interface style, the *consumer* drives: it repeatedly asks the iterator for the next element. Go's `Seq` is the opposite — a **push** iterator. The consumer hands the producer a callback, conventionally named `yield`, and the producer runs its own loop, calling `yield` once per element. Control lives inside the iterator function for the whole traversal; the loop body is a guest that gets called back. That is why the iterator does not need to store a position between calls. A pull iterator must remember where it stopped, because it returns to the caller after each element. A push iterator never stops in the middle — its own local variables, its own `for` loop, its own open file handle, all stay live on its stack for the duration. ## What `for range` does with it Given `seq` of type `iter.Seq[string]`, the loop ```go for s := range seq { use(s) } ``` compiles to roughly: build a function `func(s string) bool { use(s); return true }`, call `seq` with it, and let each invocation of that function be one iteration. The `bool` result is how the loop tells the producer whether to keep going — `true` for continue, `false` for stop. A useful consequence: because a `Seq` is a plain function, you are not obliged to use `for range` at all. You can call it directly with a callback of your own: ```go seq(func(s string) bool { fmt.Println(s) return true }) ``` This is the same traversal, written by hand. It is occasionally handy inside a helper that needs to do something the loop syntax makes awkward, and it makes concrete what the `for range` form is sugar for. ## `Seq` versus `Seq2` `Seq2[K, V]` is identical in spirit; its `yield` takes two arguments and delivers both in a single call — an index and an element, a key and a value, a page number and a decoded page. The names `K` and `V` are just type-parameter names and carry no requirement that the first value be a key, be unique, or be comparable. ## The names are a convention, not magic The compiler does not look at the type's *name* when it compiles a `for range` over a function. It looks at the **shape**: `func(func() bool)`, `func(func(V) bool)` or `func(func(K, V) bool)`. A locally declared `type Lines func(yield func(string) bool)`, or even a bare unnamed `func(func(string) bool)`, ranges exactly the same way, with no import of `iter` anywhere. So why do the named types exist? For agreement. When every package that produces a sequence writes `iter.Seq[T]` in its signature, callers read one spelling, documentation links to one place, and generic helpers can accept sequences from unrelated libraries without conversion. The value of `iter.Seq` is API vocabulary, not compiler behaviour. ## What the type does *not* promise Because `Seq` is only a function type, its guarantees stop at the signature. It does not promise that the sequence is finite, that ranging it twice will produce the same elements — or any elements at all the second time — that it is safe to call from two goroutines at once, or that any resource it opened will be released if the traversal is abandoned. Those are properties of the particular function you were handed, and they belong in the producing API's documentation. ## What to say in an interview "`iter.Seq[V]` is `func(yield func(V) bool)`. An iterator in Go is a function that pushes values into a callback; `for v := range seq` compiles the loop body into that callback, and `yield`'s `bool` result is how the loop says whether it wants more. `Seq2` is the two-value version. The names are a shared convention — the compiler matches on the function shape, not on the `iter` package."