Description
Proposal Details
Background
The iter package was introduced in Go 1.22 as a new standard library package
for working with iterators. It provides important abstractions like Seq and
Seq2 types, along with the Pull and Pull2 functions.
Currently, the package has comprehensive documentation in the comment blocks,
but lacks an example_test.go file with concrete, runnable examples. This
makes it harder for users to understand the idiomatic usage patterns for
iterators, especially for the Pull functions.
Proposal
Add an example_test.go file to the iter package that demonstrates:
- Basic usage of Seq and Seq2 iterators
- How to properly create and consume iterators with range loops
- How to use Pull and Pull2 functions, including proper resource cleanup
- Common patterns for chaining and transforming iterators
- Examples of creating custom iterators
Expected Benefits
Having clear, runnable examples will:
- Help users understand the iterator patterns more concretely
- Demonstrate best practices for iterator usage (such as proper cleanup)
- Provide copy-pastable code examples for common use cases
- Complement the existing documentation with practical implementations
These examples would be especially helpful for this new package as developers
are still learning the idiomatic ways to use iterators in Go.
Implementation Plan
I'm willing to implement this improvement by creating a new example_test.go
file with comprehensive examples if the proposal is accepted.
/cc @golang/docs