From d7c3e93c16eeb328e9d943aa4fbd5ec8c793ec1b Mon Sep 17 00:00:00 2001 From: Harald Albrecht Date: Thu, 26 Dec 2024 21:27:33 +0100 Subject: [PATCH] iter: improve documentation with iterator example In introducing iterators, package iter gives an example of how to use an iterator in a range-over-func loop, but currently does not give an example of what an iterator implementation might look like. This change adds the example of map.Keys() before the usage example. Additionally, it references to the Go blog for further examples, as well as the language spec about for-range loops. Fixes #70986 Change-Id: I7108d341d314d7de146b4c221700736c943a9f5d Reviewed-on: https://go-review.googlesource.com/c/go/+/638895 Reviewed-by: Cherry Mui Reviewed-by: Ian Lance Taylor LUCI-TryBot-Result: Go LUCI Auto-Submit: Ian Lance Taylor --- src/iter/iter.go | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/src/iter/iter.go b/src/iter/iter.go index 14fd8f8115..e765378ef2 100644 --- a/src/iter/iter.go +++ b/src/iter/iter.go @@ -28,7 +28,22 @@ or index-value pairs. Yield returns true if the iterator should continue with the next element in the sequence, false if it should stop. -Iterator functions are most often called by a range loop, as in: +For instance, [maps.Keys] returns an iterator that produces the sequence +of keys of the map m, implemented as follows: + + func Keys[Map ~map[K]V, K comparable, V any](m Map) iter.Seq[K] { + return func(yield func(K) bool) { + for k := range m { + if !yield(k) { + return + } + } + } + } + +Further examples can be found in [The Go Blog: Range Over Function Types]. + +Iterator functions are most often called by a [range loop], as in: func PrintAll[V any](seq iter.Seq[V]) { for v := range seq { @@ -187,6 +202,9 @@ And then a client could delete boring values from the tree using: p.Delete() } } + +[The Go Blog: Range Over Function Types]: https://go.dev/blog/range-functions +[range loop]: https://go.dev/ref/spec#For_range */ package iter -- 2.48.1