iterp

README

iterp

Disclaimer: This package is mostly an experiment and will likely see breaking changes. There are other packages which fulfill the same purpose and I encourage you to use them if you are trying to make reliable software.

A consistent set of packages for processing sequences and generic container types. This library is inspired by samber/lo but aims to provide a simpler, more consistent interface between analogous operations on slices, sequences, and maps.

Documentation

Overview

Package iterp provides basic utilities for processing generic sequences. The supplemental packages iterp/slicep and iterp/mapp provide analogous utilities for slices and maps with consistent APIs.

Seq and Seq2

The iter.Seq and iter.Seq2 types are the primary abstractions in this package. Sequences may be infinite and they may not be replayable. This package should generally provide two implementations of each operations: one that operates on Seq and one that operates on Seq2. The "normal" version of a function operates on Seq values and the "2" variant of a function operates on Seq2 values. For example, Map takes a Seq[T] as input and produces a Seq[U] as output while Map2 takes a Seq2[T,U] as input and produces a Seq2[T,V] as output.

Map2 vs MapSeq2

Map2 returns an iter.Seq2 with the original sequence's "left" values paired with the mapped "right" values. This definition of Map2 makes the function work consistently with the Map2 functions for slices and maps which preserve the indices/keys of the original container.

MapSeq2 in this package provides a more general mapping for iter.Seq2 than is provided by Map2. But, the ability to rewrite the "left" value is not well defined for maps and slices. So while MapSeq2 can be used to create new maps and slices from existing ones, implementing this functionality is left up to individual applications which can apply domain specific knowledge to reason about collisions and/or "gaps" in the output keys/indices and determine appropriate semantics as necessary.

FoldLeft vs FoldRight

The FoldLeft and FoldRight functions aggregate a sequence into an accumulator value. FoldLeft is defined as f(f(f(init, v1), v2), v3)... where v1, v2, v3... are the sequence elements in order. On the other hand,FoldRight is defined as f(v1, f(v2, f(v3,... f(vn, init)))), processing elements in reverse order. Because there is no memory-efficient way to right-fold a generic sequence the FoldRight function is only provided for slices.

Index

• func Chan[T any](c <-chan T) iter.Seq[T]
• func Concat[T any](its ...iter.Seq[T]) iter.Seq[T]
• func Concat2[T any, U any](its ...iter.Seq2[T, U]) iter.Seq2[T, U]
• func DropN[T any](it iter.Seq[T], n int) iter.Seq[T]
• func DropWhile[T any](it iter.Seq[T], p funcs.Select[T]) iter.Seq[T]
• func Empty[T any]() iter.Seq[T]
• func Empty2[T any, U any]() iter.Seq2[T, U]
• func Find[T any](it iter.Seq[T], p funcs.Select[T]) (T, bool)
• func FlatMap[T any, U any](it iter.Seq[T], f funcs.Map[T, iter.Seq[U]]) iter.Seq[U]
• func Flatten[T any](its iter.Seq[iter.Seq[T]]) iter.Seq[T]
• func Flatten2[T any, U any](its iter.Seq[iter.Seq2[T, U]]) iter.Seq2[T, U]
• func FoldLeft[T any, U any](it iter.Seq[T], init U, f funcs.FoldL[T, U]) U
• func Ints[Z constraints.Integer](start Z) iter.Seq[Z]
• func IntsStep[Z constraints.Integer](start Z, step Z) iter.Seq[Z]
• func Left[T any, U any](it iter.Seq2[T, U]) iter.Seq[T]
• func List[T any](values ...T) iter.Seq[T]
• func List2[T any](values ...T) iter.Seq2[int, T]
• func Map[T any, U any](it iter.Seq[T], f funcs.Map[T, U]) iter.Seq[U]
• func Map2[T any, U any, V any](it iter.Seq2[T, U], f funcs.Map2[T, U, V]) iter.Seq2[T, V]
• func MapSeq2[T any, U any, V any, W any](it iter.Seq2[T, U], f func(T, U) (V, W)) iter.Seq2[V, W]
• func Reject[T any](it iter.Seq[T], p funcs.Select[T]) iter.Seq[T]
• func Repeat[T any](it iter.Seq[T], n int) iter.Seq[T]
• func Right[T any, U any](it iter.Seq2[T, U]) iter.Seq[U]
• func Select[T any](it iter.Seq[T], p funcs.Select[T]) iter.Seq[T]
• func Sum[S Summable](it iter.Seq[S]) S
• func TakeN[T any](it iter.Seq[T], n int) iter.Seq[T]
• func TakeWhile[T any](it iter.Seq[T], p funcs.Select[T]) iter.Seq[T]
• func Zip[T any](its ...iter.Seq[T]) iter.Seq[[]T]
• func Zip2[T any, U any](v iter.Seq[T], w iter.Seq[U]) iter.Seq2[T, U]
• type Summable

Functions

func Chan

func Chan[T any](c <-chan T) iter.Seq[T]

Chan wraps c as a sequence so it can be passed to sequence processing functions. Because the channel is stateful the resulting sequence is not replayable.

func Concat

func Concat[T any](its ...iter.Seq[T]) iter.Seq[T]

Concat returns a sequence that concatenates its arguments.

func Concat2

func Concat2[T any, U any](its ...iter.Seq2[T, U]) iter.Seq2[T, U]

Concat2 returns a sequence that concatenates its arguments.

func DropN

func DropN[T any](it iter.Seq[T], n int) iter.Seq[T]

DropN returns the suffix of it without the first n elements. If n is negative, the resulting sequence is it.

func DropWhile

func DropWhile[T any](it iter.Seq[T], p funcs.Select[T]) iter.Seq[T]

DropWhile returns the longest suffix of it for which p is false for the first element.

func Empty

func Empty[T any]() iter.Seq[T]

Empty returns a sequence with no elements.

func Empty2

func Empty2[T any, U any]() iter.Seq2[T, U]

Empty2 returns a empty sequence of pairs.

func Find

func Find[T any](it iter.Seq[T], p funcs.Select[T]) (T, bool)

func FlatMap

func FlatMap[T any, U any](it iter.Seq[T], f funcs.Map[T, iter.Seq[U]]) iter.Seq[U]

FlatMap is a convenience function for Flatten(Map(it, f))

func Flatten

func Flatten[T any](its iter.Seq[iter.Seq[T]]) iter.Seq[T]

Flatten concatenates a sequence of sequences to produce a single sequence.

func Flatten2

func Flatten2[T any, U any](its iter.Seq[iter.Seq2[T, U]]) iter.Seq2[T, U]

Flatten2 concatenates a sequence of sequences of pairs to produce a single sequence of pairs.

func FoldLeft

func FoldLeft[T any, U any](it iter.Seq[T], init U, f funcs.FoldL[T, U]) U

FoldLeft aggregates it into an accumulator initialized to init.

Note that a right fold over a generic sequence is very inefficient and it is not provided here. Slices can be right-folded.

func Ints

func Ints[Z constraints.Integer](start Z) iter.Seq[Z]

Ints returns an infinite sequence of integers from start.

func IntsStep

func IntsStep[Z constraints.Integer](start Z, step Z) iter.Seq[Z]

IntsStep returns an infinite sequence of integers from start and increasing by step.

func Left

func Left[T any, U any](it iter.Seq2[T, U]) iter.Seq[T]

Left creates a sequence of "left" elements from a sequence of pairs.

func List

func List[T any](values ...T) iter.Seq[T]

List returns an ordered sequence containing the given values.

func List2

func List2[T any](values ...T) iter.Seq2[int, T]

List2 returns an ordered sequence of pairs containing the given values paired with their indices.

func Map

func Map[T any, U any](it iter.Seq[T], f funcs.Map[T, U]) iter.Seq[U]

Map returns a sequence resulting from applying f to elements of it

func Map2

func Map2[T any, U any, V any](it iter.Seq2[T, U], f funcs.Map2[T, U, V]) iter.Seq2[T, V]

Map2 is like Map but operates on a sequence of pairs. The resulting sequence has the same "left" values as the input and "right" values obtained by applying f to the input pairs.

func MapSeq2

func MapSeq2[T any, U any, V any, W any](it iter.Seq2[T, U], f func(T, U) (V, W)) iter.Seq2[V, W]

MapSeq2 is like Map2 but the mapping function produces of the left and right values of the output sequence.

func Reject

func Reject[T any](it iter.Seq[T], p funcs.Select[T]) iter.Seq[T]

Reject returns a subsequence of it without elements for which p is true.

func Repeat

func Repeat[T any](it iter.Seq[T], n int) iter.Seq[T]

Repeat returns a sequence that repeats it n times. If n is negative, the resulting sequence is infinite.

func Right

func Right[T any, U any](it iter.Seq2[T, U]) iter.Seq[U]

Right creates a sequence of "right" elements from a sequence of pairs.

func Select

func Select[T any](it iter.Seq[T], p funcs.Select[T]) iter.Seq[T]

Select returns a subsequence of it with all elements for which p is true.

func Sum

func Sum[S Summable](it iter.Seq[S]) S

func TakeN

func TakeN[T any](it iter.Seq[T], n int) iter.Seq[T]

TakeN returns the longest prefix of it with at most n elements. If n is negative, the resulting sequence is empty.

func TakeWhile

func TakeWhile[T any](it iter.Seq[T], p funcs.Select[T]) iter.Seq[T]

TakeWhile returns the longest prefix of it for which p is true for every element.

func Zip

func Zip[T any](its ...iter.Seq[T]) iter.Seq[[]T]

func Zip2

func Zip2[T any, U any](v iter.Seq[T], w iter.Seq[U]) iter.Seq2[T, U]

Types

type Summable

type Summable interface {
	constraints.Integer | constraints.Float | constraints.Complex | ~string
}

Summable types can be added using the + operator