gapic: untangle Iterator logic with generics

[noahdietz]

This requires Go 1.18+ be the minimum supported version for clients.

The Iterator interface has worked great but the generated code in GAPICs for it is kind of messy and confusing. With generics, we could create explore more general implementations that were more streamlined. For example (copied from internal link):

// Playing with https://github.com/golang/go/discussions/54245
// -----------------------------------------------------------------------------
// in standard library
type Iter2[E1, E2 any] interface {
	Next() (E1, E2, bool)
}
 
// -----------------------------------------------------------------------------
// in client library
// existing
 
type Secret struct{}
type SecretIterator struct{}
func (it *SecretIterator) Next() (*Secret, error) { return nil, nil }
 
// New
func (it *SecretIterator) Range() Iter2[*Secret, error] {
	return NewStdIter[*Secret](it)
}
 
// -----------------------------------------------------------------------------
// in iterator package
// existing
 
var Done = fmt.Errorf("done")
 
// New
 
// Nexter is an interface all client library iterators implement.
type Nexter[T any] interface {
	Next() (T, error)
}
 
func NewStdIter[T any](from Nexter[T]) Iter2[T, error] {
	return stdIteratorAdapter[T]{from}
}
 
type stdIteratorAdapter[T any] struct {
	n Nexter[T]
}
 
func (n stdIteratorAdapter[T]) Next() (T, error, bool) {
	r, err := n.n.Next()
	if err == Done {
		var zero T
		return zero, nil, false
	}
	return r, err, err == nil
}
 
// -----------------------------------------------------------------------------
// Old usage
 
it := c.ListSecrets(ctx, req)
for {
	resp, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}
 
// New usage
for resp, err := range c.ListSecrets(ctx, req) {
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}