The Pairs example (playground link) in the iter package doc seems incorrect, with it looping forever while emitting the same values.

Another minor issue is it has an extra bool in the returned func signature. (Probably an older signature).

If we correct the extra bool, we can see it timeout on the playground:

// Pairs returns an iterator over successive pairs of values from seq.
func Pairs[V any](seq iter.Seq[V]) iter.Seq2[V, V] {
    return func(yield func(V, V) bool) {
        next, stop := iter.Pull(seq)
        defer stop()
        v1, ok1 := next()
        v2, ok2 := next()
        for ok1 || ok2 {
            if !yield(v1, v2) {
                return
            }
        }
    }
}

One possible correction might be this.

Unless someone beats me to it (which would be fine 😅), I will probably send a CL, but opening this issue in case any discussion is needed, including maybe I misunderstood the intent.

Finally, at first was unsure if it was meant to show overlapping vs. non-overlapping pairs. (I think the intent was probably non-overlapping pairs. I think itertools.pairwise in Python and std::ranges::views::pairwise_transform in C++ on the other hand both give overlapping pairs. That's probably fine, including this is just intended to be a simple example of using iter.Pull).

Comment From: gabyhelp

Similar Issues

(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)

Comment From: seankhliao

cc @ianlancetaylor for CL 593555

Comment From: thepudds

Eh, sorry. I mostly wrote this up yesterday after checking if anyone had reported, but I was slow on posting and negligent on checking again 🙃 . Thanks @gabyhelp!

The looping forever is not reported in #68056, but a fix for that could be added to Ian's in-flight CL 593555 or a separate CL.

Comment From: ianlancetaylor

Thanks for catching that, added a fix to CL 593555.

Comment From: gopherbot

Change https://go.dev/cl/593555 mentions this issue: iter: minor doc comment updates

Comment From: AndrewHarrisSPU

Possibly irrelevant: this seems close to runnable example code that demonstrates something about the nature of the yield function. I'm not sure that's appropriate for this level of documentation. However, grokking the execution of yield is a bit of a light bulb that I believe documentation should try to flip on.

for {
    v1, ok1 := next()
    v2, ok2 := next()

    // short-circuit evaluation omits the yield of an (even-index, zero-value) pair, relative to !ok1 || !yield(v1, v2) || !ok2
    if !ok1 || !ok2 || !yield(v1, v2) { 
        return
    }
}