catena

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Two commands built from one shared prefix. With the builtin append
	// and spare capacity, the second would overwrite the first; here the
	// result never aliases the receiver.
	common := append(make(catena.List[string], 0, 8), "git", "log")
	oneline := common.Append("--oneline")
	graph := common.Append("--graph")
	fmt.Println(oneline, graph)
}

Output:
[git log --oneline] [git log --graph]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Crossing to lazy is explicit, and free — it is a view, not a copy.
	// The search stops at the first match instead of testing every port.
	candidates := catena.List[int]{80, 443, 8080, 8443, 9090}
	port, ok := candidates.AsSeq().Find(func(p int) bool { return p >= 1024 })
	fmt.Println(port, ok)
}

Output:
8080 true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Panics exactly like l[i] — it IS the index expression. Use it when
	// the index is known to be valid.
	stages := catena.List[string]{"build", "test", "deploy"}
	fmt.Println(stages.At(stages.Len() - 1))
}

Output:
deploy

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Start from shared defaults without changing them for everyone else.
	defaults := catena.List[string]{"--color", "--jobs=4"}
	mine := defaults.Clone()
	mine[1] = "--jobs=16"
	fmt.Println(defaults, mine)
}

Output:
[--color --jobs=4] [--color --jobs=16]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Wrapping a handler in middleware: the last one listed has to wrap
	// first so the first one listed ends up outermost. Exists only on
	// List: a right fold needs the whole sequence, which a List already is.
	middleware := catena.List[string]{"logging", "auth", "gzip"}
	chain := middleware.FoldRight("handler", func(name, inner string) string {
		return name + "(" + inner + ")"
	})
	fmt.Println(chain)
}

Output:
logging(auth(gzip(handler)))

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The comma-ok form, for when the index may be out of range: an
	// optional command-line argument with a default.
	args := catena.List[string]{"deploy"}
	command, _ := args.Get(0)
	target, ok := args.Get(1)
	if !ok {
		target = "staging"
	}
	fmt.Println(command, target)
}

Output:
deploy staging

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A List is a slice, so its length is known without consuming
	// anything — unlike Count on a lazy sequence.
	replicas := catena.List[string]{"db-1", "db-2", "db-3"}
	fmt.Println("quorum:", replicas.Len()/2+1)
}

Output:
quorum: 2

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// One page of results. It is the slice expression, aliasing included:
	// the page shares memory with the list it came from.
	results := catena.List[string]{"ada", "grace", "linus", "ken", "dennis"}
	page, size := 1, 2
	fmt.Println(results.Slice(page*size, (page+1)*size))
}

Output:
[linus ken]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Vacuously true on an empty sequence: a pipeline with no checks
	// "passes", so guard for that separately if it matters.
	type check struct {
		Name   string
		Passed bool
	}
	passed := func(c check) bool { return c.Passed }

	ci := catena.Of(check{"lint", true}, check{"unit", true}, check{"e2e", true})
	fmt.Println(ci.All(passed))
	fmt.Println(catena.Empty[check]().All(passed))
}

Output:
true
true

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Stops at the first match, so it terminates even on an endless
	// source. Here the two lines after the error are never read.
	read := 0
	log := catena.Of("INFO boot", "ERROR disk full", "INFO retrying", "INFO ok").
		OnEach(func(string) { read++ })

	failed := log.Any(func(line string) bool { return strings.HasPrefix(line, "ERROR") })
	fmt.Println(failed, read)
}

Output:
true 2

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Loose values on the end, without wrapping them in a sequence first:
	// the flags a wrapper always adds after the user's own arguments.
	userArgs := catena.Of("test", "./...")
	fmt.Println(userArgs.Append("-race", "-count=1").Collect())
}

Output:
[test ./... -race -count=1]

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Each element supplies both the key and the value.
	env := catena.Of("HOME=/home/ada", "SHELL=/bin/zsh", "LANG=en_GB.UTF-8").
		Associate(func(line string) (string, string) {
			name, value, _ := strings.Cut(line, "=")
			return name, value
		})
	fmt.Println(env["SHELL"], env["LANG"])
}

Output:
/bin/zsh en_GB.UTF-8

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Accumulates in float64, so integer latencies give a fractional
	// mean — and reports false on empty rather than dividing by zero.
	type request struct {
		Path string
		Ms   int
	}
	ms := func(r request) int { return r.Ms }
	requests := catena.Of(request{"/home", 120}, request{"/cart", 85}, request{"/search", 310})
	mean, ok := requests.AverageOf(ms)
	_, nonEmpty := catena.Empty[request]().AverageOf(ms)
	fmt.Printf("%.2f %v %v\n", mean, ok, nonEmpty)
}

Output:
171.67 true false

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The same bounded heap at the other end, sorted ascending: the two
	// least-loaded servers to send new work to.
	type server struct {
		Host string
		Load int
	}
	pool := catena.Of(server{"web-1", 71}, server{"web-2", 12}, server{"web-3", 94}, server{"web-4", 35})
	fmt.Println(pool.BottomNBy(2, func(s server) int { return s.Load }))
}

Output:
[{web-2 12} {web-4 35}]

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The hand-off back to ordinary Go: a plain slice. Nothing matching
	// gives nil, as slices.Collect does, so len and range need no guard.
	addrs := catena.Of("web-1:443", "db-1:5432", "cache-1:6379")
	onPort := func(port string) func(string) bool {
		return func(addr string) bool { return strings.HasSuffix(addr, port) }
	}
	tls := addrs.Filter(onPort(":443")).Collect()
	plain := addrs.Filter(onPort(":80")).Collect()
	fmt.Println(tls, plain == nil)
}

Output:
[web-1:443] true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// One sequence after another, any number of them: resolvers in the
	// order they should be tried. No sequence is read until the one before
	// it is exhausted.
	primary := catena.Of("10.0.0.2", "10.0.0.3")
	office := catena.Of("192.168.1.1")
	public := catena.Of("1.1.1.1", "8.8.8.8")
	fmt.Println(primary.Concat(office, public).Collect())
}

Output:
[10.0.0.2 10.0.0.3 192.168.1.1 1.1.1.1 8.8.8.8]

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Counts by consuming: nothing is collected along the way.
	body := "the quick brown fox jumps over the lazy dog"
	fmt.Println(catena.FromSlice(strings.Fields(body)).Count())
}

Output:
9

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Fused filter and count: one stage rather than two.
	statuses := catena.Of(200, 503, 200, 404, 500, 200)
	fmt.Println(statuses.CountWhere(func(code int) bool { return code >= 500 }))
}

Output:
2

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Turns a stream of health checks into a stream of state changes.
	// Only CONSECUTIVE repeats collapse, in O(1) memory, so the second
	// "up" is kept — and it is safe on an unbounded source, where
	// DistinctBy's seen-set would grow forever.
	type check struct {
		At, Status string
	}
	checks := catena.Of(
		check{"09:00", "up"}, check{"09:01", "up"},
		check{"09:02", "down"}, check{"09:03", "down"},
		check{"09:04", "up"},
	)

	fmt.Println(checks.
		DedupeBy(func(c check) string { return c.Status }).
		Collect())
}

Output:
[{09:00 up} {09:02 down} {09:04 up}]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Page the on-call engineer once per host, not once per alert. The
	// first alert seen for a host is the one that survives.
	type alert struct {
		Host, Problem string
	}
	alerts := catena.Of(
		alert{"db-1", "disk 91% full"},
		alert{"web-3", "5xx rate high"},
		alert{"db-1", "replication lag"},
	)

	fmt.Println(alerts.
		DistinctBy(func(a alert) string { return a.Host }).
		Collect())
}

Output:
[{db-1 disk 91% full} {web-3 5xx rate high}]

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// For an equality of your own — here, signups that differ only in
	// letter case are the same person — or for keys that are not
	// comparable. Retains every distinct element and compares against
	// all of them, so this is for small inputs.
	signups := catena.Of(
		"Ada@example.com", "bob@example.com", "ada@example.com", "ADA@EXAMPLE.COM",
	)

	fmt.Println(signups.DistinctWith(strings.EqualFold).Collect())
}

Output:
[Ada@example.com bob@example.com]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Runs a pipeline whose stages do the work, discarding the elements:
	// here, warming a cache.
	type user struct {
		ID   int
		Name string
	}
	cache := map[int]string{}
	catena.Of(user{7, "ada"}, user{9, "bob"}).
		OnEach(func(u user) { cache[u.ID] = u.Name }).
		Drain()
	fmt.Println(len(cache), cache[9])
}

Output:
2 bob

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Pagination: skip the pages already shown, then take one page.
	results := catena.Of("ada", "bob", "cyd", "dee", "eve", "fay", "gus")
	page, size := 1, 3

	fmt.Println(results.Drop(page * size).Take(size).Collect())
}

Output:
[dee eve fay]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Strips a totals row off the end of an export without knowing how
	// long the export is. It runs n elements behind the source, and
	// buffers only those.
	export := catena.Of("ada,36.00", "bob,41.50", "eve,12.25", "TOTAL,89.75")

	fmt.Println(export.DropLast(1).Collect())
}

Output:
[ada,36.00 bob,41.50 eve,12.25]

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Skips the comment banner at the top of a config file. Only the
	// leading run is dropped; once the predicate fails, everything after
	// is kept — including the later comment.
	config := catena.Of(
		"# managed by ops",
		"# do not edit",
		"port = 8080",
		"# seconds",
		"timeout = 30",
	)

	fmt.Println(config.
		DropWhile(func(line string) bool { return strings.HasPrefix(line, "#") }).
		JoinToString("; ", catena.Self[string]))
}

Output:
port = 8080; # seconds; timeout = 30

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The element reported is the one that repeats the key: here, the
	// second signup with each address, which is the one to reject.
	type signup struct {
		Email string
		Name  string
	}
	signups := catena.Of(
		signup{"ada@example.com", "Ada"},
		signup{"bob@example.com", "Bob"},
		signup{"ada@example.com", "Ada L."},
	)
	fmt.Println(signups.DuplicatesBy(func(s signup) string { return s.Email }).Collect())
}

Output:
[{ada@example.com Ada L.}]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Zero-based. An index out of range, or negative, reports false
	// rather than panicking — there is no counting from the end.
	leaderboard := catena.Of("mira", "tom", "ada")
	runnerUp, ok := leaderboard.ElementAt(1)
	_, fromEnd := leaderboard.ElementAt(-1)
	fmt.Println(runnerUp, ok, fromEnd)
}

Output:
tom true false

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The unpaid orders worth a reminder email. Nothing is tested until
	// Collect asks for the result.
	type order struct {
		ID    string
		Total float64
		Paid  bool
	}
	orders := catena.Of(
		order{"A-1001", 42.50, true},
		order{"A-1002", 310.00, false},
		order{"A-1003", 18.99, false},
		order{"A-1004", 129.00, false},
	)

	fmt.Println(orders.
		Filter(func(o order) bool { return !o.Paid && o.Total >= 100 }).
		Map(func(o order) string { return o.ID }).
		Collect())
}

Output:
[A-1002 A-1004]

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A predicate that can fail produces a Try, so the caller chooses
	// what a failure means rather than the pipeline deciding. Here a bad
	// config entry is reported alongside the ports that did parse.
	configured := catena.Of("8080", "443", "http", "22")
	privileged := configured.FilterErr(func(s string) (bool, error) {
		port, err := strconv.Atoi(s)
		return port < 1024, err
	})

	kept, errs := privileged.CollectAll()
	fmt.Println(kept, errs)
}

Output:
[443 22] [strconv.Atoi: parsing "http": invalid syntax]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The index is the line's position in the source, not among the
	// survivors: line 0 is the header however many blank lines the
	// predicate has dropped along the way.
	export := catena.Of("host,port", "", "db-1,5432", "", "cache-1,6379")

	fmt.Println(export.
		FilterIndexed(func(i int, line string) bool { return i > 0 && line != "" }).
		Collect())
}

Output:
[db-1,5432 cache-1,6379]

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Fused filter and map: keep the error lines and strip their prefix in
	// one stage. Anything returning (value, bool) fits, and the test is
	// not run a second time to get the value.
	logs := catena.Of(
		"INFO listening on :8080",
		"ERROR db: connection refused",
		"INFO GET /health 200",
		"ERROR cache: timeout",
	)
	for msg := range logs.FilterMap(func(line string) (string, bool) {
		return strings.CutPrefix(line, "ERROR ")
	}).Seq() {
		fmt.Println(msg)
	}
}

Output:
db: connection refused
cache: timeout

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The negated form, for when the predicate reads better positively:
	// "is a probe" is the natural question, and the traffic report wants
	// everything that is not one.
	isProbe := func(path string) bool {
		return path == "/healthz" || path == "/metrics"
	}
	paths := catena.Of("/checkout", "/healthz", "/cart", "/metrics", "/login")

	fmt.Println(paths.FilterNot(isProbe).Collect())
}

Output:
[/checkout /cart /login]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The first request that broke the 500ms budget; nothing after it is
	// examined.
	type request struct {
		Path string
		Ms   int
	}
	requests := catena.Of(request{"/home", 80}, request{"/search", 740}, request{"/export", 2100})
	slow, ok := requests.Find(func(r request) bool { return r.Ms > 500 })
	fmt.Println(slow.Path, ok)
}

Output:
/search true

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Where the first match is, counted from zero; -1 when there is none.
	log := catena.Of("INFO boot", "INFO listening on :8080", "ERROR disk full")
	hasLevel := func(level string) func(string) bool {
		return func(line string) bool { return strings.HasPrefix(line, level) }
	}
	fmt.Println(log.FindIndex(hasLevel("ERROR")))
	fmt.Println(log.FindIndex(hasLevel("FATAL")))
}

Output:
2
-1

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The most recent release that passed — the one to roll back to.
	type deploy struct {
		Version string
		Healthy bool
	}
	history := catena.Of(deploy{"v41", true}, deploy{"v42", true}, deploy{"v43", false})
	good, ok := history.FindLast(func(d deploy) bool { return d.Healthy })
	fmt.Println(good.Version, ok)
}

Output:
v42 true

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Fused find and map: the parsed value is returned, not the header
	// line it came from, and the lines after it are never parsed.
	headers := catena.Of("Host: example.com", "Content-Length: 348", "Accept: */*")
	length, ok := headers.FindMap(func(h string) (int, bool) {
		value, found := strings.CutPrefix(h, "Content-Length: ")
		if !found {
			return 0, false
		}
		n, err := strconv.Atoi(value)
		return n, err == nil
	})
	fmt.Println(length, ok)
}

Output:
348 true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The bool tells an empty sequence apart from a first element that
	// happens to be the zero value.
	queue := catena.Of("deploy api", "rotate keys")
	job, ok := queue.First()
	_, idle := catena.Empty[string]().First()
	fmt.Println(job, ok, idle)
}

Output:
deploy api true false

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// First, for use inside an expression: no second result to check.
	ports := catena.Of(8080, 8081)
	var none catena.Seq[int]
	fmt.Println(ports.FirstOr(80), none.FirstOr(80))
}

Output:
8080 80

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Each element expands into a sequence of its own and the results run
	// together in order. The inner sequences stay lazy: no port list is
	// built for a rule until the consumer reaches it.
	type rule struct {
		Service  string
		From, To int
	}
	rules := catena.Of(rule{"web", 8080, 8082}, rule{"metrics", 9100, 9101})
	fmt.Println(rules.
		FlatMap(func(r rule) catena.Seq[int] { return catena.Range(r.From, r.To+1, 1) }).
		Collect())
}

Output:
[8080 8081 8082 9100 9101]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The same, when each element already holds a slice: every file touched
	// by a run of commits, with no wrapping of the slice in a sequence.
	type commit struct {
		Hash  string
		Files []string
	}
	commits := catena.Of(
		commit{"a1f9", []string{"go.mod", "main.go"}},
		commit{"c03d", []string{"README.md"}},
	)
	fmt.Println(commits.FlatMapSlice(func(c commit) []string { return c.Files }).Collect())
}

Output:
[go.mod main.go README.md]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The seed is where the result starts: an opening balance of 100,
	// then the day's deposits and withdrawals.
	ledger := catena.Of(250, -75, -20)
	balance := ledger.Fold(100, func(balance, amount int) int { return balance + amount })
	fmt.Println(balance)
}

Output:
255

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Streaming aggregation per key. GroupBy would retain every sale;
	// this retains one running total per region.
	type sale struct {
		Region string
		Amount int
	}
	sales := catena.Of(
		sale{"west", 100}, sale{"east", 40}, sale{"west", 20},
	)
	totals := sales.FoldBy(
		func(s sale) string { return s.Region },
		func(string) int { return 0 },
		func(sum int, s sale) int { return sum + s.Amount },
	)
	fmt.Println(totals["west"], totals["east"])
}

Output:
120 40

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Stops at the first error and returns the accumulator so far: the
	// total of the rows that did parse, and why the next one did not.
	amounts := catena.Of("12", "30", "n/a", "7")
	total, err := amounts.FoldErr(0, func(sum int, field string) (int, error) {
		n, err := strconv.Atoi(field)
		if err != nil {
			return 0, err
		}
		return sum + n, nil
	})
	fmt.Println(total, err)
}

Output:
42 strconv.Atoi: parsing "n/a": invalid syntax

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The fold knows where it is: gather the line number of every
	// failing package.
	results := catena.Of("ok   pkg/api", "FAIL pkg/db", "ok   pkg/web", "FAIL pkg/auth")
	failedAt := results.FoldIndexed([]int(nil), func(i int, lines []int, line string) []int {
		if strings.HasPrefix(line, "FAIL") {
			return append(lines, i+1)
		}
		return lines
	})
	fmt.Println(failedAt)
}

Output:
[2 4]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Stops when the callback says so; the accumulator from the stopping
	// call is included. The file that tips the batch past 10 MB is
	// counted, and the one after it is never looked at.
	fileMB := catena.Of(4, 3, 5, 2)
	batchMB := fileMB.FoldWhile(0, func(total, size int) (int, bool) {
		total += size
		return total, total < 10
	})
	fmt.Println(batchMB)
}

Output:
12

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// FoldBy that stays in the chain: keys come out in the order they
	// were first seen, so the result is deterministic and keeps flowing.
	type hit struct {
		Path  string
		Bytes int
	}
	hits := catena.Of(hit{"/checkout", 900}, hit{"/home", 2400}, hit{"/health", 2}, hit{"/checkout", 1100})
	hits.
		FoldedBy(
			func(h hit) string { return h.Path },
			func(string) int { return 0 },
			func(sum int, h hit) int { return sum + h.Bytes },
		).
		Filter(func(_ string, bytes int) bool { return bytes >= 1000 }).
		ForEach(func(path string, bytes int) { fmt.Println(path, bytes) })
}

Output:
/checkout 2000
/home 2400

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The end of a pipeline whose point is the side effect.
	results := catena.Of("ok pkg/api", "FAIL pkg/db", "ok pkg/web", "FAIL pkg/auth")
	results.
		Filter(func(line string) bool { return strings.HasPrefix(line, "FAIL") }).
		ForEach(func(line string) { fmt.Println(line) })
}

Output:
FAIL pkg/db
FAIL pkg/auth

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Stops at the first error the callback returns, and returns it:
	// the order after the failure is never attempted.
	type order struct{ ID, Card string }
	orders := catena.Of(order{"A-1", "visa"}, order{"A-2", ""}, order{"A-3", "amex"})

	err := orders.ForEachErr(func(o order) error {
		if o.Card == "" {
			return fmt.Errorf("order %s: no card on file", o.ID)
		}
		fmt.Println("charged", o.ID)
		return nil
	})
	fmt.Println("err:", err)
}

Output:
charged A-1
err: order A-2: no card on file

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The position comes with the element, counted from zero.
	steps := catena.Of("back up the database", "run migrations", "restart the API")
	steps.ForEachIndexed(func(i int, step string) {
		fmt.Printf("%d. %s\n", i+1, step)
	})
}

Output:
1. back up the database
2. run migrations
3. restart the API

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Retains every element. For an aggregate, FoldBy is bounded by keys.
	type order struct {
		Customer string
		ID       int
	}
	orders := catena.Of(order{"acme", 1001}, order{"globex", 1002}, order{"acme", 1003})
	byCustomer := orders.GroupBy(func(o order) string { return o.Customer })
	fmt.Println(len(byCustomer["acme"]), byCustomer["globex"])
}

Output:
2 [{globex 1002}]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// One row per customer with all of their orders together — where
	// JoinBy would repeat ada once per order and drop bob, who has none.
	type order struct {
		Customer int
		Amount   int
	}
	type customer struct {
		ID   int
		Name string
	}
	customers := catena.Of(customer{1, "ada"}, customer{2, "bob"})
	orders := catena.Of(order{1, 30}, order{1, 12}, order{9, 99})

	fmt.Println(customers.GroupJoinBy(orders,
		func(c customer) int { return c.ID },
		func(o order) int { return o.Customer },
		func(c customer, os []order) string { return fmt.Sprintf("%s:%d", c.Name, len(os)) },
	).Collect())
}

Output:
[ada:2 bob:0]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A fallback for the whole sequence, not per element: the default
	// applies only when nothing at all was configured.
	configured := catena.Of("eu-1.example.com", "eu-2.example.com")
	unset := catena.Empty[string]()
	fmt.Println(configured.IfEmpty("localhost").Collect())
	fmt.Println(unset.IfEmpty("localhost").Collect())
}

Output:
[eu-1.example.com eu-2.example.com]
[localhost]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A lookup table; on a duplicate key the last element wins — which
	// is what defaults followed by overrides want.
	type setting struct{ Key, Value string }
	config := catena.Of(
		setting{"port", "8080"}, setting{"log", "info"}, // defaults
		setting{"port", "9090"}, // override
	).IndexBy(func(s setting) string { return s.Key })
	fmt.Println(config["port"].Value, config["log"].Value)
}

Output:
9090 info

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A separator between elements but not before the first or after the
	// last — the fence-post problem, handled once.
	menu := catena.Of("Open", "Save", "Quit")
	for line := range menu.Intersperse("----").Seq() {
		fmt.Println(line)
	}
}

Output:
Open
----
Save
----
Quit

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Answers by consuming one element — on a single-pass source that
	// element is gone.
	statuses := catena.Of(200, 204, 301)
	serverErrors := statuses.Filter(func(code int) bool { return code >= 500 })
	fmt.Println(serverErrors.IsEmpty(), statuses.IsEmpty())
}

Output:
true false

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Checks an ordering by one field without sorting anything: is the
	// changelog oldest-first? ISO dates compare correctly as strings.
	type release struct {
		Tag  string
		Date string
	}
	changelog := catena.Of(
		release{"v1.0.0", "2025-11-03"},
		release{"v1.1.0", "2026-01-19"},
		release{"v1.0.1", "2026-01-12"},
	)
	fmt.Println(changelog.IsSortedBy(func(r release) string { return r.Date }))
}

Output:
false

package main

import (
	"cmp"
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Any ordering a comparator can express: here, highest score first.
	// A tie is still in order.
	type player struct {
		Name  string
		Score int
	}
	board := catena.Of(player{"ada", 90}, player{"bob", 85}, player{"eve", 85}, player{"dan", 70})
	fmt.Println(board.IsSortedWith(func(a, b player) int { return cmp.Compare(b.Score, a.Score) }))
}

Output:
true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A relational inner join. Rows without a match are dropped on both
	// sides — the order for unknown customer 9, and eve, who ordered
	// nothing — and a key that matches twice produces a row each time.
	type order struct {
		Customer int
		Amount   int
	}
	type customer struct {
		ID   int
		Name string
	}
	orders := catena.Of(order{1, 30}, order{2, 10}, order{9, 99}, order{1, 45})
	customers := catena.Of(customer{1, "ada"}, customer{2, "bob"}, customer{3, "eve"})

	fmt.Println(orders.JoinBy(customers,
		func(o order) int { return o.Customer },
		func(c customer) int { return c.ID },
		func(o order, c customer) string { return fmt.Sprintf("%s:%d", c.Name, o.Amount) },
	).Collect())
}

Output:
[ada:30 bob:10 ada:45]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Map and join in one step: the To line of an email.
	type user struct{ Name, Email string }
	team := catena.Of(user{"Ada", "ada@example.com"}, user{"Bob", "bob@example.com"})
	fmt.Println(team.JoinToString(", ", func(u user) string {
		return fmt.Sprintf("%s <%s>", u.Name, u.Email)
	}))
}

Output:
Ada <ada@example.com>, Bob <bob@example.com>

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The most recent of a series of health checks.
	checks := catena.Of(200, 200, 503)
	latest, ok := checks.Last()
	fmt.Println(latest, ok)
}

Output:
503 true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	versions := catena.Of("v1", "v2", "v3")
	fmt.Println(versions.LastOr("v0"), catena.Empty[string]().LastOr("v0"))
}

Output:
v3 v0

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A left outer join: the order with no customer on file is kept, and
	// combine is told so, receiving a zero customer and false.
	type order struct {
		Customer int
		Amount   int
	}
	type customer struct {
		ID   int
		Name string
	}
	orders := catena.Of(order{1, 30}, order{9, 99})
	customers := catena.Of(customer{1, "ada"})

	fmt.Println(orders.LeftJoinBy(customers,
		func(o order) int { return o.Customer },
		func(c customer) int { return c.ID },
		func(o order, c customer, ok bool) string {
			if !ok {
				return fmt.Sprintf("guest:%d", o.Amount)
			}
			return fmt.Sprintf("%s:%d", c.Name, o.Amount)
		},
	).Collect())
}

Output:
[ada:30 guest:99]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The element type changes mid-chain — accounts in, addresses out —
	// which is what generic methods made possible.
	type account struct {
		Name  string
		Email string
	}
	accounts := catena.Of(
		account{"Ada", "ada@example.com"},
		account{"Bob", "bob@example.com"},
	)
	fmt.Println(accounts.Map(func(a account) string { return a.Email }).Collect())
}

Output:
[ada@example.com bob@example.com]

package main

import (
	"fmt"
	"time"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A mapping that can fail produces a Try, so one bad timeout in a
	// config does not have to abort the rest. A failed call yields the zero
	// value alongside its error, never a half-built one.
	timeouts := catena.Of("30s", "soon", "5m")
	parsed, errs := timeouts.MapErr(time.ParseDuration).CollectAll()
	fmt.Println(parsed, len(errs))
}

Output:
[30s 5m0s] 1

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The position arrives with the element, so numbering needs no counter
	// kept outside the chain. It counts from 0; a ranking wants i+1.
	finishers := catena.Of("kiptum", "bekele", "farah")
	fmt.Println(finishers.
		MapIndexed(func(i int, name string) string { return fmt.Sprintf("%d. %s", i+1, name) }).
		Collect())
}

Output:
[1. kiptum 2. bekele 3. farah]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Returns the ELEMENT with the largest key; ties go to the first.
	type endpoint struct {
		Path  string
		P99ms int
	}
	endpoints := catena.Of(endpoint{"/home", 120}, endpoint{"/search", 840}, endpoint{"/export", 840})
	slowest, _ := endpoints.MaxBy(func(e endpoint) int { return e.P99ms })
	fmt.Println(slowest.Path)
}

Output:
/search

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Returns the KEY, where MaxBy returns the element — the -By/-Of
	// distinction, which holds across the whole library.
	type file struct {
		Name  string
		Bytes int64
	}
	files := catena.Of(file{"app.log", 52_000}, file{"core.dump", 9_800_000}, file{"go.mod", 310})
	largest, _ := files.MaxOf(func(f file) int64 { return f.Bytes })
	fmt.Println(largest)
}

Output:
9800000

package main

import (
	"cmp"
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A comparator, for orderings no single key expresses: major first,
	// then minor.
	type version struct{ Major, Minor int }
	tags := catena.Of(version{1, 12}, version{2, 3}, version{2, 0})
	latest, _ := tags.MaxWith(func(a, b version) int {
		return cmp.Or(cmp.Compare(a.Major, b.Major), cmp.Compare(a.Minor, b.Minor))
	})
	fmt.Println(latest)
}

Output:
{2 3}

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The whole quote comes back, not just its price.
	type quote struct {
		Carrier string
		Cents   int
	}
	quotes := catena.Of(quote{"dhl", 1250}, quote{"ups", 990}, quote{"fedex", 1400})
	cheapest, _ := quotes.MinBy(func(q quote) int { return q.Cents })
	fmt.Println(cheapest.Carrier)
}

Output:
ups

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Both ends in a single pass.
	type reading struct {
		Sensor string
		TempC  float64
	}
	readings := catena.Of(reading{"attic", 31.5}, reading{"cellar", 12.0}, reading{"hall", 20.5})
	coldest, warmest, ok := readings.MinMaxOf(func(r reading) float64 { return r.TempC })
	fmt.Println(coldest, warmest, ok)
}

Output:
12 31.5 true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The lowest stock level, whichever product it belongs to.
	type product struct {
		SKU     string
		InStock int
	}
	shelf := catena.Of(product{"mug", 14}, product{"tee", 3}, product{"cap", 27})
	lowest, _ := shelf.MinOf(func(p product) int { return p.InStock })
	fmt.Println(lowest)
}

Output:
3

package main

import (
	"cmp"
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// What to work on next: the most urgent ticket, and among equally
	// urgent ones the oldest.
	type ticket struct {
		ID       string
		Priority int // 1 is most urgent
		AgeDays  int
	}
	backlog := catena.Of(ticket{"T-7", 2, 30}, ticket{"T-8", 1, 2}, ticket{"T-9", 1, 6})
	next, _ := backlog.MinWith(func(a, b ticket) int {
		return cmp.Or(cmp.Compare(a.Priority, b.Priority), cmp.Compare(b.AgeDays, a.AgeDays))
	})
	fmt.Println(next.ID)
}

Output:
T-9

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// "Did anything go wrong?" asked the other way round; like Any, it
	// stops at the first match.
	statuses := catena.Of(200, 204, 301, 404)
	fmt.Println(statuses.None(func(code int) bool { return code >= 500 }))
}

Output:
true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Side effects without changing the stream — logging, metrics,
	// progress. Elements pass through untouched, and nothing is logged
	// until the terminal operation pulls them.
	type upload struct {
		Name  string
		Bytes int
	}
	uploads := catena.Of(upload{"report.pdf", 48_200}, upload{"logo.png", 9_100})
	total := uploads.
		OnEach(func(u upload) { fmt.Println("uploading", u.Name) }).
		SumOf(func(u upload) int { return u.Bytes })
	fmt.Println(total, "bytes")
}

Output:
uploading report.pdf
uploading logo.png
57300 bytes

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A development guard for sources that can only be read once — a
	// request body, a database cursor: the second consumption panics
	// instead of silently re-running the producer or reading nothing.
	body := catena.Of("id,total", "1,40", "2,15").Once()
	fmt.Println(body.Count(), "lines")

	defer func() { fmt.Println("recovered:", recover()) }()
	body.Collect()
}

Output:
3 lines
recovered: catena: Once: sequence consumed more than once

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Both sides in one pass, each in encounter order.
	signups := catena.Of("ada@example.com", "bob", "eve@example.org", "n/a")
	valid, rejected := signups.Partition(func(email string) bool {
		return strings.Contains(email, "@")
	})
	fmt.Println(valid, rejected)
}

Output:
[ada@example.com eve@example.org] [bob n/a]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Loose values on the front: a header row ahead of the data, without
	// building a second sequence just to hold it.
	rows := catena.Of("report.pdf,48200", "logo.png,9100")
	for line := range rows.Prepend("name,bytes").Seq() {
		fmt.Println(line)
	}
}

Output:
name,bytes
report.pdf,48200
logo.png,9100

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A request that needs every dependency is up only as often as all
	// of them are. The empty product is 1, the multiplicative identity:
	// nothing to depend on, nothing to fail.
	type dependency struct {
		Name   string
		Uptime float64
	}
	uptime := func(d dependency) float64 { return d.Uptime }
	deps := catena.Of(dependency{"db", 0.999}, dependency{"cache", 0.995}, dependency{"auth", 0.99})
	fmt.Printf("%.3f\n", deps.ProductOf(uptime))
	fmt.Printf("%.3f\n", catena.Empty[dependency]().ProductOf(uptime))
}

Output:
0.984
1.000

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Inverts control for hand-written loops, such as reading a header
	// row before the records. THE CALLER MUST CALL stop, or a producer
	// holding a resource never releases it.
	rows := catena.Of("id,email", "1,ada@example.com", "2,bob@example.com")
	next, stop := rows.Pull()
	defer stop()

	header, _ := next()
	record, ok := next()
	fmt.Println(header, "|", record, ok)
}

Output:
id,email | 1,ada@example.com true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Uses the first element as the seed, so it suits values with no
	// natural zero — and reports false on empty rather than inventing one.
	type window struct{ From, To int }
	merge := func(a, b window) window {
		return window{min(a.From, b.From), max(a.To, b.To)}
	}
	outages := catena.Of(window{13, 14}, window{9, 11}, window{16, 17})

	span, ok := outages.Reduce(merge)
	_, nonEmpty := catena.Empty[window]().Reduce(merge)
	fmt.Println(span, ok, nonEmpty)
}

Output:
{9 17} true false

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Last in, first out: migrations are rolled back in the opposite
	// order to the one they were applied in.
	applied := catena.Of("001_users", "002_orders", "003_add_index")
	fmt.Println(applied.Reversed().Collect())
}

Output:
[003_add_index 002_orders 001_users]

package main

import (
	"fmt"
	"math/rand/v2"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Five of a million, each equally likely, holding five in memory.
	// A seeded generator makes the choice repeatable; pass nil for the
	// shared one.
	rng := rand.New(rand.NewPCG(1, 2))
	fmt.Println(len(catena.Range(0, 1_000_000, 1).Sample(5, rng)))

	// A short sequence is returned whole, in order.
	fmt.Println(catena.Of("a", "b").Sample(5, rng))
}

Output:
5
[a b]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A running fold: the balance after every transaction rather than only
	// the final one. The opening balance itself is not emitted, so the
	// output is as long as the input.
	opening := 500
	transactions := catena.Of(120, -75, -300, 40)
	fmt.Println(transactions.
		Scan(opening, func(balance, amount int) int { return balance + amount }).
		Collect())
}

Output:
[620 545 245 285]

package main

import (
	"fmt"
	"slices"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A free conversion to the standard iterator type, in both
	// directions — Seq IS iter.Seq underneath — so anything in the
	// standard library that takes an iterator takes a pipeline.
	hosts := catena.Of("web-2", "db-1", "web-1")
	fmt.Println(slices.Sorted(hosts.Seq()))
}

Output:
[db-1 web-1 web-2]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// True only for exactly one element — the check for "there must be
	// one primary". It stops as soon as a second arrives rather than
	// counting the rest.
	type node struct{ Name, Role string }
	isPrimary := func(n node) bool { return n.Role == "primary" }

	healthy := catena.Of(node{"db-1", "primary"}, node{"db-2", "replica"})
	splitBrain := catena.Of(node{"db-1", "primary"}, node{"db-2", "primary"})

	primary, ok := healthy.Filter(isPrimary).Single()
	_, unambiguous := splitBrain.Filter(isPrimary).Single()
	fmt.Println(primary.Name, ok, unambiguous)
}

Output:
db-1 true false

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Stable, and the selector runs exactly once per element rather than
	// once per comparison — so an expensive key is affordable. Stability
	// shows here: tickets of equal priority stay in the order they arrived.
	type ticket struct {
		ID       string
		Priority int
	}
	queue := catena.Of(ticket{"T-1", 2}, ticket{"T-2", 1}, ticket{"T-3", 2}, ticket{"T-4", 1})
	fmt.Println(queue.SortedBy(func(t ticket) int { return t.Priority }).Collect())
}

Output:
[{T-2 1} {T-4 1} {T-1 2} {T-3 2}]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Largest key first: what is filling the disk.
	type file struct {
		Name  string
		Bytes int
	}
	files := catena.Of(file{"app.log", 9_400}, file{"core.dump", 880_000}, file{"cache.db", 61_000})
	fmt.Println(files.SortedByDesc(func(f file) int { return f.Bytes }).Collect())
}

Output:
[{core.dump 880000} {cache.db 61000} {app.log 9400}]

package main

import (
	"cmp"
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A comparator, for orderings a single key cannot express: by region,
	// then busiest first within each region.
	type host struct {
		Region string
		Name   string
		Load   int
	}
	hosts := catena.Of(host{"us", "us-1", 40}, host{"eu", "eu-1", 15}, host{"us", "us-2", 85}, host{"eu", "eu-2", 60})
	fmt.Println(hosts.
		SortedWith(func(a, b host) int {
			return cmp.Or(strings.Compare(a.Region, b.Region), cmp.Compare(b.Load, a.Load))
		}).
		Map(func(h host) string { return h.Name }).
		Collect())
}

Output:
[eu-2 eu-1 us-2 us-1]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Downsampling: one CPU reading in every three is enough for the
	// chart. The first element always survives, then every nth after it.
	cpuPercent := catena.Of(12, 15, 11, 40, 42, 38, 90, 88)

	fmt.Println(cpuPercent.Step(3).Collect())
}

Output:
[12 40 90]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The selector computes what to add, so a basket totals without an
	// intermediate Map.
	type line struct {
		Qty, UnitCents int
	}
	basket := catena.Of(line{2, 1250}, line{1, 400}, line{3, 99})
	fmt.Println(basket.SumOf(func(l line) int { return l.Qty * l.UnitCents }))
}

Output:
3197

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The next three invoice numbers from a counter that never ends.
	// Take consumes exactly what it emits, so it bounds an infinite
	// source.
	invoices := catena.Generate(1041, func(n int) int { return n + 1 }).
		Map(func(n int) string { return fmt.Sprintf("INV-%d", n) })

	fmt.Println(invoices.Take(3).Collect())
}

Output:
[INV-1041 INV-1042 INV-1043]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// tail -n 2: the end of a log. It buffers only n lines, but has to
	// read the source to its end to know which they are.
	log := catena.Of(
		"12:00:01 starting",
		"12:00:02 listening on :8080",
		"12:04:37 upstream timeout",
		"12:04:38 shutting down",
	)

	log.TakeLast(2).ForEach(func(line string) { fmt.Println(line) })
}

Output:
12:04:37 upstream timeout
12:04:38 shutting down

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The build steps that passed before the first failure. It stops at
	// the first element that fails — unlike Filter, which would keep
	// testing the rest and let "package" through.
	type step struct {
		Name   string
		Passed bool
	}
	steps := catena.Of(
		step{"lint", true}, step{"build", true},
		step{"test", false}, step{"package", true},
	)

	fmt.Println(steps.
		TakeWhile(func(s step) bool { return s.Passed }).
		Map(func(s step) string { return s.Name }).
		Collect())
}

Output:
[lint build]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A count per key, with no group ever built: responses by class.
	statuses := catena.Of(200, 503, 201, 404, 500, 200)
	byClass := statuses.TallyBy(func(code int) string { return fmt.Sprintf("%dxx", code/100) })
	fmt.Println(byClass["2xx"], byClass["4xx"], byClass["5xx"])
}

Output:
3 1 2

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Package functions sit inside the chain instead of wrapping it, so
	// the steps read in the order they happen: dedupe the hosts, sort
	// them, roll out two at a time. A function taking more than the
	// sequence goes in a closure.
	hosts := catena.Of("web-2", "web-1", "web-2", "web-3", "web-1")
	fmt.Println(hosts.
		Then(catena.Distinct).
		Then(catena.Sorted).
		Then(func(s catena.Seq[string]) catena.Seq[[]string] { return catena.Chunked(s, 2) }).
		Collect())
}

Output:
[[web-1 web-2] [web-3]]

package main

import (
	"context"
	"fmt"
	"sync"
	"sync/atomic"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The fan-out mechanism: a Seq is not safe to consume from two
	// goroutines, a channel is. Cancelling ctx closes the channel.
	uploads := catena.Of("a.png", "b.png", "c.png", "d.png")
	jobs := uploads.ToChan(context.Background())

	var resized atomic.Int32
	var workers sync.WaitGroup
	for range 2 {
		workers.Go(func() {
			for range jobs {
				resized.Add(1)
			}
		})
	}
	workers.Wait()
	fmt.Println(resized.Load())
}

Output:
4

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The eager twin: a List has the same operations, evaluated at once,
	// so it can be measured, indexed and reused without re-running the
	// pipeline.
	releases := catena.Of("v1.4.0", "v1.4.1", "v1.5.0").ToList()
	fmt.Println(releases.Len(), releases.At(releases.Len()-1))
}

Output:
3 v1.5.0

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A bounded heap of n, not a sort: memory is O(n) rather than O(all),
	// which is the difference between a working pipeline and an OOM on a
	// large scan. Output is sorted descending, ties in encounter order.
	type customer struct {
		Name  string
		Spend int
	}
	customers := catena.Of(
		customer{"acme", 5200}, customer{"initech", 800}, customer{"globex", 9100},
		customer{"hooli", 5200}, customer{"umbrella", 300},
	)
	fmt.Println(customers.TopNBy(3, func(c customer) int { return c.Spend }))
}

Output:
[{globex 9100} {acme 5200} {hooli 5200}]

package main

import (
	"context"
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Cancellation enters at the edge rather than threading a context
	// through every stage: an endless polling loop ends when the context
	// does, and the context's error arrives as the pipeline's error.
	ctx, cancel := context.WithCancel(context.Background())
	polls := catena.Generate(1, func(attempt int) int { return attempt + 1 })

	done, err := polls.UntilDone(ctx).
		OnEach(func(attempt int) {
			if attempt == 3 { // the deadline passes, or the user hits Ctrl-C
				cancel()
			}
		}).
		Collect()
	fmt.Println(done, err)
}

Output:
[1 2 3] context canceled

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The index becomes half of a pair, so it survives later stages: the
	// positions reported are those in the original file, counting from 0,
	// not those in the filtered result.
	lines := catena.Of("package main", "// TODO: add flags", "func main() {", "// TODO: exit code", "}")
	fmt.Println(lines.WithIndex().
		Filter(func(_ int, line string) bool { return strings.Contains(line, "TODO") }).
		Keys().
		Collect())
}

Output:
[1 3]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Pairs elements positionally and stops at the shorter side: a CSV row
	// that is missing its last field yields only the columns it has.
	header := catena.Of("host", "port", "region")
	row := catena.Of("db-1", "5432")
	fmt.Println(header.Zip(row).
		MapTo(func(column, value string) string { return column + "=" + value }).
		Collect())
}

Output:
[host=db-1 port=5432]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Each element paired with its successor — deltas, gaps, transitions.
	// Here, the seconds between heartbeats; the long gap is the outage.
	// Four heartbeats make three gaps.
	heartbeats := catena.Of(0, 30, 61, 245)
	fmt.Println(heartbeats.ZipWithNext().
		MapTo(func(prev, next int) int { return next - prev }).
		Collect())
}

Output:
[30 31 184]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Is every required setting filled in? Stops at the first one that is
	// not.
	settings := map[string]string{"host": "localhost", "port": "8080", "token": ""}
	complete := catena.FromMap(settings).All(func(_, value string) bool { return value != "" })
	fmt.Println(complete)
}

Output:
false

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Is anything out of stock? Stops at the first pair that says yes.
	stock := map[string]int{"mug": 4, "tee": 9, "cap": 0}
	fmt.Println(catena.FromMap(stock).Any(func(_ string, units int) bool { return units == 0 }))
}

Output:
true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// How many SKUs are running low.
	stock := map[string]int{"mug": 4, "tee": 9, "cap": 0}
	low := catena.FromMap(stock).Filter(func(_ string, units int) bool { return units < 5 })
	fmt.Println(low.Count())
}

Output:
2

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Skip a CSV header after numbering the lines, so the data rows keep
	// the line numbers a user would see in their editor.
	rows := catena.Of("sku,qty", "mug,4", "tee,9").WithIndex().Drop(1)
	rows.ForEach(func(i int, row string) { fmt.Printf("line %d: %s\n", i+1, row) })
}

Output:
line 2: mug,4
line 3: tee,9

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The predicate sees both sides of the pair: pick hosts by their
	// measured latency.
	latencies := catena.Of("api-1", "api-2", "db-1").Zip(catena.Of(42, 310, 275))
	slow := latencies.Filter(func(host string, ms int) bool { return ms > 200 })
	fmt.Println(slow.Keys().Collect())
}

Output:
[api-2 db-1]

package main

import (
	"fmt"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Drop the comment lines of a config file while every surviving line
	// keeps its original number, ready for an error message.
	lines := catena.Of("# cache", "ttl=60", "# auth", "realm=prod").WithIndex().
		FilterNot(func(_ int, line string) bool { return strings.HasPrefix(line, "#") })
	lines.ForEach(func(i int, line string) { fmt.Printf("line %d: %s\n", i+1, line) })
}

Output:
line 2: ttl=60
line 4: realm=prod

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The first item that cannot be fulfilled, with the comma-ok form for
	// when there is none. Nothing after it is examined.
	stock := catena.Of("mug", "cap", "tee").Zip(catena.Of(4, 0, 0))
	sku, units, ok := stock.Filter(func(_ string, units int) bool { return units == 0 }).First()
	fmt.Println(sku, units, ok)
}

Output:
cap 0 true

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A cart total: each pair is a quantity and a unit price in cents.
	cart := catena.Of(2, 1, 3).Zip(catena.Of(1200, 2500, 400))
	total := cart.Fold(0, func(sum, qty, cents int) int { return sum + qty*cents })
	fmt.Println(total)
}

Output:
6100

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Both sides arrive as separate arguments — no pair type to unpack.
	env := catena.Of("HOST", "PORT").Zip(catena.Of("localhost", "8080"))
	env.ForEach(func(name, value string) {
		fmt.Printf("%s=%s\n", name, value)
	})
}

Output:
HOST=localhost
PORT=8080

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The settings a config map defines, in a stable order. Keys and
	// Values on the SAME single-pass Seq2 is a double consume; Unzip does
	// both in one pass.
	config := map[string]string{"port": "8080", "host": "localhost", "debug": "true"}
	fmt.Println(catena.FromMap(config).Keys().Then(catena.Sorted).Collect())
}

Output:
[debug host port]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Both sides can change, types included: a ranked list becomes a
	// name-to-place lookup.
	finishers := catena.Of("ada", "grace", "linus").WithIndex()
	places := finishers.Map(func(i int, name string) (string, int) { return name, i + 1 })
	fmt.Println(catena.CollectMap(places))
}

Output:
map[ada:1 grace:2 linus:3]

package main

import (
	"fmt"
	"net"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The intended exit: collapse each pair into one value and continue
	// in Seq, where the full API lives.
	hosts := catena.Of("api.internal", "db.internal")
	addrs := hosts.Zip(catena.Of("443", "5432")).MapTo(net.JoinHostPort)
	fmt.Println(addrs.Collect())
}

Output:
[api.internal:443 db.internal:5432]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Keys stay put and values are rewritten. The callback receives the
	// key as well, so the new value can depend on it — here, which items
	// are on sale.
	onSale := map[string]bool{"mug": true}
	prices := catena.Of("mug", "tee").Zip(catena.Of(1200, 2500)).
		MapValues(func(sku string, cents int) int {
			if onSale[sku] {
				return cents / 2
			}
			return cents
		})
	fmt.Println(catena.CollectMap(prices))
}

Output:
map[mug:600 tee:2500]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// When the consumer has to drive: take one pair now and the rest
	// later. Ownership transfers to you: always call stop.
	fields := catena.Of("id", "email").Zip(catena.Of("42", "ada@example.com"))
	next, stop := fields.Pull()
	defer stop()
	column, value, ok := next()
	fmt.Println(column, value, ok)
}

Output:
id 42 true

package main

import (
	"fmt"
	"maps"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The standard iterator type, for the stdlib functions that take one —
	// here maps.Insert, layering overrides onto defaults.
	config := map[string]string{"host": "localhost", "port": "8080"}
	overrides := catena.Of("port", "debug").Zip(catena.Of("9090", "true"))
	maps.Insert(config, overrides.Seq2())
	fmt.Println(config)
}

Output:
map[debug:true host:localhost port:9090]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Invert a lookup table: from code-to-name to name-to-code.
	names := map[int]string{200: "OK", 404: "Not Found"}
	codes := catena.CollectMap(catena.FromMap(names).Swap())
	fmt.Println(codes["Not Found"], codes)
}

Output:
404 map[Not Found:404 OK:200]

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The podium: the first three finishers, each still paired with its
	// position.
	finishers := catena.Of("ada", "grace", "linus", "ken", "dennis").WithIndex()
	finishers.Take(3).ForEach(func(i int, name string) {
		fmt.Printf("%d. %s\n", i+1, name)
	})
}

Output:
1. ada
2. grace
3. linus

package main

import (
	"fmt"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Leave the keys behind once only the values matter: total units in
	// stock, whatever the SKU.
	stock := map[string]int{"mug": 4, "tee": 9, "cap": 0}
	fmt.Println(catena.FromMap(stock).Values().Then(catena.Sum))
}

Output:
13

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The all-or-nothing policy: stop at the first bad value. You get the
	// error plus what was gathered before it — enough to say how far it
	// got, and "9090" is never parsed.
	ports, err := catena.Of("8080", "https", "9090").MapErr(strconv.Atoi).Collect()
	fmt.Println(ports)
	fmt.Println(err)
}

Output:
[8080]
strconv.Atoi: parsing "https": invalid syntax

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// The import-report policy: everything that worked and everything that
	// did not, in one pass. The two slices do not correspond positionally.
	orders, errs := importedOrders().CollectAll()
	fmt.Printf("imported %d, rejected %d\n", len(orders), len(errs))
	for _, err := range errs {
		fmt.Println("rejected:", err)
	}
}

Output:
imported 3, rejected 1
rejected: order A-101: bad amount "pending"

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// Count is a terminal, so it stops at the first error: this is how
	// many rows were good before the import broke, not how many are good
	// in total. That would be Ignore().Count().
	n, err := importedOrders().Count()
	fmt.Println(n, err)
	fmt.Println(importedOrders().Ignore().Count())
}

Output:
1 order A-101: bad amount "pending"
3

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Skipping a header row. The header fails to parse like any other bad
	// row, and Drop counts it all the same: it skips elements, errored or
	// not.
	column := catena.Of("qty", "12", "n/a", "7").MapErr(strconv.Atoi)
	quantities, errs := column.Drop(1).CollectAll()
	fmt.Println(quantities, errs)
}

Output:
[12 7] [strconv.Atoi: parsing "n/a": invalid syntax]

package main

import (
	"fmt"
	"net/netip"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A pre-flight check: is every entry in the allowlist a valid address?
	// Only the first error matters, and the parsed values are not needed.
	allowlist := catena.Of("10.0.0.1", "10.0.0.256", "10.0.0.3").MapErr(netip.ParseAddr)
	if err := allowlist.Err(); err != nil {
		fmt.Println("allowlist rejected:", err)
	}
}

Output:
allowlist rejected: ParseAddr("10.0.0.256"): IPv4 field has value >255

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Only what went wrong: a validation pass that lists every bad value
	// and has no use for the good ones. It is the dual of Ignore; wanting
	// both from one single-pass Try is a double consume, so use CollectAll.
	flags := catena.Of("true", "yes", "false", "enabled").MapErr(strconv.ParseBool)
	flags.Errs().ForEach(func(err error) { fmt.Println(err) })
}

Output:
strconv.ParseBool: parsing "yes": invalid syntax
strconv.ParseBool: parsing "enabled": invalid syntax

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// Keep the orders worth reviewing by hand. The predicate is not called
	// on the row that failed, and that row is not filtered out — dropping
	// it would silently discard the failure.
	large := importedOrders().Filter(func(o importedOrder) bool { return o.Cents >= 1000 })
	orders, errs := large.CollectAll()
	fmt.Println(orders)
	fmt.Println(errs)
}

Output:
[{A-100 2500} {A-102 1200}]
[order A-101: bad amount "pending"]

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// A predicate that has to look something up can fail too. A failed
	// lookup takes the element's place as an error instead of being read
	// as "no" and quietly dropping the order.
	paid := map[string]bool{"A-100": true, "A-102": false}
	settled := importedOrders().FilterErr(func(o importedOrder) (bool, error) {
		isPaid, found := paid[o.ID]
		if !found {
			return false, fmt.Errorf("order %s: no payment record", o.ID)
		}
		return isPaid, nil
	})
	orders, errs := settled.CollectAll()
	fmt.Println(orders)
	fmt.Println(errs)
}

Output:
[{A-100 2500}]
[order A-101: bad amount "pending" order A-103: no payment record]

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

func main() {
	// One fallible step fans out into more fallible steps: every upload
	// that opened is parsed value by value. The upload that failed to open
	// passes through as its one error, in order with the inner ones.
	uploads := map[string]string{"mon.csv": "12,7", "wed.csv": "3,n/a"}
	open := func(name string) (string, error) {
		if body, ok := uploads[name]; ok {
			return body, nil
		}
		return "", fmt.Errorf("open %s: no such file", name)
	}
	quantities := catena.Of("mon.csv", "tue.csv", "wed.csv").MapErr(open).
		FlatMap(func(body string) catena.Try[int] {
			return catena.FromSlice(strings.Split(body, ",")).MapErr(strconv.Atoi)
		})
	vals, errs := quantities.CollectAll()
	fmt.Println(vals, len(errs))
}

Output:
[12 7 3] 2

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// A revenue total over rows that may not parse. It stops at the first
	// error and returns the accumulator so far alongside it, so a partial
	// total can never be mistaken for the whole.
	cents, err := importedOrders().Fold(0, func(sum int, o importedOrder) int {
		return sum + o.Cents
	})
	fmt.Println(cents, err)
}

Output:
2500 order A-101: bad amount "pending"

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// Do something fallible with each element — here, save it. Stops at
	// the first failure from either side: a bad element, or the callback
	// returning an error.
	err := importedOrders().ForEach(func(o importedOrder) error {
		fmt.Println("saved", o.ID)
		return nil
	})
	fmt.Println("stopped:", err)
}

Output:
saved A-100
stopped: order A-101: bad amount "pending"

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The log-scan policy: a malformed line is not worth stopping for.
	// Drop the failures and carry on as a plain Seq, with its full API.
	statuses := catena.Of("200", "503", "-", "404", "500").MapErr(strconv.Atoi)
	serverErrors := statuses.Ignore().
		Filter(func(code int) bool { return code >= 500 }).
		Collect()
	fmt.Println(serverErrors)
}

Output:
[503 500]

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// The callback only runs on rows that parsed. The bad row passes
	// through as its error, so a failure is never formatted into something
	// that looks like a valid receipt line.
	receipts := importedOrders().Map(func(o importedOrder) string {
		return fmt.Sprintf("%s $%.2f", o.ID, float64(o.Cents)/100)
	})
	lines, errs := receipts.CollectAll()
	fmt.Println(lines)
	fmt.Println(errs)
}

Output:
[A-100 $25.00 A-102 $12.00 A-103 $8.00]
[order A-101: bad amount "pending"]

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Parse, then validate: two stages that can each fail. Errors from
	// either one flow on side by side, in input order.
	ports := catena.Of("8080", "https", "70000", "9090").MapErr(strconv.Atoi).
		MapErr(func(port int) (int, error) {
			if port > 65535 {
				return 0, fmt.Errorf("port %d out of range", port)
			}
			return port, nil
		})
	valid, errs := ports.CollectAll()
	fmt.Println(valid)
	fmt.Println(errs[0])
	fmt.Println(errs[1])
}

Output:
[8080 9090]
strconv.Atoi: parsing "https": invalid syntax
port 70000 out of range

package main

import (
	"fmt"
	"time"

	"github.com/NerdMeNot/catena"
)

func main() {
	// For input you wrote yourself — a retry schedule compiled into the
	// binary — where a failure is a programming bug. The panic value is
	// the error itself, so recover() can inspect it.
	defer func() { fmt.Println("recovered:", recover()) }()
	backoff := catena.Of("1s", "5s", "30sec").MapErr(time.ParseDuration)
	fmt.Println(backoff.Must().Collect())
}

Output:
recovered: time: unknown unit "sec" in duration "30sec"

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// A tap for the rows that worked — here a running total for the import
	// summary — without ending the pipeline. Failed rows pass by untouched.
	importedCents := 0
	_, errs := importedOrders().
		OnEach(func(o importedOrder) { importedCents += o.Cents }).
		CollectAll()
	fmt.Println(importedCents, len(errs))
}

Output:
4500 1

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// The logging tap, the mirror of OnEach: record each failure as it
	// goes by and still choose afterwards what failures mean. Here they
	// are logged, then skipped.
	orders := importedOrders().
		OnError(func(err error) { fmt.Println("skipped:", err) }).
		Ignore().
		Collect()
	fmt.Println(len(orders), "orders imported")
}

Output:
skipped: order A-101: bad amount "pending"
3 orders imported

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// When the consumer has to drive — one record at a time, between
	// other work. A failed element still arrives with ok true; ok is false
	// only at the end. Ownership transfers to you: always call stop.
	next, stop := importedOrders().Pull()
	defer stop()
	order, err, ok := next()
	fmt.Println(order, err, ok)
	_, err, ok = next()
	fmt.Println(err, ok)
}

Output:
{A-100 2500} <nil> true
order A-101: bad amount "pending" true

package main

import (
	"errors"
	"fmt"
	"time"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Fall back where a sensible default exists and let the rest through:
	// an unset timeout becomes 30s, a malformed one is still an error.
	// Reporting true replaces the element, false lets the error continue.
	errUnset := errors.New("not set")
	parse := func(s string) (time.Duration, error) {
		if s == "" {
			return 0, errUnset
		}
		return time.ParseDuration(s)
	}
	timeouts := catena.Of("5s", "", "fast").MapErr(parse).
		Recover(func(err error) (time.Duration, bool) {
			return 30 * time.Second, errors.Is(err, errUnset)
		})
	vals, errs := timeouts.CollectAll()
	fmt.Println(vals, errs)
}

Output:
[5s 30s] [time: invalid duration "fast"]

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// A free conversion to the standard pair iterator, for a plain range
	// loop that handles each failure its own way.
	ports := catena.Of("8080", "https", "9090").MapErr(strconv.Atoi)
	for port, err := range ports.Seq2() {
		if err != nil {
			fmt.Println("skipping:", err)
			continue
		}
		fmt.Println("listening on", port)
	}
}

Output:
listening on 8080
skipping: strconv.Atoi: parsing "https": invalid syntax
listening on 9090

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// A preview of the first two rows is two rows, bad ones included —
	// Take counts elements, so it never reads past n looking for
	// successes. For "the first two that parsed", Ignore first.
	preview, errs := importedOrders().Take(2).CollectAll()
	firstTwoGood := importedOrders().Ignore().Take(2).Collect()
	fmt.Println(preview, errs)
	fmt.Println(firstTwoGood)
}

Output:
[{A-100 2500}] [order A-101: bad amount "pending"]
[{A-100 2500} {A-102 1200}]

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// Latency samples up to the first slow one. The dropped sample "--"
	// passes through without ending the run; only a successful element
	// failing the predicate stops it.
	samples := catena.Of("12", "15", "--", "18", "950", "14").MapErr(strconv.Atoi)
	fast, errs := samples.TakeWhile(func(ms int) bool { return ms < 100 }).CollectAll()
	fmt.Println(fast, len(errs))
}

Output:
[12 15 18] 1

package main

import (
	"context"
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
	"github.com/NerdMeNot/catena/parallel"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// Then keeps a Try in the chain through a function that takes one —
	// here a concurrent stage, so the orders are confirmed four at a time
	// without first deciding what the import's errors mean. The bad row
	// is never sent to the payment service; it arrives in its place.
	confirm := func(ctx context.Context, o importedOrder) (string, error) {
		return fmt.Sprintf("%s confirmed", o.ID), nil
	}
	confirmed, failed := importedOrders().
		Then(parallel.MapTry(context.Background(), 4, confirm)).
		CollectAll()
	fmt.Println(confirmed)
	fmt.Println(failed)
}

Output:
[A-100 confirmed A-102 confirmed A-103 confirmed]
[order A-101: bad amount "pending"]

package main

import (
	"context"
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// Cancellation enters at the edge. Once ctx is done the sequence
	// yields ctx's error and stops, so a shutdown surfaces like any other
	// failure. Here the request is cancelled while the first order saves.
	ctx, cancel := context.WithCancel(context.Background())
	saved, err := importedOrders().UntilDone(ctx).
		OnEach(func(importedOrder) { cancel() }).
		Collect()
	fmt.Println(len(saved), err)
}

Output:
1 context canceled

package main

import (
	"fmt"
	"strconv"
	"strings"

	"github.com/NerdMeNot/catena"
)

// importedOrder is one row of the order export the Try examples share.
type importedOrder struct {
	ID    string
	Cents int
}

// importedOrders parses a four-row CSV export whose second row has a bad
// amount: three orders that parse and one that fails, so every operator's
// treatment of an error is visible.
func importedOrders() catena.Try[importedOrder] {
	rows := catena.Of("A-100,2500", "A-101,pending", "A-102,1200", "A-103,800")
	return rows.MapErr(func(row string) (importedOrder, error) {
		id, amount, _ := strings.Cut(row, ",")
		cents, err := strconv.Atoi(amount)
		if err != nil {
			return importedOrder{}, fmt.Errorf("order %s: bad amount %q", id, amount)
		}
		return importedOrder{ID: id, Cents: cents}, nil
	})
}

func main() {
	// Stop at the first failure, but as a sequence: the chain goes on
	// with the full Seq API, and the error is checked once it has run —
	// the way bufio.Scanner's Err is read after the loop.
	var err error
	revenue := importedOrders().UntilErr(&err).
		Map(func(o importedOrder) int { return o.Cents }).
		Then(catena.Sum)
	if err != nil {
		fmt.Println("import stopped:", err)
	}
	fmt.Println("revenue so far:", revenue)
}

Output:
import stopped: order A-101: bad amount "pending"
revenue so far: 2500

package main

import (
	"fmt"
	"strconv"

	"github.com/NerdMeNot/catena"
)

func main() {
	// The parser knows what went wrong; only this stage knows where. Add
	// that here. Returning nil keeps the original error rather than
	// turning a failure into a zero value.
	line := 0
	quantities := catena.Of("12", "n/a", "7").
		MapErr(func(field string) (int, error) {
			line++
			return strconv.Atoi(field)
		}).
		WrapErr(func(err error) error {
			return fmt.Errorf("stock.csv line %d: %w", line, err)
		})
	_, err := quantities.Collect()
	fmt.Println(err)
}

Output:
stock.csv line 2: strconv.Atoi: parsing "n/a": invalid syntax