sequence

package module
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2023 License: MIT Imports: 10 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 (
	// 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")

	// ErrEmptySequence is returned when an operation expects a non-empty
	// sequence, but doesn't get one.
	ErrEmptySequence = errors.New("empty sequence")
)
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.

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

func IntoMap[M ~map[K]V, K comparable, V any](dst M, s Sequence[Pair[K, V]]) error

IntoMap stores the pairs from the given sequence into the provided map. Multiple items with the same key from the sequence will cause the later ones to overwrite earlier ones. If an error occurs generating items from the sequence the map will be partially updated with every item upto the 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.

func PairCompare added in v0.0.10 

func PairCompare[A, B cmp.Ordered](a, b Pair[A, B]) int

PairCompare compares two Pair values with the same element types provided both items in the pair are a cmp.Ordered type. The comparison first looks at the first (A) value, and if equal, moves on to the second (B) value.

func PairCompareFirst added in v0.0.10 

func PairCompareFirst[A cmp.Ordered, B any](a, b Pair[A, B]) int

PairCompareFirst compares 2 pairs by only their first elements using cmp.Compare. The second element of the Pair is completely ignored for the purpose of the comparison.

func PairCompareSecond added in v0.0.10 

func PairCompareSecond[A, B cmp.Ordered](a, b Pair[A, B]) int

PairCompareSecond compares 2 pairs by only their second elements using cmp.Compare. The first element of the Pair is completely ignored for the purpose of the comparison.

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

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

Unzip takes a sequence of pairs and returns two sequences, one containing the first item of each pair, the other containing the second of each pair.

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

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

A Result represents a (Value,error) tuple where both could be present. It will panic if the value is accessed alone when the error is non-nil.

func Append added in v0.0.5 

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

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) Result[U]

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)) Result[U]

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]) Result[int]

Count returns a Result with the number of items in the given sequence, or an error if one was produced while iterating the sequence.

func First added in v0.0.5 

func First[T any](s Sequence[T]) Result[T]

First returns a Result containing 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 Last added in v0.0.5 

func Last[T any](s Sequence[T]) Result[T]

Last returns a Result containing the final value from the given sequence and any error should the sequence end with an error.

func MakeResult added in v0.1.0 

func MakeResult[T any](value T, err error) Result[T]

MakeResult is the base constructor for a result where both the value and error are specified. Useful for wrapping a (T,error) returning function.

func Max added in v0.0.8 

func Max[T cmp.Ordered](s Sequence[T]) Result[T]

Max returns a Result containing the smallest item from the sequence of cmp.Ordered items. The result will contain only an error if one stopped processing early.

func MaxFunc added in v0.0.8 

func MaxFunc[T any](s Sequence[T], less func(x, y T) bool) Result[T]

MaxFunc returns the largest item from the sequence as determined by the provided comparision function. The comparison must return true if the first value is strictly less than the second. The returned result like with Max, will only contain the error if one occurred.

func Min added in v0.0.8 

func Min[T cmp.Ordered](s Sequence[T]) Result[T]

Min returns a Result containing the smallest item from the sequence of cmp.Ordered items. Any error during processing will stop the collection early, and the Result generate will only contain the error.

func MinFunc added in v0.0.8 

func MinFunc[T any](s Sequence[T], less func(x, y T) bool) Result[T]

MinFunc returns the smallest item from the sequence as determined by the provided comparision function. The comparison must return true if the first value is strictly less than the second. Otherwise it returns a Result with the same restrictions as Min.

func NextResult added in v0.1.0 

func NextResult[In, Out any](in Result[In], f func(In) Out) Result[Out]

NextResult accepts a Result, and a function that will process the value stored within, to produce a new Result value. If the input Result has an error, no work is done other than propogating the error to the output Result value.

func NextResultErr added in v0.1.2 

func NextResultErr[In, Out any](in Result[In], f func(In) (Out, error)) Result[Out]

NextResultErr accepts a Result, and a function that will process the value stored within, to produce a new Result value. If the input Result has an error, no work is done other than propogating the error to the output Result value. Otherwise the return values of the callback produces a value/error Result.

func Product added in v0.0.8 

func Product[T tools.Arithmetic](s Sequence[T]) Result[T]

Product is a helper function for a sequence of arithmetic values that returns the product of all values in the sequence.

func ResultError added in v0.1.0 

func ResultError[T any](err error) Result[T]

ResultError creates a result with just an error. One may need to pass a type argument, since it's likely the generic type inference won't detect the the needed value type of the Result.

func ResultValue added in v0.1.0 

func ResultValue[T any](value T) Result[T]

ResultValue creates a result using just the provided value, assuming a nil error.

func Sum added in v0.0.6 

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

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

func ToMap added in v0.0.12 

func ToMap[K comparable, V any](s Sequence[Pair[K, V]]) Result[map[K]V]

ToMap creates a map from the given sequence of Pairs, and returning it in a Result. The first element in each pair must be comparable, since it must become a map key. Earlier items with the same key will be replaced by later items in the sequence. If an error occurs, the value of the Result will contain all the items processed so far.

func ToSlice added in v0.0.5 

func ToSlice[T any](s Sequence[T]) Result[[]T]

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

func (Result[T]) Clean added in v0.1.0 

func (r Result[T]) Clean() Result[T]

Clean returns a new result where the presence of an error means that the value is the zero value.

func (Result[T]) DropError added in v0.1.0 

func (r Result[T]) DropError() Result[T]

DropError returns a new result copied from the current result, with the error explicity set to nil. This should only be used if the error can safely be ignored or has already been dealt with.

func (Result[T]) Error added in v0.1.0 

func (r Result[T]) Error() error

Error returns the error stored in this result (if any) or nil.

func (Result[T]) HasError added in v0.1.0 

func (r Result[T]) HasError() bool

HasError returns true if there's an error present in this Result.

func (Result[T]) Pair added in v0.1.0 

func (r Result[T]) Pair() (T, error)

Pair returns both the value stored and error (if any). It does not panic.

func (Result[T]) Value added in v0.1.0 

func (r Result[T]) Value() T

Value returns the value stored in this result (if any). If there is an error stored in the result, this method will panic, otherwise the value is returned or a zero value if none was stored.

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

func FromMap[K comparable, V any](m map[K]V) Sequence[Pair[K, V]]

FromMap creates a sequence of pairs, where the first item in the pair is a key from the map, and the second item is the value for that key. The sequence is Volatile, since multiple iterations could produce different results.

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

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

Inspect adds an "inpection" phase to the given sequence, where each value, and it's index is passed to the callback. The result of the callback may be an error to stop iteration, but otherwise, the value is returned from the sequence as though the inspection step never happened.

Note: a reference type can be changed by the inspection function, since only a shallow copy is made for passing on.

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

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

Reverse returns a sequence that produces the items from the input sequence in reverse order.

Note: This function must read and store the entire sequence prior to reversing it, which may be an issue for large/infinite sequences.

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

func Simulate[T any](prev Sequence[T], step func(T) (T, bool)) Sequence[T]

Simulate produces a sequence where items are generated by taking the previously generated item, and running it through a step function that returns a new item, and whether or not there are more values to come. This process is fed by the provided sequence where the final element of that sequence is the initial value to step. The final returned sequence is the concatenation of the starting sequence and the simulated elements. The generated sequence will be volatile if the input sequence is volatile.

func SimulateOne added in v0.0.14 

func SimulateOne[T any](prev Sequence[T], step func(T) T) Sequence[T]

SimulateOne is like Simulate except that a single step is unconditionally done, producing a sequence that has one more element than the input. The new sequence is produced using Derive so will retain the properties of the input sequence.

func Simulation added in v0.0.13 

func Simulation[T any](initial T, step func(T) (T, bool)) Sequence[T]

Simulation creates a sequence where an initial state is updated by a function that produces a new state, and indicates if there is more work to be done. The sequence of states is expected to be deterministic given the initial state and the step function, if not, the sequence should be marked volatile. The output sequence returns the series of states created from the initial state to the final state.

Logically, this is equivalent to Single(initial).Simulate(step), but slightly faster due to avoiding creating and iterating the first sequence.

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

func Sort[T any](s Sequence[T], cmp func(a, b T) int) Sequence[T]

Sort creates a sequence using the comparision function that returns the items of the original sequence in sorted order. The comparison function is the same used for slices.Sort and can be cmp.Compare for cmp.Ordered types.

Note: This function must read and store the entire sequence prior to sorting it, which may be an issue for large/infinite sequences.

func SortOrdered added in v0.0.10 

func SortOrdered[T cmp.Ordered](s Sequence[T]) Sequence[T]

SortOrdered creates a sequence that provides the items from a sequence of cmp.Ordered items in sorted order.

Note: This function must read and store the entire sequence prior to sorting it, which may be an issue for large/infinite sequences.

func SortStable added in v0.0.10 

func SortStable[T any](s Sequence[T], cmp func(a, b T) int) Sequence[T]

SortStable is like Sort and takes the same parameters, but the resulting sort/order will be stable.

Note: This function must read and store the entire sequence prior to sorting it, which may be an issue for large/infinite sequences.

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]) Count added in v0.1.0 

func (s Sequence[T]) Count() Result[int]

Count is a helper to call the package function Count on the receiver.

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() Result[T]

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

func (Sequence[T]) Inspect added in v0.1.3 

func (s Sequence[T]) Inspect(inspect func(int, T) error) Sequence[T]

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

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() Result[T]

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]) Reverse added in v0.0.10 

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

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

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]) Simulate added in v0.0.13 

func (s Sequence[T]) Simulate(step func(T) (T, bool)) Sequence[T]

Simulate is a helper method to call the package function Simulate on the receiver to produce new simulated values to extend the current sequence.

func (Sequence[T]) SimulateOne added in v0.0.14 

func (s Sequence[T]) SimulateOne(step func(T) T) Sequence[T]

SimulateOne is a helper method to call the package function SimulateOne on the receiver to produce a sequence with a simulated value added to the end.

func (Sequence[T]) Sort added in v0.0.10 

func (s Sequence[T]) Sort(cmp func(T, T) int) Sequence[T]

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

func (Sequence[T]) SortStable added in v0.0.10 

func (s Sequence[T]) SortStable(cmp func(T, T) int) Sequence[T]

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

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() Result[[]T]

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.