sequence

package module
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Dec 7, 2023 License: MIT Imports: 7 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. Collect uses Sync to synchronize updating the accumulated value, but the order of updates is non-deterministic.

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. CollectErr uses Sync to synchronize updating the value but there is no guarantee that the processing step will happen in the same order.

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

func Count added in v0.0.7 

func Count[T any](s Sequence[T]) (int, error)

Count returns the number of items in the given sequence, and an error if any are produced while iterating the sequence.

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. The results of first are not deterministic for an asynchronous sequence.

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

func Sum[T tools.Arithmetic](s Sequence[T]) (T, error)

Sum is a helper function for a sequence of arithmetic values that produces the sum of the entire sequence.

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]) String added in v0.0.7 

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

String returns a string representation of this pair.

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

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

Async is an alias for AsyncProcs.

func AsyncCPUs added in v0.0.7 

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

AsyncCPUs is a helper that calls AsyncPool with the pool size set using runtime.NumCPU.

func AsyncPool added in v0.0.7 

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

AsyncPool create a derived sequence that processes the input sequence using parallel goroutines. At most n goroutines may be in-flight at once, and a negative value results in no limit.

All Aync* sequences provide no guarantee on the order of results in iteration, and downstream errors / early exits may not prevent the the processing of additional elements, although the errors will be processed and one will be returned.

Due to the unstable nature of results, async sequences are also marked as volatile, meaning that they can only be iterated over once, and need to be generated again from the input sequence, or the results need to be materialized with Materialize or [extra.Buffer].

Note: any state that is altered by a downstream operation, e.g. Collect may produce unexpected results since the order is non-deterministic, and the access is unsynchronized.

func AsyncProcs added in v0.0.7 

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

AsyncProcs is a helper that calls AsyncPool with the pool size set using runtime.GOMAXPROCS.

func Buffer added in v0.0.7 

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

Buffer is an alternative to the Materialize method that waits until the sequence is accessed before creating the cached copy. This means that there is basically no cost in computation or memory if the sequence hasn't been used yet.

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

func Counter[T tools.Arithmetic](start T) Sequence[T]

Counter creates a continuously increasing sequence of numbers starting from the given value and incrementing by 1. It is an infinite sequence.

func Derive added in v0.0.7 

func Derive[Out, In any](input Sequence[In], f func(func(Out) error) error) Sequence[Out]

Derive creates a new sequence where the properties of the input sequence are copied over to the created sequence. This makes sense when permuting a sequence as it will usually have the same properties.

For example: using Map to permute a Volatile sequence results in the output sequence being Volatile as well.

The "sequence function" passed as parameter is the same as for Generate, and neither its element type nor that of the returned sequence need to match the input sequence. The sole purpose of the input sequence is to provide the sequence properties for the output.

The properties that are copied include:

  • volatile
  • async

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

The resulting sequence is neither volatile, nor asynchronous, although an asynchronous input will mean the values stored for playback will be in a non-deterministic order.

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

func NumberSequence[T tools.Integer | tools.Real](start, stop, step T) Sequence[T]

NumberSequence creates a finite sequence of numbers starting at a given value, incrementing by another value, and ending when the counter exceeds a given point analogeous to a "for i:=start; i<stop; i+=step {}" loop.

- If start >= stop, a 0-item sequence is produced. - If step <= 0, an erroring sequnce is produced as it's likely a mistake.

func PairSelectA added in v0.0.6 

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

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

func PairSelectB added in v0.0.6 

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

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

func PairSwap added in v0.0.6 

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

PairSwap 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 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 Scan added in v0.0.6 

func Scan[T, U any](s Sequence[T], initial U, op func(T, U) U) Sequence[U]

Scan converts a sequence into a scaned version of the sequence where every element returned is the result of performing a binary operation between the element from the input sequence and an accumulator, with the result also going back in the accumulator. The initial value of the accumulator must also be provided. It is recommended that op be commutative and associative for consistent results.

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

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

Sync creates a new sequence where the iteration is guaranteed to produce values synchronously for downstream use. It's a no-op if the sequence is not asynchronous. This is to allow downstream processing to not have to worry about synchronizing access to local state, as the callback will only ever have one call in-flight at any time at the cost of this coarse-grained locking. Downstream code that is already thread-safe doesn't need to call sync in this case, and may see performance benefits.

Note: Async sequences are also volatile, and using Sync doesn't change that, so you still need to either only iterate once or use Materialize/Buffer to create a non-volatile sequence.

func Until added in v0.0.7 

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

Until returns a sequence that mirrors the provided sequence until the given predicate returns true. It's the logical counterpoint to While.

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

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

While wraps a sequence to have it end early when the predicate returns false.

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

If at least one sequence is volatile then the output sequence will be as well.

func ZipLongest added in v0.0.7 

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

ZipLongest is like Zip, but when the shorter sequence ends the output uses a zero value in it's place while the longer sequence continues.

func (Sequence[T]) Async added in v0.0.7 

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

Async is a helper method that calls the top level function Async with the receiver.

func (Sequence[T]) AsyncPool added in v0.0.7 

func (s Sequence[T]) AsyncPool(n int) Sequence[T]

AsyncPool is a helper method to call the top-level function AsyncPool using the receiver.

func (Sequence[T]) Buffer added in v0.0.7 

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

Buffer is a helper method to call the package function Buffer on the receiver.

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]) Filter added in v0.0.6 

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

Filter is a helper method that creates a new sequence via the top level function Filter using the receiver and the given predicate function.

func (Sequence[T]) First added in v0.0.6 

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

First is a helper method for the top level function First.

func (Sequence[T]) IsAsync added in v0.0.7 

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

IsAsync will return true if the sequence will asynchronously generate values during iteration.

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]) Last added in v0.0.6 

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

Last is a helper method for the top level function Last.

func (Sequence[T]) Limit added in v0.0.7 

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

Limit is a helper method to call the top level function Limit on the receiver.

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]) Scan added in v0.0.6 

func (s Sequence[T]) Scan(initial T, op func(T, T) T) Sequence[T]

Scan is a helper method for calling the top level function Scan with the current sequence, as long as the accumulator and binary operation all use and return the same type as the sequence's element type.

func (Sequence[T]) Sync added in v0.0.7 

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

Sync is a helper that calls the top level function Sync with the reciever.

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.

func (Sequence[T]) Until added in v0.0.7 

func (s Sequence[T]) Until(pred func(T) bool) Sequence[T]

Until is a helper method to call the top level function Until on the receiver.

func (Sequence[T]) While added in v0.0.7 

func (s Sequence[T]) While(pred func(T) bool) Sequence[T]

While is a helper method to call the top level function While on the receiver.

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.