sequence

README

sequence

Sequence is a module containing packages around building, manipulating, and extracting data from "sequences". Sequences are a lazily processed type generated from either a concrete type, a generator method, or from another sequence. Processing is normally delayed until extracting the data from the sequence.

Warning

This package is in the process of being built up and protoyped without much of a clear design in mind. It's currently about playing around during Advent of Code (2023) and building up some utilities.

These packages are very much in flux, and can change in an instant. As a result, I'm not really going to look at the community tabs at all, respond to any issues, or accept pull requests. This is very much not for public consumption at the moment.

Documentation

Index

• Variables
• func Each[T any](s Sequence[T]) func(func(T) error) error
• func EachSimple[T any](s Sequence[T]) func(func(T) bool) error
• func Iterator[T any](s Sequence[T]) func(func(T) bool)
• type Pair
  • func MakePair[A, B any](a A, b B) Pair[A, B]
  • func (p Pair[A, B]) A() A
  • func (p Pair[A, B]) AB() (A, B)
  • func (p Pair[A, B]) B() B
  • func (p Pair[A, B]) BA() (B, A)
  • func (p Pair[A, B]) Swap() Pair[B, A]
• type Sequence
  • func Generate[T any](f func(func(T) error) error) Sequence[T]
  • func GenerateVolatile[T any](f func(func(T) error) error) Sequence[T]
  • func Volatile[T any](s Sequence[T]) Sequence[T]
  • func (s Sequence[T]) Each(f func(T) error) error
  • func (s Sequence[T]) IsVolatile() bool
  • func (s Sequence[T]) Materialize() Sequence[T]

Variables

var ErrRepeatedUse = errors.New("volatile sequence used more than once")

ErrRepeatedUse is returned by a VolatileSequence if it's accessed more than once.

var (
	// ErrStopIteration is used by iteration callbacks to indicate that
	// the iteration should be stopped early, but there was no other issue.
	ErrStopIteration = errors.New("iteration stopped")
)

Functions

func Each

func Each[T any](s Sequence[T]) func(func(T) error) error

Each returns a function to iterate over the sequence. The callback to the produced function is for users to receive and handle each value from the sequence, and return an error if processing should stop. The first error produced by the sequence, either an error from the callback or an error producing values will be returned. The ErrStopIteration error will not be returned from the iteration function.

func EachSimple

func EachSimple[T any](s Sequence[T]) func(func(T) bool) error

EachSimple is like Each, where a function is returned to iterate over the contents of the sequence, but the callback is in a simpler true/false form. An error generating a value will be returned, and iteration stopped. When the callback returns false, an ErrStopIteration error is passed through the sequence to anyone who cares about errors, but will be dropped before returning from EachSimple as it doesn't represent a real error.

func Iterator

func Iterator[T any](s Sequence[T]) func(func(T) bool)

Iterator is a wrapper on EachSimple and is used to work with the upcoming language extension that allow functions in a for-range statement. Thus, when avaliable, one may write "for x := range Iterator(seq) {}" to use a sequence directly in a for-loop.

Errors when generating the contents of the sequence will result in a panic.

Types

type Pair

type Pair[A, B any] struct {
	// contains filtered or unexported fields
}

A Pair is a 2 element tuple containing values of independant types.

func MakePair

func MakePair[A, B any](a A, b B) Pair[A, B]

MakePair creates a pair using its two arguments

func (Pair[A, B]) A

func (p Pair[A, B]) A() A

A returns the first value of the pair.

func (Pair[A, B]) AB

func (p Pair[A, B]) AB() (A, B)

AB returns both values from the pair in order.

func (Pair[A, B]) B

func (p Pair[A, B]) B() B

B returns the second value of the pair.

func (Pair[A, B]) BA

func (p Pair[A, B]) BA() (B, A)

BA returns both values from the pair in reverse order.

func (Pair[A, B]) Swap

func (p Pair[A, B]) Swap() Pair[B, A]

Swap retuns a new pair where the elements of the current pair are swapped.

type Sequence

type Sequence[T any] struct {
	// contains filtered or unexported fields
}

A Sequence represents a functionally immutable series of values. The sequence can only be used to fetch the values stored within, but the sequence itself can't be used to make changes.

func Generate

func Generate[T any](f func(func(T) error) error) Sequence[T]

Generate is used to create a sequence manually from a "sequence function". A sequence function represents the for loop that will produce all the values of the sequence, passing them to a callback. The callback returns an error either on a problem, or because the user of the data wishes to stop early (by sending ErrStopIteration). The generator is expected to stop immediately on a non-nill error from the callback, perform cleanup, and then return a non-nil error (preferably wrapping the error it was given) or the exact error it received.

The generator function should not handle ErrStopIteration itself, both for simplicity (unless it intends to wrap all errors), and to allow the top-level of the sequence processing to see it (or a wrapped version).

func GenerateVolatile

func GenerateVolatile[T any](f func(func(T) error) error) Sequence[T]

GenerateVolatile is a helper to do the following: Volatile(Generate(f)). It creates a volatile sequence from the provided sequence function.

func Volatile

func Volatile[T any](s Sequence[T]) Sequence[T]

Volatile returns a new sequence that depends on the the original, but is marked volatile, meaning it should only be iterated over a single time. Any sequence, even if not actually volatile can be wrapped, and will prevent repeat iterations over the sequence.

The exact nature of the volatile sequence is as follows:

• The first time it's used it will behave exactly as normal. It can stop early, fail, or run to completion
• Any subsequent accesses will return an error immediately. The behaviour is unaffected by the outcome of the first iteration
• Iterations concurrent with the first will also fail.

func (Sequence[T]) Each

func (s Sequence[T]) Each(f func(T) error) error

Each iterates over every item in the sequence calling the passed callback with each item. An error returned from the callback, or one that arose from the processing of the sequence will be returned if they arise and iteration will stop. Unlike the top-level functions that iterate over sequences, this method will not on it's own handle ErrStopIteration and return it instead.

func (Sequence[T]) IsVolatile

func (s Sequence[T]) IsVolatile() bool

IsVolatile returns true if the sequence is volatile, meaning that it should only be iterated over once. It is an error to call Each/EachSimple/Iterator more than once. Volatile sequences can be created with the [Volatlie] function.

func (Sequence[T]) Materialize

func (s Sequence[T]) Materialize() Sequence[T]

Materialize returns a new sequence where all the data (including any error) from the current sequence is cached and played back on each iteration.

This has 3 main benefits:

• It is likely faster than the original sequence
• It has no dependencies, not even on the original sequence
• It can be iterated over multiple times

The speed benefit only makes sense if you are going to iterate more than once, as Materialize otherwise requires the time to iterate the sequence to be created.

Otherwise, it's other main use is to overcome the limitations of volatile sequences.