Iterator utilities library#
Importing#
|#| 'stditutil.nest' = itu
Functions#
@chain
#
Synopsis:
[sequence: Iter|Array|Vector|Str] @chain -> Iter
Returns:
An iterator that chains the objects inside of the elements inside of the sequence.
Example:
|#| 'stditutil.nest' = itu
{'Hi!', 1 -> 4} @itu.chain --> 'H', 'i', '!', 1, 2, 3
'Hi!' @itu.chain --> 'H', 'i', '!' this is the same as {'H', 'i', '!'} @itu.chain
'Hi!' @itu.enumerate @itu.chain --> 0, 'H', 1, 'i', 2, '!'
@count
#
Synopsis:
[start: Int, step: Int?] @count -> Iter
Returns:
An iterator that counts indefinitely from start
, advancing by step
. If
step
is null
it defaults to 0
.
Example:
|#| 'stditutil.nest' = itu
0 2 @itu.count --> 0, 2, 4, 6, 8, ...
@cycle
#
Synopsis:
[sequence: Str|Array|Vector|Iter] @cycle -> Iter
Returns:
An iterator that cycles through the elements of the given object restarting from the first when the sequence ends.
Example:
|#| 'stditutil.nest' = itu
'Hi!' @itu.cycle --> 'H', 'i', '!', 'H', 'i', ...
@enumerate
#
Synopsis:
[iterator: Str|Array|Vector|Iter, start: Int?, step: Int?, invert_order: Bool?] @enumerate -> Iter
Arguments:
iterator
: the iterator to enumeratestart
: the starting number for the numeration, the function will still start from the first elementstep
the step of the enumeration, the function will still step through all the elements
Returns:
An iterator that returns a 2-element array where the first element is the
object returned by the iterator
and the second is the index of the current
iteration. When invert_order
is set to a truthy value the first element is
the object and the second the iteration count.
start
by default is set to 0
and step
to 1
but this behaviour can be
changed by passing the additional arguments.
Example:
|#| 'stditutil.nest' = itu
'Hi!' @itu.enumerate --> {0, 'H'}, {1, 'i'}, {2, '!'}
'Hi!' 5 -1 @itu.enumerate --> {5, 'H'}, {4, 'i'}, {3, '!'}
'Hi!' @itu.reversed @itu.enumerate --> {0, '!'}, {1, 'i'}, {2, 'H'}
'Hi!' 0 1 true @itu.enumerate --> {'H', 0}, {'i', 1}, {'!', 2}
@iter_is_done
#
Synopsis:
[iter: Iter] @iter_is_done
Description:
Calls the _is_done_
function of an iterator.
@iter_get_val
#
Synopsis:
[iter: Iter] @iter_get_val
Description:
Calls the get_val
function of
an iterator.
@iter_start
#
Synopsis:
[iter: Iter] @iter_start
Description:
Calls the start
function of an
iterator.
@keys
#
Synopsis:
[map: Map] @keys -> Iter
Returns:
An iterator which goes through all the keys in a map.
Example:
|#| 'stditutil.nest' = itu
{'key_1': 1, 'key_2': 2} @itu.keys --> 'key_1', 'key_2'
{'key_2': 2, 'key_1': 1} @itu.keys --> 'key_2', 'key_1'
@new_iterator
#
Synopsis:
[start: Func, get_val: Func, data: Any] @new_iterator -> Iter
Description:
Creates a new iterator object that uses custom functions. Any of the given
functions must take exactly one parameter that will be data
.
start
should initialize data to start the iterator and is always called
before iterating.
get_val
should return the current value of the iterator. To signal that the
iterator has ended this function should return
IEND
. If it may return
IEND
before reaching the actual end, it
should be replaced by null
.
Arguments:
start
: the function called when the iterator is startedis_done
: the function called before any iteration to check if it has endedget_val
: the function called to get the value of each iterationdata
: the object passed to the functions when they get called
Returns:
The new custom iterator.
@repeat
#
Synopsis:
[object: Any, times: Int] @repeat -> Iter
Returns:
An iterator that repeats object
the number of times specified by times
.
Example:
|#| 'stditutil.nest' = itu
'Hi!' 3 @itu.repeat --> 'Hi!', 'Hi!', 'Hi!'
@reversed
#
Synopsis:
[sequence: Str|Array|Vector] @reversed -> Iter
Returns:
An iterator which goes through the elements of a sequence in reverse order, from the last to the first.
Example:
|#| 'stditutil.nest' = itu
'Hi!' @itu.reversed --> '!', 'i', 'H'
@values
#
Synopsis:
[map: Map] @values -> Iter
Returns:
An iterator which goes through all the keys in a map.
Example:
|#| 'stditutil.nest' = itu
{'key_1': 1, 'key_2': 2} @itu.values --> 1, 2
{'key_2': 2, 'key_1': 1} @itu.values --> 2, 1
@zip
#
Synopsis:
[seq_1: Array|Vector|Str|Iter, seq_2: Array|Vector|Str|Iter] @zip -> Iter
[seq: Array|Vector.Array|Vector|Str|Iter] @zip -> Iter
Returns:
The first kind of this function accepts two arguments and returns an iterator
that zips them together pairing the objects of seq_1
with the objects of
seq_2
at the same index and that ends when the shortest of the two sequences
ends.
The second kind only accepts the first argument (the second must be null
since there are no actual overloads in Nest) and returns an iterator that
zips together all the sequences inside seq
putting all the arguments with the
same index in an array. The iterator ends when the shortest of all the
sequences has ended.
Example:
|#| 'stditutil.nest' = itu
'Hi!' {1, 2, 3} @itu.zip --> {'H', 1}, {'i', 2}, {'i', 3}
{'Hi!', 1 -> 3, <{9, 8, 7, 6}>} @itu.zip --> {'H', 1, 9}, {'i', 2, 8}
Constants#
IEND
#
This is the value returned by an iterator that signals its end.