sequence

package module
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 5, 2023 License: MIT Imports: 4 Imported by: 0

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

Constants

This section is empty.

Variables

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

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

View Source 
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 Append added in v0.0.5 

func Append[S ~[]T, T any](dst S, s Sequence[T]) (S, error)

Append processes the given sequence such that each item returned is appended to the provided destination slice. The resulting final slice is returned.

func Collect added in v0.0.5 

func Collect[T, U any](s Sequence[T], initial U, process func(T, U) U) (U, error)

Collect produces a single value from a sequence. It starts with an initial output value, and for every item in the sequence the value is permuted by the process function using the item from the sequence and the current value.

func CollectErr added in v0.0.5 

func CollectErr[T, U any](s Sequence[T], initial U, process func(T, U) (U, error)) (U, error)

CollectErr produces a single value from a sequence. It starts with an initial output value, and for every item in the sequence the value is permuted by the process function using the item from the sequence and the current value.

The callback may return errors to stop processing, either to indicate failure, or in the case of ErrStopIteration to simply end processing.

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 First added in v0.0.5 

func First[T any](s Sequence[T]) (T, error)

First returns the first value from the given sequence, or an error if even that isn't possible.

func IntoChan added in v0.0.5 

func IntoChan[T any](ch chan<- T, s Sequence[T]) error

IntoChan sends the contents of the sequence into the channel. If an error occurs processing the sequence it will be returned.

func IntoChanCtx added in v0.0.5 

func IntoChanCtx[T any](ctx context.Context, ch chan<- T, s Sequence[T]) error

IntoChanCtx sends the contents of the sequence into the channel. If an error occurs processing the sequence it will be returned. The provided context will be consulted for an alternate reason to stop iteration.

func IntoChanPair added in v0.0.5 

func IntoChanPair[T any](ch chan<- Pair[T, error], s Sequence[T])

IntoChanPair sends the items from a sequence into a channel of type Pair[T,error] for the purpose of passing on the error from the sequence should one occur. If such an error happens it will be in a <zero,error> element on its own.

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.

func Last added in v0.0.5 

func Last[T any](s Sequence[T]) (T, error)

Last returns the final value from the given sequence and any error should the sequence end with an error. Unlike most functions both value and error will be returns as it's really upto the caller to determine if an error should stop downstream processing in this case. Note: ErrStopIteration will still be suppressed as normal as it indicates early exit without error.

func ToChan added in v0.0.5 

func ToChan[T any](s Sequence[T]) <-chan T

ToChan returns a channel that will receive the values from the sequence. If the sequence produces an error, then this code will panic.

func ToChanCtx added in v0.0.5 

func ToChanCtx[T any](ctx context.Context, s Sequence[T]) (<-chan T, context.Context)

ToChanCtx returns a channel and a context where the channel returns values emitted from the input sequence, and the context will be cancelled if the sequence returns an error. An input context is used as the basis of the generated context, and can be used to cancel processing externally.

func ToChanErr added in v0.0.5 

func ToChanErr[T any](s Sequence[T]) (<-chan T, <-chan error)

ToChanErr returns 2 channels, the first containing items from the sequence, and the second will receive an error if the sequence failed with that error.

func ToChanPair added in v0.0.5 

func ToChanPair[T any](s Sequence[T]) <-chan Pair[T, error]

ToChanPair returns a channel whose elements are Pair[T,error] such that errors that arise while processing the sequence will return a <zero,err> Pair.

func ToSlice added in v0.0.5 

func ToSlice[T any](s Sequence[T]) ([]T, error)

ToSlice returns a new slice containing every item received from the given sequence, or any error that occured while doing so.

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 AddFirst added in v0.0.5 

func AddFirst[A, T any](a A, s Sequence[T]) Sequence[Pair[A, T]]

AddFirst creates a sequence where each item is a pair of a constant value and a value from a given sequence. The constant value is the first item in the pair.

func AddSecond added in v0.0.5 

func AddSecond[T, B any](s Sequence[T], b B) Sequence[Pair[T, B]]

AddSecond creates a sequence where each item is a pair of a constant value and a value from a given sequence. The constant value is the second item in the pair.

func Concat added in v0.0.5 

func Concat[T any](seqs ...Sequence[T]) Sequence[T]

Concat performs a concatenation of multiple sequences, where each sequence is iterated in turn until the final one is completed.

func Error added in v0.0.5 

func Error[T any](err error) Sequence[T]

Error returns a sequence where the given error is return when iterated upon.

func Filter added in v0.0.5 

func Filter[T any](s Sequence[T], pred func(T) bool) Sequence[T]

Filter takes an input sequence and creates a sequence where only the values that pass the provided predicate function will be emitted. The ouput sequence will be the same type as the input sequence.

func FilterErr added in v0.0.5 

func FilterErr[T any](s Sequence[T], pred func(T) (bool, error)) Sequence[T]

FilterErr takes an input sequence and creates a sequence where only the values that pass the provided predicate function will be emitted. The ouput sequence will have the same element type as the input sequence.

FilterErr allows the callback to stop iteration with a generic error, or use ErrStopIteration to simply indicate that no more values should be proceed.

func FirstOnly added in v0.0.5 

func FirstOnly[A, B any](s Sequence[Pair[A, B]]) Sequence[A]

FirstOnly takes a sequence of Pair values, and returns a sequence of just the first value from each pair.

func Flatten added in v0.0.5 

func Flatten[T any, S ~[]T](src Sequence[S]) Sequence[T]

Flatten processes a sequence of slices, producing a new sequence of the element type, and iterating across each slice as it's pulled from the input.

func FromChan added in v0.0.5 

func FromChan[T any](ch <-chan T) Sequence[T]

FromChan produces a sequence from the provided channel. The new sequence is volatile since the channel itself can only be iterated over once.

func FromSlice added in v0.0.5 

func FromSlice[T any](items []T) Sequence[T]

FromSlice returns a sequence where the elements of the slice are returned. The source slice is reference from the sequence so certain changes to that slice may affect the sequence.

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 added in v0.0.4 

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 Infinite added in v0.0.5 

func Infinite[T any](t T) Sequence[T]

Infinite generates a sequence where the given value is returned forever, on each iteration of the sequence.

func Limit added in v0.0.5 

func Limit[T any](s Sequence[T], n int) Sequence[T]

Limit returns a sequence where only a given number of items can be accessed from the input sequence before hitting the end of the sequence.

func Map added in v0.0.5 

func Map[In, Out any](s Sequence[In], convert func(In) Out) Sequence[Out]

Map takes in an input sequence and returns a sequence where every input value is permuted by the provided convert function. The new sequence may be of a different type due to the conversion, but will have the same number of items.

func MapErr added in v0.0.5 

func MapErr[In, Out any](s Sequence[In], convert func(In) (Out, error)) Sequence[Out]

MapErr takes in an input sequence and returns a sequence where every input value is permuted by the provided convert function. The new sequence may be of a different type due to the conversion, but will have the same number of items.

MapErr allows the callback to stop iteration with a generic error, or use ErrStopIteration to simply indicate that no more values should be proceed.

func MapFilter added in v0.0.5 

func MapFilter[In, Out any](s Sequence[In], convert func(In) (Out, bool, error)) Sequence[Out]

MapFilter performs both a Map and Filter operation on the input sequence where the convert function returns both the new value, and a boolean to indicate if it should be added at all.

MapFilter allows the callback to stop iteration with a generic error, or use ErrStopIteration to simply indicate that no more values should be proceed.

func Materialize added in v0.0.5 

func Materialize[T any](s Sequence[T]) 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.

func New added in v0.0.5 

func New[T any](items ...T) Sequence[T]

New creates a simple sequence using the provided items.

func Process added in v0.0.5 

func Process[In, Out any](src Sequence[In], proc func(In, func(Out)) error) Sequence[Out]

Process provides a method of generating a destination sequence from a given input sequence using a BEAM style emitter.

The proc callback receives each input item, one at a time, and calls the provided emmiter function to output zero, one, or many results from that single input value. It can also return an error to stop processing.

func Repeat added in v0.0.5 

func Repeat[T any](t T, n int) Sequence[T]

Repeat generates a sequence where the given item is returns a fixed number of times.

func SecondOnly added in v0.0.5 

func SecondOnly[A, B any](s Sequence[Pair[A, B]]) Sequence[B]

SecondOnly takes a sequence of Pair values, and returns a sequence of just the second value from each pair.

func Single added in v0.0.5 

func Single[T any](t T) Sequence[T]

Single returns a sequence where the given value is returned once.

func SwapPairs added in v0.0.5 

func SwapPairs[A, B any](s Sequence[Pair[A, B]]) Sequence[Pair[B, A]]

SwapPairs processes a sequence with Pair[A,B] elements to produce one where the elements in the pair are swapped (i.e. Pair[B,A]).

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 Zip added in v0.0.5 

func Zip[A, B any](aSeq Sequence[A], bSeq Sequence[B]) Sequence[Pair[A, B]]

Zip combines two input sequences into a sequence of Pairs where each pair contains an item from the first sequence matched up with one from the second sequence. When one seqence ends, the zipped sequence continues producing Pairs where one element is the zero value until both sequences are finished.

func ZipShortest added in v0.0.5 

func ZipShortest[A, B any](aSeq Sequence[A], bSeq Sequence[B]) Sequence[Pair[A, B]]

ZipShortest is like Zip, but stops once one sequence is empty.

func (Sequence[T]) Concat added in v0.0.5 

func (s Sequence[T]) Concat(next ...Sequence[T]) Sequence[T]

Concat is a helper method which calls the top level function Concat to build a combined sequence of receiver followed by the given sequence(s).

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 added in v0.0.4 

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 added in v0.0.4 

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

Materialize is a utility method that calls the package level function Materialize on this sequence.

func (Sequence[T]) ToSlice added in v0.0.5 

func (s Sequence[T]) ToSlice() ([]T, error)

ToSlice is a utility method that calls the top level function version of ToSlice.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.