From: Harald Albrecht Date: Thu, 26 Dec 2024 20:27:33 +0000 (+0100) Subject: iter: improve documentation with iterator example X-Git-Tag: go1.24rc2~6^2~50 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=d7c3e93c16eeb328e9d943aa4fbd5ec8c793ec1b;p=gostls13.git 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 --- 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