Sequence utilities library#
Importing#
|#| 'stdsequtil.nest' = sequFunctions#
@all#
Synopsis:
[seq: Array|Vector] @all -> BoolReturns:
true if all the elements of seq are truthy.
@any#
Synopsis:
[seq: Array|Vector] @any -> BoolReturns:
true if at least one element in seq is truthy.
@copy#
Synopsis:
[cont: Array|Vector|Map] @copy -> Array|Vector|MapDescription:
Creates a shallow copy of a container.
Arguments:
cont: the container to copy
Returns:
A shallow copy of cont.
@count#
Synopsis:
[seq: Str|Array|Vector, object: Any] @count -> IntReturns:
The number of times object appears inside seq. When seq is a Str the
function returns the number of non-overlapping occurrences of object in the
string. If object is not a string and seq is 0 is returned.
@deep_copy#
Synopsis:
[cont: Array|Vector|Map] @copy -> Array|Vector|MapDescription:
Creates a deep copy of a container keeping recursive objects the same relative to each other.
Arguments:
cont: the container to copy
Returns:
A deep copy of cont.
Example:
|#| 'stdsequtil.nest' = sequ
|#| 'stdsys.nest' = sys
{null, {1, 2, 3}} = arr
arr = arr.0
arr @sequ.deep_copy = new_arr
>>> (new_arr new_arr.0 ==) -- true
>>> ((new_arr @sys.get_addr) (new_arr.0 @sys.get_addr) == '\n' ><) -- true
>>> ((arr @sys.get_addr) (new_arr.0 @sys.get_addr) == '\n' ><) -- false@empty#
Synopsis:
[vect: Vector] @empty -> VectorDescription:
Removes all objects from vect.
Returns:
vect.
@extend#
Synopsis:
[vect: Vector, seq: Vector|Array|Str|Iter] @extend -> VectorDescription:
Extends vect with all of the items inside seq.
Arguments:
vect: the vector to extendseq: the sequence containing the items to extend the vector with
Returns:
The extended vector, the same object as vect.
@filter#
Synopsis:
[seq: Array|Vector, func: Func] @filter -> Array|VectorDescription:
Creates a new sequence of the same type of seq that has all the elements from
seq which, when passed as an argument to func, returned a truthy value.
func must take exactly one argument.
Returns:
A new sequence of type ?::seq that contains the filtered elements.
@filter_i#
Synopsis:
[seq: Array|Vector|Str|Iter, func: Func] @filter -> IterDescription:
Works like filter but an iterator is
created instead of a new sequence.
Returns:
The newly created iterator.
@insert_at#
Synopsis:
[vect: Vector, index: Int, object: Any] @insert_at -> nullDescription:
Inserts object at index in vect moving all following objects by one spot.
Negative indices are allowed. If index falls outside the boundaries of vect
an error is thrown.
Arguments.
vect: the vector to insert the object intoindex: the index where to insert the objectobject: the object to insert
Example:
|#| 'stdsequtil.nest' = sequ
<{1, 2, 3, 5}> = vec
vec 4 -1 @sequ.insert_at
>>> (vec '\n' ><) --> <{1, 2, 3, 4, 5}>@lscan#
Synopsis:
[seq: Array|Vector|Str, func: Func, start_val: Any, max_items: Int?] @lscan -> Array|VectorDescription:
Creates a new sequence where each element is the result of passing the previous
object and the current object through func. For the first object start_val
is used.
The operation happens from the start to the end of the sequence.
func must take exactly two arguments where the first is the previous value and
the second the current one.
{x1, x2, ...} f s @lscan == {s, s x1 @f, (s x1 @f) x2 @f, ...}Arguments:
seq: the sequence to scanfunc: the function to scan the sequence withstart_val: the value that is passed to the sequence along the fist objectmax_items: the maximum number of items in the end sequence
Returns:
The scanned sequence that includes start_val.
Example:
|#| 'stdsequtil.nest' = sequ
{1, 2, 3, 4} (##a b => a b +) 0 @sequ.lscan --> {0, 1, 3, 6, 10}
'hello' (##a b => a b ><) '' 4 @sequ.lscan --> {'', 'h', 'he', 'hel'}@map#
Synopsis:
[seq: Array|Vector, func: Func, in_place: Bool?] @map -> Array|VectorDescription:
Maps all the objects in seq to new ones generated by passing the original
object through func and using the return value as the mapped object. func
must take exactly one argument otherwise an error is thrown.
If in_place is omitted or is false the objects are inserted in the new
sequence otherwise seq is modified in-place.
Arguments:
seq: the sequence containing the items to be mappedfunc: the function used to map each objectin_place: whether the function should modify the sequence in-place or create another one
Returns:
A sequence containing the mapped items.
Example:
|#| 'stdsequtil.nest' = sequ
{1, 2, 3, 4} = arr
arr (##n => n n *) @sequ.map = squares
>>> (squares '\n' ><) --> {1, 4, 8, 16}@map_i#
Synopsis:
[seq: Array|Vector|Str|Iter, func: Func] @map_i -> IterDescription:
Creates an iterator which maps all the values in seq by passing them to
func. func must take exactly one argument.
Arguments:
seq: the sequence containing the items to be mappedfunc: the function used to map each object
Returns:
A new iterator object.
@merge#
Synopsis:
[seq1: Array|Vector, seq2: Array|Vector] @merge -> Array|VectorDescription:
Creates a new sequence that merges the two sequences together, one after the other.
Returns:
A new sequence of type Array if both seq1 and seq2 are arrays and
Vector otherwise, containing all the elements inside seq1 followed by the
elements inside seq2.
@remove_at#
Synopsis:
[vect: Vector, index: Int] @remove_at -> AnyDescription:
Removes the element at index in vect by moving all following elements one
spot back.
Returns:
The removed element.
@rscan#
Synopsis:
[seq: Array|Vector|Str, func: Func, start_val: Any, max_items: Int?] @lscan -> Array|VectorDescription:
Creates a new sequence where each element is the result of passing the previous
object and the current object through func. For the first object start_val
is used.
The operation happens from the end to the start of the sequence.
func must take exactly two arguments.
Note
The arguments passed to func are reversed compared to lscan.
Arguments:
seq: the sequence to scanfunc: the function to scan the sequence withstart_val: the value that is passed to the sequence along the fist objectmax_items: the maximum number of items in the end sequence
Returns:
The scanned sequence that includes start_val.
Example:
|#| 'stdsequtil.nest' = sequ
{1, 2, 3, 4} (##a b => a b +) 0 @sequ.rscan --> {10, 9, 7, 4, 0}
'hello' (##a b => a b ><) '' 4 @sequ.rscan --> {'llo', 'lo', 'o', ''}@slice#
Synopsis:
[seq: Str|Array|Vector, start: Int?, stop: Int?, step: Int?] @slice -> Str|Array|VectorDescription:
Creates a new sequence of type ?::seq that contains the elements from start
to stop separated by a gap of step. Negative indices are allowed for
start and stop. stop is excluded while start is included. A negative
step is allowed. start and stop are clamped inside the boundaries of
seq.
start, if set to null, defaults to the start of the sequence when the step
is positive and to the end when it is negative.
stop, if set to null, defaults to the end of the sequence when the step is
positive and to the start when it is negative.
step, if set to null, defaults to 1.
Arguments:
seq: the sequence to take a slice ofstart: the starting index of the slicestop: the end index of the slicestep: the step between elements of the slice
Returns:
The function returns the slice of the sequence.
Example:
|#| 'stdsequtil.nest' = sequ
'Hello' null null -1 @sequ.slice --> 'olleH'
{1, 2, 3, 4} 10 1 @sequ.slice --> {,}
<{'a', 'b', 'c', 'd', 'e'}> 0 null 2 @sequ.slice --> <{'a', 'c', 'e'}>@slice_i#
Synopsis:
[seq: Str|Array|Vector, start: Int?, stop: Int?, step: Int?] @slice_i -> IterDescription:
Works exactly like slice but instead
of creating a new sequence an iterator is created.
Returns:
The new iterator.
@sort#
Synopsis:
[seq: Array|Vector, mapping_func: Func?, new_seq: Bool?] @sort -> Array|VectorDescription:
Sorts seq in increasing order. When mapping_func is not null it is
used to map the objects of seq to keys used in the comparisons, the original
objects are sorted according to the value of the corresponding key.
mapping_func must take exactly one argument.
If new_seq is not given or false, seq is sorted in-place otherwise a new,
sorted sequence is created.
Returns:
The sorted sequence which is seq if new_seq is false.