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 AffineStep[Z Numeric](start Z, a, b Z) iter.Seq[Z]
• func All[T any](it iter.Seq[T], p PredicateFunc[T]) bool
• func Any[T any](it iter.Seq[T], p PredicateFunc[T]) bool
• 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 Cons[T any](head T, tail iter.Seq[T]) iter.Seq[T]
• func DropN[T any](it iter.Seq[T], n int) iter.Seq[T]
• func DropWhile[T any](it iter.Seq[T], p PredicateFunc[T]) iter.Seq[T]
• func DropWhile2[K any, T any](it iter.Seq2[K, T], p Predicate2Func[K, T]) iter.Seq2[K, T]
• func Empty[T any]() iter.Seq[T]
• func Empty2[T any, U any]() iter.Seq2[T, U]
• func False[T any](T) bool
• func False2[K any, T any](K, T) bool
• func Find[T any](it iter.Seq[T], p PredicateFunc[T]) (T, bool)
• func Find2[K any, T any](it iter.Seq2[K, T], p Predicate2Func[K, T]) (K, T, bool)
• func FlatMap[T any, U any](it iter.Seq[T], f MapFunc[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 FoldLFunc[T, U]) U
• func Identity[T any](v T) T
• func Identity2[K any, T any](k K, v T) T
• func Ints[Z constraints.Integer](start Z) iter.Seq[Z]
• func IntsStep[Z constraints.Integer](start Z, step Z) iter.Seq[Z]
• func IsZero[T comparable](v T) bool
• func Left[T any, U any](it iter.Seq2[T, U]) iter.Seq[T]
• func LenMax[T any](it iter.Seq[T], max int) (count int, ok bool)
• 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 MapFunc[T, U]) iter.Seq[U]
• func Map2[T any, U any, V any](it iter.Seq2[T, U], f Map2Func[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 PredicateFunc[T]) iter.Seq[T]
• func RejectValue[T comparable](it iter.Seq[T], v T) iter.Seq[T]
• func Repeat[T any](it iter.Seq[T], n int) iter.Seq[T]
• func RepeatedFunc[T any](start T, f func(T) T) iter.Seq[T]
• func Right[T any, U any](it iter.Seq2[T, U]) iter.Seq[U]
• func RunLength[T comparable](it iter.Seq[T]) iter.Seq2[int, T]
• func Select[T any](it iter.Seq[T], p PredicateFunc[T]) iter.Seq[T]
• func Select2[K any, T any](it iter.Seq2[K, T], p Predicate2Func[K, T]) iter.Seq2[K, T]
• func Sum[S Summable](it iter.Seq[S]) S
• func SumMap[T any, Z Summable](it iter.Seq[T], f func(T) Z) Z
• func TakeN[T any](it iter.Seq[T], n int) iter.Seq[T]
• func TakeWhile[T any](it iter.Seq[T], p PredicateFunc[T]) iter.Seq[T]
• func True[T any](T) bool
• func True2[K any, T any](K, T) bool
• func Uniq[T comparable](it iter.Seq[T]) iter.Seq[T]
• func Unique[T comparable](it iter.Seq[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 FoldLFunc
• type FoldRFunc
• type Map2Func
• type MapFunc
• type Numeric
• type Predicate2Func
• type PredicateFunc
  • func EqualFunc[T comparable](v T) PredicateFunc[T]
• type Summable

Functions

func AffineStep

func AffineStep[Z Numeric](start Z, a, b Z) iter.Seq[Z]

AffineStep returns a sequence of repeated applications of the affine function f(z) = a*z + b to the initial value start.

func All

func All[T any](it iter.Seq[T], p PredicateFunc[T]) bool

All return true if all elements of it satisy the predicate p. All returns true if the sequence is empty.

func Any

func Any[T any](it iter.Seq[T], p PredicateFunc[T]) bool

Any returns true if any element of it satisfies the predicate p. Any returns false if the sequence is empty.

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 Cons

func Cons[T any](head T, tail iter.Seq[T]) iter.Seq[T]

Cons returns a sequence with head as the first element followed by the elements of tail.

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 PredicateFunc[T]) iter.Seq[T]

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

func DropWhile2

func DropWhile2[K any, T any](it iter.Seq2[K, T], p Predicate2Func[K, T]) iter.Seq2[K, T]

DropWhile2 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 False

func False[T any](T) bool

False is a PredicateFunc that always returns false.

func False2

func False2[K any, T any](K, T) bool

False2 is a Predicate2Func that always returns false.

func Find

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

Find returns the first element in it for which p is true along with the bool true. If there is no such element, it returns a zero value and false.

func Find2

func Find2[K any, T any](it iter.Seq2[K, T], p Predicate2Func[K, T]) (K, T, bool)

Find2 returns the first pair in it for which p is true along with the bool true. If there is no such pair, it returns zero values and false.

func FlatMap

func FlatMap[T any, U any](it iter.Seq[T], f MapFunc[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 FoldLFunc[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 Identity

func Identity[T any](v T) T

Identity is a MapFunc that returns its argument unchanged.

func Identity2

func Identity2[K any, T any](k K, v T) T

Identity2 is a Map2Func that returns the second argument unchanged.

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 IsZero

func IsZero[T comparable](v T) bool

IsZero is a PredicateFunc that returns true for zero values of the type T and false

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 LenMax

func LenMax[T any](it iter.Seq[T], max int) (count int, ok bool)

LenMax counts elements in the sequence by iterating it up to max elements. LenMax consumes non-replayable sequences. If max is not a positive int, LenMax iterates the entire sequence. The returned bool is true if the end of the sequence was reached.

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 MapFunc[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 Map2Func[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 PredicateFunc[T]) iter.Seq[T]

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

func RejectValue

func RejectValue[T comparable](it iter.Seq[T], v T) iter.Seq[T]

func Repeat

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

Repeat returns a sequence that repeats the sequence it n times. If n is negative, the resulting sequence is infinite. Only replayable sequences can be repeated.

func RepeatedFunc

func RepeatedFunc[T any](start T, f func(T) T) iter.Seq[T]

RepeatedFunc returns a sequence of repeated applications of the function: start, f(start), f(f(start)), ...

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 RunLength

func RunLength[T comparable](it iter.Seq[T]) iter.Seq2[int, T]

RunLength returns a sequence of pairs of the form (n, v) where n is the number of consecutive occurrences of v in it. RunLength is similar to Uniq but it also counts the number of consecutive duplicates. RunLength uses constant memory.

func Select

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

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

func Select2

func Select2[K any, T any](it iter.Seq2[K, T], p Predicate2Func[K, T]) iter.Seq2[K, T]

func Sum

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

Sum returns the sum of sequence elements.

func SumMap

func SumMap[T any, Z Summable](it iter.Seq[T], f func(T) Z) Z

SumMap returns the sum of the sequence elements under the image of f.

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 PredicateFunc[T]) iter.Seq[T]

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

func True

func True[T any](T) bool

True is a PredicateFunc that always returns true.

func True2

func True2[K any, T any](K, T) bool

True2 is a Predicate2Func that always returns true.

func Uniq

func Uniq[T comparable](it iter.Seq[T]) iter.Seq[T]

Uniq returns a sequence of values from it with consecutive duplicates removed much like the uniq command line utility. The iteration uses constant memory.

See Unique for building a sequence of truly unique values.

func Unique

func Unique[T comparable](it iter.Seq[T]) iter.Seq[T]

Unique returns a sequence that passes through unique elements of it the first time each is encountered. Unique uses memory proportional to the number of unique sequence elements.

See Uniq for a more memory efficient way of removing duplicates from (sorted) sequences.

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 FoldLFunc

type FoldLFunc[T any, U any] = func(accumulator U, value T) U

FoldLFunc merges a value into an accumulator from the left.

type FoldRFunc

type FoldRFunc[T any, U any] = func(value T, accumulator U) U

FoldRFunc merges a value into an accumulator from the right.

type Map2Func

type Map2Func[K any, T any, U any] = func(index K, value T) U

Map2Func transforms a value with an associated key/index

type MapFunc

type MapFunc[T any, U any] = func(value T) U

MapFunc transforms a single value

type Numeric

type Numeric interface {
	constraints.Integer | constraints.Float | constraints.Complex
}

Numeric is a constraint that matches all numeric types.

type Predicate2Func

type Predicate2Func[K any, T any] = func(index K, value T) bool

PredicateFunc returns true for values that should be selected.

type PredicateFunc

type PredicateFunc[T any] = func(value T) bool

PredicateFunc returns true for values that should be selected.

func EqualFunc

func EqualFunc[T comparable](v T) PredicateFunc[T]

EqualFunc returns a PredicateFunc that returns matches values equal to v.

type Summable

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

Summable is a constraint that matches types that can be added using the + operator.