API
Basic iteration routines
iterate-for-effects(iterator function)Extract a value from
iterator and call function with that
value. Repeat until the next state is stop and return no values.do-iterator((val iterator) &body body)Execute
body for each value from iterator. The value is
bound to val. This is equal to the following code:(iterate-for-effects
iterator
(lambda (val) ...))
collect(iterator)Collect all values from an iterator into a list. This is the
inverse of
list->iterator.length(iterator)Return a number of elements in the iterator
consume-one(iterator &optional default)Get exactly one value from iterator and return this value and a
new iterator without this value. If the iterator does not contain
values, return default. Useful when we need to get the first value
which satisfies some condition:
(consume-one
(drop-while
#'oddp
(list->iterator '(1 3 5 7 2 3 5))))
;; => 2, (ITERATOR #<FUNCTION STATELESS-ITERATORS::LIST->ITERATOR/NEXT> (3 5)), T
The third value is a boolean which indicates if the returned value is not default.
nth(n iterator)Get n-th value from an iterator.
(nth 4 (count-from 0))
;; => 5, (STATELESS-ITERATORS:ITERATOR #<FUNCTION STATELESS-ITERATORS::COUNT-FROM/NEXT> 6)
Available iterators
+empty+An empty iterator.
singleton(value)Return an iterator containing only one specified value
list->iterator(list)Convert a list to an iterator. This is the inverse of
collect.vector->iterator(vector)Convert a vector to an iterator.
take(n iterator)Create an iterator which takes
n values from iterator and
stops.(collect (take 3 (list->iterator '(1 2 3 4)))) -> '(1 2 3)
(collect (take 3 (list->iterator '(1)))) -> '(1)
iterate(function x)Create an infinite iterator whose values are
x, f(x),
f(f(x)) and so on.(collect (take 3 (iterate (lambda (x)(/ x 2)) 1))) -> '(1 1/2 1/4)
unfold(function x)When an element is forced from this iterator, it calls a function
function with the current state and uses the first returned value
as the element and the second value as a next state. x is an
initial state for iteration. A generation of new values can be stopped
if the symbol stop is the second returned value from function.
These two calls are equivalent:
(iterate fn x)
(unfold (lambda (state)(values state (funcall fn state))) x)
Example:
(collect
(unfold
(lambda (state)
(values
(* state 2)
(if (< state 5)(1+ state) 'stop)))
1)) -> '(2 4 6 8)
count-from(n)An infinite counting iterator which starts from
n and
increments each next value by 1.(collect (take 4 (count-from 1))) -> '(1 2 3 4)
range(from to &optional (step 1))Create an iterator which counts from
from to to(excluding
to) stepping by step.(collect (range 1 8 2)) -> '(1 3 5 7)
take-while(predicate iterator)Create an iterator which returns values from
iterator while
predicate is true.(collect (take-while #'oddp (list->iterator '(1 3 8 2 5)))) -> '(1 3)
drop-while(predicate iterator)Create an iterator which has the same values as in
iterator
but drops initial values which satisfy the predicate.(collect (drop-while #'oddp (list->iterator '(1 3 8 2 5)))) -> '(8 2 5)
imap(function &rest iterators)Create an iterator which applies
function to values of
iterators. This iterator stops when at least one of iterators stops.(collect (imap #'+ (list->iterator '(1 3 8 2))(count-from 0))) -> '(1 4 10 5)
zip(iter1 iter2)Create an iterator which returns consed pairs of values of
iter1 and iter2.(collect (take 3 (zip (count-from 1)(count-from 2)))) -> '((1 . 2)(2 . 3)(3 . 4))
zip*(&rest iterators)Create an iterator which returns lists of values from
iterators.(collect
(take 3 (zip* (count-from 1)
(count-from 2)
(count-from 3)))) -> '((1 2 3)(2 3 4)(3 4 5))
repeat(value)Create an iterator which repeats
value infinitely.replicate(value n)Create an iterator which repeats
valuen times.(replicate x n) = (take n (repeat x))
foldl(function init iterator)Left-associative fold for iterators. The returned value is the same
as for the following, but without consing:
(reduce function (collect iterator) :initial-value init)
foldr(function init iterator)Right-associative fold for iterators. The returned value is the same
as for the following, but maybe more effective:
(reduce function (collect iterator) :initial-value init :from-end t)
cycle(iterator)Repeat values of
iterator infinitely.(collect (take 5 (cycle (list->iterator '(1 2 3))))) -> '(1 2 3 1 2)
concat(&rest iterators)Concatenate one or more iterators into one iterator.
(collect (concat (replicate 3 2)(replicate 1 3))) -> '(3 3 1 1 1)
product(outer inner)Create an iterator which has all possible pairs
(x . y) where
x ∈ outer and y ∈ inner.(collect (product (range 1 3)(range 3 5))) -> '((1 . 3)(1 . 4)(2 . 3)(2 . 4))
filter(predicate iterator)Create an iterator which returns only those values of
iterator
which satisfy predicate.(collect (take 6 (filter #'oddp (count-from 0)))) -> '(1 3 5 7 9 11)
power(iterator n)For an iterator which contains a set of elements \(A\), return an
iterator which contains all elements of \(A^n\).
(collect (power (list->iterator '(-1 0 1)) 2)) ->
'((-1 -1)(-1 0)(-1 1)(0 -1)(0 0)(0 1)(1 -1)(1 0)(1 1))
indices(dimensions)For a list of array dimensions, return an iterator which iterates
through all possible indices in the array.
(collect (indices '(3 4 2))) ->
'((0 0 0)(0 0 1)(0 1 0)(0 1 1)(0 2 0)(0 2 1)(0 3 0)(0 3 1)(1 0 0)
(1 0 1)(1 1 0)(1 1 1)(1 2 0)(1 2 1)(1 3 0)(1 3 1)(2 0 0)(2 0 1)
(2 1 0)(2 1 1)(2 2 0)(2 2 1)(2 3 0)(2 3 1))
every(predicate iterator)Return
t if predicate is true for every element contained
in the iterator and nil otherwise.some(predicate iterator)Return
t if predicate is true for at least one element
contained in the iterator and nil otherwise.undefined-valueA condition signalled by
undefined.stringAdditional clarification of what happenedOption Value Allocation: instance Type: nilInitarg: :stringReaders: (undefined-value-string)
undefined(string)When a value is forced out of this iterator, a condition of type
undefined-value is signalled with a supplied text.