iter: Pull example in package doc loops forever

[thepudds]

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).

[gabyhelp]

Similar Issues

• iter: example Pairs in package doc uses wrong (outdated?) signature for iter.Seq2 #68056

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

[seankhliao]

cc @ianlancetaylor for CL 593555

[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.

[ianlancetaylor]

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

[gopherbot]

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

[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
	}
}