all: change the signature of Each to be a range function

README.md

@@ -7,6 +7,16 @@ This repository defines generic data structures in Go.
 
 ## Data Structures
 
+Most of the types in this module share common behaviors:
+
+- A `Clear` method that discards all the contents of the container.
+- A `Peek` method that returns an order statistic of the container.
+- An `Each` method that iterates the container in its natural order (usable as a [range function](https://go.dev/blog/range-functions)).
+- An `IsEmpty` method that reports whether the container is empty.
+- A `Len` method that reports the number of elements in the container.
+
+### Packages
+
 - [heapq](./heapq) a heap-structured priority queue ([package docs](https://godoc.org/github.com/creachadair/mds/heapq))
 - [mapset](./mapset) a basic map-based set implementation ([package docs](https://godoc.org/github.com/creachadair/mds/mapset))
 - [mlink](./mlink) basic linked sequences (list, queue) ([package docs](https://godoc.org/github.com/creachadair/mds/mlink))

go.mod

@@ -1,5 +1,5 @@
 module github.com/creachadair/mds
 
-go 1.22
+go 1.23
 
 require github.com/google/go-cmp v0.6.0

heapq/heapq.go

@@ -156,16 +156,14 @@ func (q *Queue[T]) Reorder(cmp func(a, b T) int) {
 	}
 }
 
-// Each calls f for each value in q in heap order. If f returns false, Each
-// stops and returns false. Otherwise, Each returns true after visiting all
-// elements of q.
-func (q *Queue[T]) Each(f func(T) bool) bool {
+// Each is a range function that calls f with each value in q in heap order.
+// If f returns false, Each returns immediately.
+func (q *Queue[T]) Each(f func(T) bool) {
 	for _, v := range q.data {
 		if !f(v) {
-			return false
+			return
 		}
 	}
-	return true
 }
 
 // Clear discards all the entries in q, leaving it empty.

heapq/heapq_test.go

@@ -32,10 +32,9 @@ func runTests(t *testing.T, q *heapq.Queue[int]) {
 	check := func(want ...int) {
 		t.Helper()
 		var got []int
-		q.Each(func(v int) bool {
+		for v := range q.Each {
 			got = append(got, v)
-			return true
-		})
+		}
 		if diff := cmp.Diff(want, got); diff != "" {
 			t.Errorf("Queue contents (+want, -got):\n%s", diff)
 			t.Logf("Got:  %v", got)

internal/mdtest/mdtest.go

@@ -13,14 +13,14 @@ import (
 type Shared[T any] interface {
 	Clear()
 	Peek(int) (T, bool)
-	Each(func(T) bool) bool
+	Each(func(T) bool)
 	IsEmpty() bool
 	Len() int
 }
 
 // Eacher is the subset of Shared provided by iterable elements.
 type Eacher[T any] interface {
-	Each(func(T) bool) bool
+	Each(func(T) bool)
 	Len() int
 }
 
@@ -29,7 +29,9 @@ type Eacher[T any] interface {
 func CheckContents[T any](t *testing.T, s Eacher[T], want []T) {
 	t.Helper()
 	var got []T
-	s.Each(func(v T) bool { got = append(got, v); return true })
+	for v := range s.Each {
+		got = append(got, v)
+	}
 	if diff := cmp.Diff(want, got, cmpopts.EquateEmpty()); diff != "" {
 		t.Errorf("Wrong contents (-got, +want):\n%s", diff)
 	}

mlink/example_test.go

@@ -31,10 +31,9 @@ func ExampleList() {
 	name.Remove()
 
 	// Print out everything in the list.
-	lst.Each(func(s string) bool {
+	for s := range lst.Each {
 		fmt.Print(" ", s)
-		return true
-	})
+	}
 	fmt.Println()
 
 	// Calculate the length of the list.

mlink/list.go

@@ -29,24 +29,23 @@ func (lst *List[T]) Peek(n int) (T, bool) {
 	return cur.Get(), !cur.AtEnd()
 }
 
-// Each calls f with each value in lst, in order from first to last.
-// If f returns false, Each stops and returns false.
-// Otherwise, Each returns true after visiting all elements of lst.
-func (lst *List[T]) Each(f func(T) bool) bool {
+// Each is a range function that calls f with each value in lst in order from
+// first to last.  If f returns false, Each returns immediately.
+func (lst *List[T]) Each(f func(T) bool) {
 	for cur := lst.cfirst(); !cur.AtEnd(); cur.Next() {
 		if !f(cur.Get()) {
-			return false
+			return
 		}
 	}
-	return true
 }
 
 // Len reports the number of elements in lst. This method takes time proportional
 // to the length of the list.
-func (lst *List[T]) Len() int {
-	var n int
-	lst.Each(func(T) bool { n++; return true })
-	return n
+func (lst *List[T]) Len() (n int) {
+	for range lst.Each {
+		n++
+	}
+	return
 }
 
 // At returns a cursor to the element at index n ≥ 0 in the list.  If n is

mlink/mlink.go

@@ -1,13 +1,5 @@
 // Package mlink implements basic linked container data structures.
 //
-// Most types in this package share certain common behaviors:
-//
-//   - A Clear method that discards all the contents of the container.
-//   - A Peek method that returns an order statistic of the container.
-//   - An Each method that iterates the container in its natural order.
-//   - An IsEmpty method that reports whether the container is empty.
-//   - A Len method that reports the number of elements in the container.
-//
 // The types defined here are not safe for concurrent use by multiple
 // goroutines without external synchronization.
 package mlink

mlink/queue.go

@@ -56,10 +56,9 @@ func (q *Queue[T]) Pop() (T, bool) {
 	return out, true
 }
 
-// Each calls f with each value in q, in order from oldest to newest.
-// If f returns false, Each stops and returns false.
-// Otherwise, Each returns true after visiting all elements of q.
-func (q *Queue[T]) Each(f func(T) bool) bool { return q.list.Each(f) }
+// Each is a range function that calls f with each value in q, in order from
+// oldest to newest.  If f returns false, Each returns immediately.
+func (q *Queue[T]) Each(f func(T) bool) { q.list.Each(f) }
 
 // Len reports the number of elements in q. This is a constant-time operation.
 func (q *Queue[T]) Len() int { return q.size }

queue/queue.go

@@ -148,18 +148,16 @@ func (q *Queue[T]) PopLast() (T, bool) {
 	return out, true
 }
 
-// Each calls f with each value in q, in order from oldest to newest.
-// If f returns false, Each stops and returns false.
-// Otherwise, Each returns true after visiting all elements of q.
-func (q *Queue[T]) Each(f func(T) bool) bool {
+// Each is a range function that calls f with each value, in q, in order from
+// oldest to newest.  If f returns false, Each returns immediately.
+func (q *Queue[T]) Each(f func(T) bool) {
 	cur := q.head
 	for range q.n {
 		if !f(q.vs[cur]) {
-			return false
+			return
 		}
 		cur = (cur + 1) % len(q.vs)
 	}
-	return true
 }
 
 // Slice returns a slice of the values of q in order from oldest to newest.

ring/example_test.go

@@ -19,10 +19,9 @@ func ExampleRing() {
 	s.Prev().Join(r)
 
 	// Iterate over the elements of a ring.
-	r.Each(func(s string) bool {
+	for s := range r.Each {
 		fmt.Println(s)
-		return true
-	})
+	}
 
 	// Output:
 	// fruit

ring/ring.go

@@ -150,11 +150,10 @@ func (r *Ring[T]) Peek(n int) (T, bool) {
 	return cur.Value, true
 }
 
-// Each calls f with each value in r, in circular order. If f returns false,
-// Each stops and returns false.  Otherwise, Each returns true after visiting
-// all elements of r.
-func (r *Ring[T]) Each(f func(v T) bool) bool {
-	return scan(r, func(cur *Ring[T]) bool { return f(cur.Value) })
+// Each is a range function that calls f with each value of r in circular
+// order.  If f returns false, Each returns immediately.
+func (r *Ring[T]) Each(f func(v T) bool) {
+	scan(r, func(cur *Ring[T]) bool { return f(cur.Value) })
 }
 
 // Len reports the number of elements in r. If r == nil, Len is 0.
@@ -171,19 +170,18 @@ func (r *Ring[T]) Len() int {
 // IsEmpty reports whether r is the empty ring.
 func (r *Ring[T]) IsEmpty() bool { return r == nil }
 
-func scan[T any](r *Ring[T], f func(*Ring[T]) bool) bool {
+func scan[T any](r *Ring[T], f func(*Ring[T]) bool) {
 	if r == nil {
-		return true
+		return
 	}
 
 	cur := r
 	for f(cur) {
 		if cur.next == r {
-			return true
+			return
 		}
 		cur = cur.next
 	}
-	return false
 }
 
 func newRing[T any]() *Ring[T] { r := new(Ring[T]); r.next = r; r.prev = r; return r }

stack/stack.go

@@ -56,16 +56,14 @@ func (s *Stack[T]) Pop() (T, bool) {
 	return out, ok
 }
 
-// Each calls f with each value in s, in order from newest to oldest.
-// If f returns false, Each stops and returns false.
-// Otherwise, Each returns true after visiting all elements of s.
-func (s *Stack[T]) Each(f func(T) bool) bool {
+// Each is a range function that calls f with each value in s, in order from
+// newest to oldest.  If f returns false, Each returns immediately.
+func (s *Stack[T]) Each(f func(T) bool) {
 	for i := len(s.list) - 1; i >= 0; i-- {
 		if !f(s.list[i]) {
-			return false
+			return
 		}
 	}
-	return true
 }
 
 // Len reports the number of elements in s. This is a constant-time operation.