feat(iterator): add package to help work with new iter.Seq types

v2/iterator/example_test.go

@@ -0,0 +1,75 @@
+// Copyright 2024, Google Inc.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//     * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//     * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//     * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+//go:build go1.23
+
+package iterator_test
+
+import (
+	"fmt"
+	"iter"
+
+	"github.com/googleapis/gax-go/v2/iterator"
+	otherit "google.golang.org/api/iterator"
+)
+
+type exampleType struct {
+	data []int
+	i    int
+}
+
+func (t *exampleType) next() (int, error) {
+	var v int
+	if t.i == len(t.data) {
+		return v, otherit.Done
+	}
+	v = t.data[t.i]
+	t.i++
+	return v, nil
+}
+
+func (t *exampleType) All() iter.Seq2[int, error] {
+	return iterator.RangeAdapter[int](t.next)
+}
+
+func ExampleRangeAdapter() {
+	t := &exampleType{
+		data: []int{1, 2, 3},
+	}
+	for v, err := range t.All() {
+		if err != nil {
+			// TODO: handle error
+		}
+		fmt.Println(v)
+	}
+	// Output:
+	// 1
+	// 2
+	// 3
+}

v2/iterator/iterator.go

@@ -0,0 +1,63 @@
+// Copyright 2024, Google Inc.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//     * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//     * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//     * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+//go:build go1.23
+
+// Package iterator contains helper for working with iterators. It is meant for
+// internal use only by the Go Client Libraries.
+package iterator
+
+import (
+	"iter"
+
+	otherit "google.golang.org/api/iterator"
+)
+
+// RangeAdapter transforms client iterator type into a [iter.Seq2] that can
+// be used with Go's range expressions.
+//
+// This is for internal use only.
+func RangeAdapter[T any](next func() (T, error)) iter.Seq2[T, error] {
+	var err error
+	return func(yield func(T, error) bool) {
+		for {
+			if err != nil {
+				return
+			}
+			var resp T
+			resp, err = next()
+			if err == otherit.Done {
+				return
+			}
+			if !yield(resp, err) {
+				return
+			}
+		}
+	}
+}