Move chaining iterators to itx package

Author: BooleanCat

README.md

@@ -7,14 +7,14 @@ A library of iterators for use with `iter.Seq`. Requires Go 1.23+.
 ```go
 // The first 5 natural numbers
 numbers := slices.Collect(
-	it.Take(it.Count(), 5),
+	it.Take(it.Count[int](), 5),
 )
 
 // All even numbers
-evens := it.Filter(it.Count(), filter.IsEven)
+evens := it.Filter(it.Count[int](), filter.IsEven)
 
 // String representations of integers
-numbers := it.Map(it.Count(), strconv.Itoa)
+numbers := it.Map(it.Count[int](), strconv.Itoa)
 ```
 
 _[Read the docs](https://pkg.go.dev/github.com/BooleanCat/go-functional/v2)_ to see the full iterator library.
@@ -24,3 +24,22 @@ _[Read the docs](https://pkg.go.dev/github.com/BooleanCat/go-functional/v2)_ to
 ```terminal
 go get github.com/BooleanCat/go-functional/v2@latest
 ```
+
+## Iterator Chaining
+
+The iterators in this package were designed to be used with the native
+`iter.Seq` from Go's standard library. In order to facilitate complex
+sequences of iterators, the
+[`itx`](https://github.com/BooleanCat/go-functional/tree/main/it/itx) package
+provides `Iterator` and `Iterator2` as wrappers around `iter.Seq` and
+`iter.Seq2` that allow for chaining operations.
+
+Let's take a look at an example:
+
+```go
+// The first 10 odd integers
+itx.Count[int]().Filter(filter.IsOdd).Take(10).Collect()
+```
+
+Most iterators support chaining. A notable exception is `it.Map` which cannot
+support chaining due to limitations on Go's type system.

it/chain.go

@@ -11,11 +11,6 @@ func Chain[V any](iterators ...iter.Seq[V]) iter.Seq[V] {
 	}
 }
 
-// Chain is a convenience method for chaining [Chain] on [Iterator]s.
-func (iterator Iterator[V]) Chain(iterators ...iter.Seq[V]) Iterator[V] {
-	return Iterator[V](Chain[V](append([]iter.Seq[V]{iter.Seq[V](iterator)}, iterators...)...))
-}
-
 // Chain2 yields values from multiple iterators in sequence.
 func Chain2[V, W any](iterators ...iter.Seq2[V, W]) iter.Seq2[V, W] {
 	return func(yield func(V, W) bool) {
@@ -24,8 +19,3 @@ func Chain2[V, W any](iterators ...iter.Seq2[V, W]) iter.Seq2[V, W] {
 		}
 	}
 }
-
-// Chain is a convenience method for chaining [Chain2] on [Iterator2]s.
-func (iterator Iterator2[V, W]) Chain(iterators ...iter.Seq2[V, W]) Iterator2[V, W] {
-	return Iterator2[V, W](Chain2(append([]iter.Seq2[V, W]{iter.Seq2[V, W](iterator)}, iterators...)...))
-}

it/chain_test.go

@@ -18,13 +18,6 @@ func ExampleChain() {
 	// Output: [1 2 3 4]
 }
 
-func ExampleChain_method() {
-	numbers := it.Iterator[int](slices.Values([]int{1, 2})).Chain(slices.Values([]int{3, 4})).Collect()
-
-	fmt.Println(numbers)
-	// Output: [1 2 3 4]
-}
-
 func TestChainEmpty(t *testing.T) {
 	t.Parallel()
 
@@ -57,13 +50,6 @@ func ExampleChain2() {
 	// Output: 2
 }
 
-func ExampleChain2_method() {
-	pairs := it.Iterator2[string, int](maps.All(map[string]int{"a": 1})).Chain(maps.All(map[string]int{"b": 2}))
-
-	fmt.Println(len(maps.Collect(iter.Seq2[string, int](pairs))))
-	// Output: 2
-}
-
 func TestChain2(t *testing.T) {
 	t.Parallel()
 

it/channel.go

@@ -33,8 +33,3 @@ func ToChannel[V any](seq iter.Seq[V]) <-chan V {
 
 	return channel
 }
-
-// ToChannel is a convenience method for chaining [ToChannel] on [Iterator]s.
-func (iterator Iterator[V]) ToChannel() <-chan V {
-	return ToChannel(iter.Seq[V](iterator))
-}

it/channel_test.go

@@ -66,19 +66,6 @@ func ExampleToChannel() {
 	// 3
 }
 
-func ExampleToChannel_method() {
-	channel := it.Iterator[int](slices.Values([]int{1, 2, 3})).ToChannel()
-
-	for number := range channel {
-		fmt.Println(number)
-	}
-
-	// Output:
-	// 1
-	// 2
-	// 3
-}
-
 func TestToChannelEmpty(t *testing.T) {
 	t.Parallel()
 

it/cycle.go

@@ -29,11 +29,6 @@ func Cycle[V any](delegate iter.Seq[V]) iter.Seq[V] {
 	}
 }
 
-// Cycle is a convenience method for chaining [Cycle] on [Iterator]s.
-func (iterator Iterator[V]) Cycle() Iterator[V] {
-	return Iterator[V](Cycle(iter.Seq[V](iterator)))
-}
-
 // Cycle2 yields pairs of values from an iterator repeatedly.
 //
 // Note: this is an infinite iterator.
@@ -66,8 +61,3 @@ func Cycle2[V, W any](delegate iter.Seq2[V, W]) iter.Seq2[V, W] {
 		}
 	}
 }
-
-// Cycle is a convenience method for chaining [Cycle2] on [Iterator2]s.
-func (iterator Iterator2[V, W]) Cycle() Iterator2[V, W] {
-	return Iterator2[V, W](Cycle2(iter.Seq2[V, W](iterator)))
-}

it/cycle_test.go

@@ -2,7 +2,6 @@ package it_test
 
 import (
 	"fmt"
-	"iter"
 	"maps"
 	"slices"
 	"testing"
@@ -18,13 +17,6 @@ func ExampleCycle() {
 	// Output: [1 2 1 2 1]
 }
 
-func ExampleCycle_method() {
-	numbers := it.Iterator[int](slices.Values([]int{1, 2})).Cycle().Take(5).Collect()
-
-	fmt.Println(numbers)
-	// Output: [1 2 1 2 1]
-}
-
 func TestCycleYieldFalse(t *testing.T) {
 	t.Parallel()
 
@@ -44,13 +36,6 @@ func ExampleCycle2() {
 	// Output: map[1:one]
 }
 
-func ExampleCycle2_method() {
-	numbers := it.Iterator2[int, string](maps.All(map[int]string{1: "one"})).Cycle().Take(5)
-
-	fmt.Println(maps.Collect(iter.Seq2[int, string](numbers)))
-	// Output: map[1:one]
-}
-
 func TestCycle2YieldFalse(t *testing.T) {
 	t.Parallel()
 

it/drop.go

@@ -19,11 +19,6 @@ func Drop[V any](delegate iter.Seq[V], count int) iter.Seq[V] {
 	}
 }
 
-// Drop is a convenience method for chaining [Drop] on [Iterator]s.
-func (iterator Iterator[V]) Drop(count int) Iterator[V] {
-	return Iterator[V](Drop(iter.Seq[V](iterator), count))
-}
-
 // Drop2 yields all pairs of values from a delegate [Iterator2] except the
 // first `count` pairs.
 func Drop2[V, W any](delegate iter.Seq2[V, W], count int) iter.Seq2[V, W] {
@@ -40,8 +35,3 @@ func Drop2[V, W any](delegate iter.Seq2[V, W], count int) iter.Seq2[V, W] {
 		}
 	}
 }
-
-// Drop is a convenience method for chaining [Drop] on [Iterator2]s.
-func (iterator Iterator2[V, W]) Drop(count int) Iterator2[V, W] {
-	return Iterator2[V, W](Drop2(iter.Seq2[V, W](iterator), count))
-}

it/drop_test.go

@@ -2,7 +2,6 @@ package it_test
 
 import (
 	"fmt"
-	"iter"
 	"maps"
 	"slices"
 	"testing"
@@ -22,17 +21,6 @@ func ExampleDrop() {
 	// 5
 }
 
-func ExampleDrop_method() {
-	for value := range it.Iterator[int](slices.Values([]int{1, 2, 3, 4, 5})).Drop(2) {
-		fmt.Println(value)
-	}
-
-	// Output:
-	// 3
-	// 4
-	// 5
-}
-
 func TestDropYieldFalse(t *testing.T) {
 	t.Parallel()
 
@@ -58,13 +46,6 @@ func ExampleDrop2() {
 	// Output: 2
 }
 
-func ExampleDrop2_method() {
-	numbers := it.Iterator2[int, string](maps.All(map[int]string{1: "one", 2: "two", 3: "three"})).Drop(1)
-
-	fmt.Println(len(maps.Collect(iter.Seq2[int, string](numbers))))
-	// Output: 2
-}
-
 func TestDrop2(t *testing.T) {
 	t.Parallel()
 

it/enumerate.go

@@ -17,8 +17,3 @@ func Enumerate[V any](delegate iter.Seq[V]) iter.Seq2[int, V] {
 		}
 	}
 }
-
-// Enumerate is a convenience method for chaining [Enumerate] on [Iterator]s.
-func (iterator Iterator[V]) Enumerate() Iterator2[int, V] {
-	return Iterator2[int, V](Enumerate[V](iter.Seq[V](iterator)))
-}