Add TakeWhile iterator

Author: BooleanCat

README.md

@@ -691,7 +691,7 @@ itx.Repeat2(42, "42").Take(5).Collect()
 > otherwise it's likely to result in an infinite while loop. Consider bounding the size of the
 > iterator before consuming (e.g. using [Take](#take)).
 
-### Take
+<h3 id="take">Take & TakeWhile</h3>
 
 Take limits the number of values of an iterator to a specified size. If the iterator has fewer
 values than the provided number then it behaves as though the original iterator is not changed.
@@ -709,6 +709,26 @@ maps.Collect(it.Take2(slices.All([]int{1, 2, 3}), 2))
 itx.FromSlice([]int{1, 2, 3}).Enumerate().Take(2).Collect()
 ```
 
+TakeWhile yields values from the provided iterator whilst the predicate returns true for each value.
+After the first value results in the predicate returning false, the iterator is exhausted.
+
+```go
+lessThanThree := func(number int) { number < 3 }
+
+slices.Collect(it.TakeWhile(slices.Values([]int{1, 2, 3}), lessThanThree))
+
+// Chainable
+itx.FromSlice([]int{1, 2, 3}).TakeWhile(lessThanThree).Collect()
+
+lessThanThreeRight := func(_ string, number int) { return number < 3 }
+
+// Taking from iter.Seq2
+maps.Collect(it.TakeWhile2(maps.All(map[string]int{"one": 1, "four": 4}), lessThanThreeRight))
+
+// As above, but chainable
+itx.FromMap(map[string]int{"one": 1, "four": 4}).TakeWhile(lessThanThreeRight).Collect()
+```
+
 ### Zip, Left & Right
 
 `Zip` yields pairs of values from two iterators. It is exhausted when one of the two provided

it/itx/take.go

@@ -11,3 +11,15 @@ func (iterator Iterator[V]) Take(limit uint) Iterator[V] {
 func (iterator Iterator2[V, W]) Take(limit uint) Iterator2[V, W] {
 	return Iterator2[V, W](it.Take2(iterator, limit))
 }
+
+// TakeWhile is a convenience method for chaining [it.TakeWhile] on
+// [Iterator]s.
+func (iterator Iterator[V]) TakeWhile(predicate func(V) bool) Iterator[V] {
+	return Iterator[V](it.TakeWhile(iterator, predicate))
+}
+
+// TakeWhile is a convenience method for chaining [it.TakeWhile2] on
+// [Iterator2]s.
+func (iterator Iterator2[V, W]) TakeWhile(predicate func(V, W) bool) Iterator2[V, W] {
+	return Iterator2[V, W](it.TakeWhile2(iterator, predicate))
+}

it/itx/take_test.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"maps"
 
+	"github.com/BooleanCat/go-functional/v2/it/filter"
 	"github.com/BooleanCat/go-functional/v2/it/itx"
 )
 
@@ -24,3 +25,22 @@ func ExampleIterator2_Take() {
 	fmt.Println(len(numbers))
 	// Output: 2
 }
+
+func ExampleIterator_TakeWhile() {
+	for number := range itx.FromSlice([]int{1, 2, 3, 4, 5}).TakeWhile(filter.LessThan(4)) {
+		fmt.Println(number)
+	}
+
+	// Output:
+	// 1
+	// 2
+	// 3
+}
+
+func ExampleIterator2_TakeWhile() {
+	lessThanFour := func(int, v int) bool { return v < 4 }
+
+	_, numbers := itx.FromSlice([]int{1, 2, 3, 4, 5}).Enumerate().TakeWhile(lessThanFour).Collect()
+	fmt.Println(numbers)
+	// Output: [1 2 3]
+}

it/take.go

@@ -33,3 +33,35 @@ func Take2[V, W any](delegate func(func(V, W) bool), limit uint) iter.Seq2[V, W]
 		}
 	}
 }
+
+// TakeWhile yields values from a delegate iterator until the predicate returns
+// false.
+func TakeWhile[V any](delegate func(func(V) bool), predicate func(V) bool) iter.Seq[V] {
+	return func(yield func(V) bool) {
+		for value := range delegate {
+			if predicate(value) {
+				if !yield(value) {
+					return
+				}
+			} else {
+				return
+			}
+		}
+	}
+}
+
+// TakeWhile2 yields pairs of values from a delegate iterator until the
+// predicate returns false.
+func TakeWhile2[V, W any](delegate func(func(V, W) bool), predicate func(V, W) bool) iter.Seq2[V, W] {
+	return func(yield func(V, W) bool) {
+		for v, w := range delegate {
+			if predicate(v, w) {
+				if !yield(v, w) {
+					return
+				}
+			} else {
+				return
+			}
+		}
+	}
+}

it/take_test.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/BooleanCat/go-functional/v2/internal/assert"
 	"github.com/BooleanCat/go-functional/v2/it"
+	"github.com/BooleanCat/go-functional/v2/it/filter"
 )
 
 func ExampleTake() {
@@ -102,3 +103,86 @@ func TestTake2YieldFalse(t *testing.T) {
 		return false
 	})
 }
+
+func ExampleTakeWhile() {
+	for number := range it.TakeWhile(slices.Values([]int{1, 2, 3, 4, 5}), filter.LessThan(4)) {
+		fmt.Println(number)
+	}
+
+	// Output:
+	// 1
+	// 2
+	// 3
+}
+
+func TestTakeWhileYieldsFalse(t *testing.T) {
+	t.Parallel()
+
+	seq := it.TakeWhile(slices.Values([]int{1, 2, 3, 4, 5}), filter.LessThan(4))
+
+	seq(func(n int) bool {
+		return false
+	})
+}
+
+func TestTakeWhileEmpty(t *testing.T) {
+	t.Parallel()
+
+	assert.Empty[int](t, slices.Collect(it.TakeWhile(it.Exhausted[int](), filter.Passthrough)))
+}
+
+func TestTakeWhileNeverTake(t *testing.T) {
+	t.Parallel()
+
+	numbers := slices.Collect(it.TakeWhile(slices.Values([]int{1, 2, 3}), func(int) bool { return false }))
+	assert.Empty[int](t, numbers)
+}
+
+func TestTakeWhileTakeAll(t *testing.T) {
+	t.Parallel()
+
+	numbers := slices.Collect(it.TakeWhile(slices.Values([]int{1, 2, 3}), filter.Passthrough))
+	assert.SliceEqual(t, []int{1, 2, 3}, numbers)
+}
+
+func ExampleTakeWhile2() {
+	_, values := it.Collect2(it.TakeWhile2(slices.All([]int{1, 2, 3}), func(i int, v int) bool {
+		return v < 3
+	}))
+
+	fmt.Println(values)
+	// Output: [1 2]
+}
+
+func TestTakeWhile2YieldsFalse(t *testing.T) {
+	t.Parallel()
+
+	seq := it.TakeWhile2(slices.All([]int{1, 2, 3}), func(i int, v int) bool {
+		return v < 3
+	})
+
+	seq(func(i int, v int) bool {
+		return false
+	})
+}
+
+func TestTakeWhile2Empty(t *testing.T) {
+	t.Parallel()
+
+	_, values := it.Collect2(it.TakeWhile2(it.Exhausted2[int, int](), filter.Passthrough2))
+	assert.Empty[int](t, values)
+}
+
+func TestTakeWhile2NeverTake(t *testing.T) {
+	t.Parallel()
+
+	_, values := it.Collect2(it.TakeWhile2(slices.All([]int{1, 2, 3}), func(int, int) bool { return false }))
+	assert.Empty[int](t, values)
+}
+
+func TestTakeWhile2TakeAll(t *testing.T) {
+	t.Parallel()
+
+	_, values := it.Collect2(it.TakeWhile2(slices.All([]int{1, 2, 3}), filter.Passthrough2))
+	assert.SliceEqual(t, []int{1, 2, 3}, values)
+}