Document Map iterators and remove Map from itx

README.md

@@ -524,6 +524,48 @@ for line, err := range it.LinesString(buffer) {
 > As with [bufio.Scanner](https://pkg.go.dev/bufio#Scanner), there is a maximum line length per line
 > of 65536 characters.
 
+### Map & Transform
+
+Map yields values from an iterator that have had the provided function applied to each value.
+Transform serves the same purpose but contrains the return type to the type of the iterator's values
+(see note below).
+
+```go
+double := func(n int) int { return n * 2 }
+
+it.Map(slices.Values([]int{1, 2, 3}), double)
+
+// Map for iter.Seq2
+doubleBoth := func(n, m int) (int, int) { return n * 2, m * 2 }
+
+it.Map2(maps.All(map[int]int{1: 2, 3: 4}), doubleBoth)
+
+// Limited chainable flavour of Map
+itx.FromSlice([]int{0, 1, 2}).Transform(double)
+
+// As above for iter.Seq2
+itx.FromMap(map[int]int{1: 2}).Transform(doubleBoth)
+```
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> The `itx` package does not contain `Map` due to limitations with Go's type system. Instead a
+> limited from of `Map` called `Transform` is provided where the type returned from operations is
+> the same as a type of the iterator's values.
+>
+> A chainable Map will be added should Go's type system ever support new generic type parameters on
+> methods.
+
+<!-- prettier-ignore -->
+> [!TIP]
+
+> If you wish to chain operations on Map, you can do so by first converting it to an itx.Iterator
+> like so:
+>
+> ```go
+> itx.From(it.Map(slices.Values([]int{1, 2, 3}), double)).Collect()
+> ```
+
 ### NaturalNumbers
 
 NaturalNumbers yields all non-negative integers in ascending order.

it/itx/map.go

@@ -2,12 +2,6 @@ package itx
 
 import "github.com/BooleanCat/go-functional/v2/it"
 
-// Map is a convenience method [it.Map] returning an [Iterator] to support
-// chaining.
-func Map[V any, W any](iterator func(func(V) bool), f func(V) W) Iterator[W] {
-	return Iterator[W](it.Map(iterator, f))
-}
-
 // Transform is a convenience method for chaining [it.Map] on [Iterator]s where
 // the provided functions argument type is the same as its return type.
 //

it/itx/map_test.go

@@ -3,18 +3,10 @@ package itx_test
 import (
 	"fmt"
 	"maps"
-	"slices"
 
 	"github.com/BooleanCat/go-functional/v2/it/itx"
 )
 
-func ExampleMap() {
-	fmt.Println(itx.Map(slices.Values([]int{0, 1, 2}), func(v int) int {
-		return v + 1
-	}).Collect())
-	// Output: [1 2 3]
-}
-
 func ExampleIterator_Transform() {
 	fmt.Println(itx.FromSlice([]int{0, 1, 2}).Transform(func(v int) int {
 		return v + 1