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]
• type VolatileSequence
  • func Volatile[T any](s Sequence[T]) VolatileSequence[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] interface {
	Each(func(T) error) error
}

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).

type VolatileSequence

type VolatileSequence[T any] interface {
	Sequence[T]
}

A VolatileSequence represents a sequence where the process of iterating over the sequence damages or changes it in a fundamental way. Since sequences are meant to be immutable, some cases can't uphold this requirement.

VolatileSequences are OK to be accessed once, but any further access will return ErrRepeatedUse immediately. They serve as an indication that the user may wish to wrap them using [process.Materialize] or [process.Buffer] if they think they may be used more than once.

func Volatile

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

Volatile wraps the provided sequence in the VolatileSequence type indicating it should only be iterated over a single time. Any sequence, even if not actually volatile can be wrapped, and will prevent repeat calls to Each.

The exact nature of the wrapped 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 in the same way