sequences
About
sequences
is a collection of utilities for working with lazily-evaluated
sequences of data.
Working with lazily-evaluated sequences can be more efficient than other JS alternatives, as it allows you to minimize intermediate memory allocations where possible, and only perform operations on elements that contribute to your final result.
// temporary arrays are created by filter and map,let val = -3 -2 -1 0 1 2 3 ; // no temporary arrayslet val2 = ;
Why not ES6 Iterators?
-
ES6 Iterators require a temporary
{ done, value }
object to be allocated with every call, which reduces performace. -
Sequence().read()
accepts a 'recycle' parameter when called, which allows you to re-use previously allocated values, to minimize allocations. -
Sequence().read()
returns the next result or the terminatorSequence().END
, which can simplify control flow compared to having an "independent" control channel (the iteratordone
parameter).
Why ES6 Iterators?
- You want to use the Iterable protocol.
API
object
sequences : Kind: global namespace
- sequences :
object
- .Sequence
- .Assert ⇒
Sequence
- .Concat ⇒
Sequence
- .Count ⇒
Sequence
- .Deduplicate ⇒
Sequence
- .Default ⇒
Sequence
- .Drain ⇒
Sequence
- .Each ⇒
Sequence
- .Filter ⇒
Sequence
- .Flatten ⇒
Sequence
- .FromArray ⇒
Sequence
- .FromBlocks ⇒
Sequence
- .FromIterator ⇒
Sequence
- .From ⇒
Sequence
- .FromObject ⇒
Sequence
- .FromSet ⇒
Sequence
- .Group ⇒
Sequence
- .Join ⇒
Array
- .Map ⇒
Sequence
- .Reduce ⇒
Sequence
- .Replace ⇒
Sequence
- .Slice ⇒
Sequence
- .Sort ⇒
Sequence
- .Splice ⇒
Sequence
- .ToArray ⇒
Sequence
- .ToBlocks ⇒
Sequence
- .ToIterator ⇒
Iterator
- .ToObject ⇒
Sequence
- .ToSet ⇒
Sequence
- .Window ⇒
Sequence
- .Zip
- .bytes :
object
- .FromHex ⇒
Sequence
- .FromWords ⇒
Sequence
- .ToHex ⇒
Sequence
- .ToWords ⇒
Sequence
- .FromHex ⇒
- .random :
object
- .RandomBoolean ⇒
Sequence
- .RandomInteger ⇒
Sequence
- .Random ⇒
Sequence
- .RandomSelection ⇒
Sequence
- .XORShift32 ⇒
Sequence
- .RandomBoolean ⇒
sequences.Sequence
Kind: static class of sequences
new Sequence()
Sequence
is the base sequence class.
it should always be subclassed.
sequence constructors should never require new.
sequence.read(recycle)
read is the core method of a sequence. read should return the next value in the sequence. if there are no more values to read, read should return Sequence.END
Kind: instance method of Sequence
Params
- recycle - a 'container' value to re-use when returning the next value. always optional.
sequence.pipe(sequenceConstructor, ...args)
// thislet seq = ;seq = ;seq = ;seq = ; // is equivalent to thisconst seq = ;
pipe is a utility method to wrap one sequence in another.
Kind: instance method of Sequence
Params
- sequenceConstructor - the constructor function for another sequence. pipe assumes the constructor takes a source sequence as its first argument
- ...args
*
- any number of additional args to pass into sequenceConstructor
Sequence
sequences.Assert ⇒ let Assert = ;let From = ;let ToArray = ; let Number; // val is [ 1, 2, 3, 4 ]let val = ; // throws an assertion errorlet val2 = ;
Assert
is a sequence wrapper that builds a sequence to run an assertion against every value in the sequence
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - assert
function
- an assertion function - error
function
- an error builder function
Sequence
sequences.Concat ⇒ let Count = ; let Slice = ; let Concat = ; // res is '0 - 1 - 2 - 3 - 4': let res = ;
Concat
performs string concatenation of all elements in a sequence
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - separator
string
- an optional separator string, to be placed in
Sequence
sequences.Count ⇒ let Count = ;let Slice = ;let ToArray = ; // val is [ 0, 1, 2, 3 ]let val = ;
Count
is a sequence constructor that builds a sequence that counts integers upward
Count
never terminates, so make sure to add a terminating sequence like a Slice
somewhere after it.
Kind: static property of sequences
Params
- start
number
- the number to start counting from
Sequence
sequences.Deduplicate ⇒ let Count = ; let Deduplicate = ; let Map = ; let Slice = ; let ToArray = ; // res is [0, 1, 2, 3]: let res = ;
Deduplicate
removes duplicates from a sequence, while maintaining sequence order
NOTE: Deduplicate
uses a Set to track already-seen elements,
so it can potentially use a large amount of memory
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - projection
function
- an optional projection function, that you can use to deduplicate based off some part of values
Sequence
sequences.Default ⇒ let Count = ; let Default = ; let Filter = ; let Slice = ; // res is [0, 10, 20, 30, 40]: let res = // filter out everything, so the sequence returns END ; // returns 0
Default
provides a default return value to the sequence, if the sequence terminates without returning any value
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - _default
function
- the default value
Sequence
sequences.Drain ⇒ let Count = ; let Drain = ; let Slice = ; // returns sequence terminator ;
Drain
is a sequence constructor wraps a source sequence, and when read is called it reads the entire sequence and throws it away.
Useful for sequences with side-effects.
Kind: static property of sequences
Params
- source
Sequence
- the source sequence to drain
Sequence
sequences.Each ⇒ let Count = ; let Drain = ; let Each = ; let Slice = ; // should log: // element 0 is 1 // element 1 is 2 // element 2 is 3 ;
Each
takes a function, and called it once per every element in a sequence.
Useful for logging, or performing other side-effects.
Kind: static property of sequences
Params
- source
Sequence
- the source sequence to drain - each
function
- a function to get called for each value
Sequence
sequences.Filter ⇒ let Count = ; let Filter = ; let Slice = ; let ToArray = ; // res is [0, 10, 20, 30, 40]: let res = ;
Filter
removes some items from a sequence.
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - filter
function
- a filter function
Sequence
sequences.Flatten ⇒ let From = ; let Flatten = ; let ToArray = ; // res is [1, 2, 3, 4, 5, 6]: let res = ;
Flatten
'flattens' a sequence of "collections" into a sequence of elements.
right now, Flatten
supports flattening sequences and array-like objects.
Anything else will be passed through without modification.
Kind: static property of sequences
Params
- source
Sequence
- a sequence of arrays
Sequence
sequences.FromArray ⇒ let FromArray = ; let ToArray = ; // res is [1, 2, 3]: let res = ;
FromArray
builds a sequence from an array.
Kind: static property of sequences
Params
- values
array
- values to return in the sequence, in order
Sequence
sequences.FromBlocks ⇒ let From = ; let FromBlocks = ; let ToArray = ; // res is [1, 2, 3, 4, 5, 6]: let res = ;
FromBlocks
'flattens' a sequence of arrays into a sequence of elements.
FromBlocks
is a legacy alias for Flatten
Kind: static property of sequences
Params
- source
Sequence
- a sequence of arrays
Sequence
sequences.FromIterator ⇒ FromIterator
builds a sequence from an iterator
Kind: static property of sequences
Params
- iterator
Iterator
- iterator to convert into a sequence
Sequence
sequences.From ⇒ let From = ; let ToArray = ; // res is [1, 2, 3]: let res = ;
From
builds a sequence from its arguments.
Kind: static property of sequences
Params
- ...values
*
- values to return in the sequence, in order
Sequence
sequences.FromObject ⇒ let FromObject = ; let ToArray = ; // res is [{ key: 'a', value: 1 }, { key: 'b', value: 2 }]: let res = ;
FromObject
builds a sequence of key-value pairs from an object.
Kind: static property of sequences
Params
- obj
object
- object from which to return a sequence of key-value pairs
Sequence
sequences.FromSet ⇒ FromSet
builds a sequence from a Set
Kind: static property of sequences
Params
- set
Set
- set to convert into a sequence
Sequence
sequences.Group ⇒ let From = ; let Group = ; let ToArray = ; // res is [ [1, 2, 3], [4, 5, 6] ]: let res = ;
Group
converts a sequence into a sequence of 'blocks' (fixed-size arrays of the elements)
Kind: static property of sequences
Params
- source
Sequence
- the source sequence - size
number
- the size of blocks to emit
Array
sequences.Join ⇒ let Join = ; let ToArray = ; // res is [ [1, 4], [1, 5], [1, 6], [2, 4], [2, 5], [2, 6], [3, 4], [3, 5], [3, 6] ]: let res = ;
Join
converts two arrays into a number (first array size * second array size) of pairs (arrays of two items)
Kind: static property of sequences
Params
- outerSource
Array
- first array - innerSource
Array
- second array
Sequence
sequences.Map ⇒ let Count = ; let Map = ; let Slice = ; let ToArray = ; // res is [1, 2, 3]: let res = ;
Map
transforms each element in a sequence.
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - map
function
- a map function
Sequence
sequences.Reduce ⇒ let Count = ; let Reduce = ; let Slice = ; // res is 6: let res = ;
Reduce
'reduces' a sequence of elements to a single result.
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - reduce
function
- a reduce function - state
*
- the initial value of the state
Sequence
sequences.Replace ⇒ let From = ; let Replace = ; let ToArray = ; // res is [1, 1, 2, 2, 3, 3]: let res = ;
Replace
allows you to replace some elements in a sequence dynamically.
It acts like a mapping with a pre-selector choosing which elements to map
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - selector
function
- the selector function, that chooses which elements to replace - mapper
function
- the mapper function, that replaces the elements
Sequence
sequences.Slice ⇒ let Count = ; let Slice = ; let ToArray = ; // res is [1, 2, 3]: let res = ;
Slice
'slices' out a piece of a sequence to use
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - start
integer
- the index to start from (inclusive) - end
integer
- the index to end at (exclusive)
Sequence
sequences.Sort ⇒ let From = ; let Sort = ; let ToArray = ; // res is [1, 2, 3]: let res = ;
Sort
sorts a sequence inline.
NOTE: Sort
must buffer all values in the sequence for sorting, so it has a space complexity of O(N)
Kind: static property of sequences
Params
- source
Sequence
- the source sequence
Sequence
sequences.Splice ⇒ let From = ; let Splice = ; let ToArray = ; // res is [1, 2, 3, 4, 5, 6]: let res = ;
Splice
'splices' several sequences together, concatenating them into a single sequence
Kind: static property of sequences
Params
- ...sources
Sequence
- the source sequences
Sequence
sequences.ToArray ⇒ let From = ; let ToArray = ; // res is [1, 2, 3]: let res = ;
ToArray
converts a sequence into an array.
NOTE: ToArray
will always return exactly once. If the source sequence is empty,
ToArray
will return an empty array.
Kind: static property of sequences
Params
- source
Sequence
- the source sequence
Sequence
sequences.ToBlocks ⇒ let From = ; let ToBlocks = ; let ToArray = ; // res is [ [1, 2, 3], [4, 5, 6] ]: let res = ;
ToBlocks
converts a sequence into a sequence of 'blocks' (fixed-size arrays of the elements)
ToBlocks
is a legacy alias for Group
Kind: static property of sequences
Params
- source
Sequence
- the source sequence - size
number
- the size of blocks to emit
Iterator
sequences.ToIterator ⇒ let From = ; let Map = ; let ToIterator = ; // res is [1, 2, 3]: let res = ; console; // { value: 2, done: false }
ToIterator
converts a sequence into an iterator, if you need one
Kind: static property of sequences
Params
- source
Sequence
- the source sequence
Sequence
sequences.ToObject ⇒ let From = ; let ToObject = ; // res is { a: 1, b: 2 }: let res = ;
ToObject
converts a sequence into an object
The sequence must be a sequence of key-value pairs,
structured as an object with a 'key' and a 'value' property.
NOTE: ToObject
will always return exactly once. If the source sequence is empty,
ToObject
will return an empty object.
Kind: static property of sequences
Params
- source
Sequence
- the source sequence
Sequence
sequences.ToSet ⇒ ToSet
converts a sequence into a Set
NOTE: ToSet
will always return exactly once. If the source sequence is empty,
ToSet
will return an empty Set.
Kind: static property of sequences
Params
- source
Sequence
- the source sequence
Sequence
sequences.Window ⇒ let From = ;let ToArray = ;let Window = ; let Number; // val is [ [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ] ]let val = ; // val2 is [ [ 1 ], [ 1, 2 ], [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ], [ 4, 5 ], [ 5 ] ]let val2 = ;
Window
is a sequence wrapper that returns a fixed-length sliding window of a source sequence
Kind: static property of sequences
Params
- source
Sequence
- a source sequence - size
number
- the size of the window buffer - edges
boolean
- allow edges (a not-full buffer)
sequences.Zip
let Zip = ; let From = ; let ToArray = ; // res is [ [1, 4], [2, 5], [3, 6] ]: let res = ; // Zip takes in sequences or arrays as sources // res is [ [1, 4], [2, 5], [3, 6] ]: let res = ; // the zipped sequence will be the length of the _longest_ source // if any source sequences end early, their result will be undefined // res is [ [1, 4], [2, 5], [undefined, 6] ]: let res = ; // if you need to clip your results to the shortest sequence, use Zip.Short // res is [ [1, 4], [2, 5] ]: let res = Zip ;
Zip
combines any number of arrays or sequences into a single sequence of tuples of elements at the same index
Kind: static property of sequences
object
sequences.bytes : Kind: static namespace of sequences
- .bytes :
object
- .FromHex ⇒
Sequence
- .FromWords ⇒
Sequence
- .ToHex ⇒
Sequence
- .ToWords ⇒
Sequence
- .FromHex ⇒
Sequence
bytes.FromHex ⇒ let FromHex = ;*
FromHex
converts a hex string into a Sequence of bytes
Kind: static property of bytes
Params
- hex
string
Sequence
bytes.FromWords ⇒ // res is [1, 2, 3, 4, 5, 6]: let res = ;
FromWords
'flattens' a sequence of words (32 bit integers) into a sequence of elements.
Kind: static property of bytes
Returns: Sequence
- - a sequence of bytes
Params
- source
Sequence
- a sequence of words - isLittleEndian
boolean
- an optional parameter to set the byte order, default true
Sequence
bytes.ToHex ⇒ // res is '000102': let res = ;
ToHex
converts a sequence into an array.
NOTE: ToHex
will always return exactly once. If the source sequence is empty,
ToHex
will return an empty string.
Kind: static property of bytes
Params
- source
Sequence
- the source sequence
Sequence
bytes.ToWords ⇒ // res is [1, 2, 3, 4, 5, 6]: let res = ;
ToWords
'flattens' a sequence of words (32 bit integers) into a sequence of elements.
Kind: static property of bytes
Returns: Sequence
- - a sequence of bytes
Params
- source
Sequence
- a sequence of words - isLittleEndian
boolean
- an optional parameter to set the byte order, default true
object
sequences.random : Kind: static namespace of sequences
- .random :
object
- .RandomBoolean ⇒
Sequence
- .RandomInteger ⇒
Sequence
- .Random ⇒
Sequence
- .RandomSelection ⇒
Sequence
- .XORShift32 ⇒
Sequence
- .RandomBoolean ⇒
Sequence
random.RandomBoolean ⇒ let RandomBoolean = ;*
RandomBoolean
is a Sequence pseudo-random number generator that returns a random boolean.
Kind: static property of random
Params
- seed
number
- an optional 32 bit seed
Sequence
random.RandomInteger ⇒ let RandomInteger = ;*
RandomInteger
is a Sequence pseudo-random number generator that returns a random int between min and max, inclusive.
RandomInteger returns in the range [0, 1] by default.
RandomInteger has 32 bits of precision.
Kind: static property of random
Params
- min
number
- the minimum possible integer to return - max
number
- the maximum possible integer to return - seed
number
- an optional 32 bit seed
Sequence
random.Random ⇒ let Random = ;*
Random
is a Sequence pseudo-random number generator that returns a random number between min and max, inclusive.
Random returns in the range [0, 1] by default.
Random has 32 bits of precision.
Kind: static property of random
Params
- min
number
- max
number
- seed
number
- an optional 32 bit seed
Sequence
random.RandomSelection ⇒ let RandomSelection = ;*
RandomSelection
is a Sequence generator that returns a random relection from the choices.
Kind: static property of random
Params
- choices
Array
- the selection choices - seed
number
- an optional 32 bit seed
Sequence
random.XORShift32 ⇒ let XORShift32 = ;*
XORShift32
is a Sequence implementation of the XORShift32 PRNG algorithm
Kind: static property of random
Params
- seed
number
- an optional 32 bit seed