This is the picl Reference Manual, version 1.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Jul 15 06:15:15 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
piclPython Itertools in Common Lisp
Anish Moorthy <anlsh@protonmail.com>
MIT
1.0.1
defclass-std (system).
alexandria (system).
src (module).
Modules are listed depth-first from the system components tree.
picl/srcpicl (system).
package.lisp (file).
interface.lisp (file).
default-iterators.lisp (file).
utils.lisp (file).
itertools.lisp (file).
combinatoric.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
picl/picl.asdpicl/src/package.lisppicl/src/interface.lisppicl/src/default-iterators.lisppicl/src/utils.lisppicl/src/itertools.lisppicl/src/combinatoric.lisppicl/src/interface.lisppackage.lisp (file).
src (module).
make-iterator (generic function).
next (function).
def-iter (macro).
picl/src/default-iterators.lispinterface.lisp (file).
src (module).
make-iterator (method).
make-iterator (method).
picl/src/utils.lispinterface.lisp (file).
src (module).
always (function).
apply (function).
empty-iterator (function).
iter-to-list (function).
iter-to-vec (function).
never (function).
take (function).
picl/src/itertools.lisputils.lisp (file).
src (module).
chain (function).
chain-from-iter (function).
compress (function).
count (function).
cycle (function).
dropwhile (function).
enumerate (function).
filter (function).
filterfalse (function).
islice (function).
map (function).
range (function).
repeat (function).
starmap (function).
takewhile (function).
tee (function).
zip (function).
zip-longest (function).
tee-item (function).
zip-from-itl (function).
zip-longest-from-itl (function).
picl/src/combinatoric.lisputils.lisp (file).
src (module).
combinations (function).
combinations-with-rep (function).
nfold-product (function).
permutations (function).
product (function).
Packages are listed by definition order.
piclcommon-lisp.
always (function).
apply (function).
chain (function).
chain-from-iter (function).
combinations (function).
combinations-with-rep (function).
compress (function).
count (function).
cycle (function).
dropwhile (function).
empty-iterator (function).
enumerate (function).
filter (function).
filterfalse (function).
islice (function).
iter-to-list (function).
iter-to-vec (function).
make-iterator (generic function).
map (function).
never (function).
next (function).
nfold-product (function).
permutations (function).
product (function).
range (function).
repeat (function).
starmap (function).
take (function).
takewhile (function).
tee (function).
zip (function).
zip-longest (function).
def-iter (macro).
tee-item (function).
zip-from-itl (function).
zip-longest-from-itl (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Truthy iff every element of the argument is truthy
“‘
(always ’(1 2 3))
;; t
(always ’(nil))
;; nil
(always nil)
t
“‘
picl.
Like regular apply, except that the final argument can be an arbitrary
iterable.
“‘
(picl:apply #’+ 1 #(2 3))
;; 6
“‘
picl.
Yields the elements of the first iterable in ‘iterable‘, then the second, etc.
“‘
(chain ’(1 2 3) ’(4 5 6) (count 7))
;; 1, 2, 3, 4, 5, 6, 7 etc
“‘
picl.
Yields the elements of the first iterable in ‘iterable‘, then the second, etc.
Equivalent to python’s chain.from_iterable(), and conceptually equivalent to
‘(picl:apply #’picl:chain iterable-of-iterables)‘.
“‘
(chain-from-iter (picl:map (lambda (x) (picl:range x))) (picl:count))
;; 0, 0, 1, 0, 1, 2, 0, 1, 2, 3, etc
“‘
picl.
r-combinations of input iterable, returned as vectors in lexicographic order.
“‘
(combinations 2 ’(1 2 3))
;; #(1 2), #(1 3), #(2 3)
“‘
picl.
r-combinations with replacement of input iterable, returned as vectors in lexicographic
order
“‘
(combinations 2 ’(1 2 3))
;; #(1 1), #(1 2), #(1 3), #(2 1), #(2 2), #(2 3), #(3 1), #(3 2), #(3 3)
“‘
picl.
Yields elements of ‘base-iterable‘ while the corresponding element in ‘bool-iterable‘
is truthy.
Stops when either of its arguments is consumed
“‘
(iterator-compress (count) (t nil t nil t nil))
;; 0 2 4
“‘
picl.
Yields the elements ‘start, start + 1*step, start + 2*step, etc
“‘
(count 2 4)
;; 2, 6, 10, 14, etc
“‘
picl.
Continually yields the elements of its argument in order, starting over when the end is
reached
If the base iterator is empty, the result of iterator-cycle will be too
“‘
(cycle ’(1 2 3 4))
;; 1, 2, 3, 4, 1, 2, 3, 4, etc
(iter-to-list (cycle ’()))
;; nil
“‘
picl.
Drops all elements of ‘base-iter‘ until ‘pred‘ first returns false, then yields all further
elements
“‘
(dropwhile (lambda (x) (< 3 x) (count)))
;; 3, 4, 5, etc
“‘
picl.
Returns an empty iterator
“‘
(iter-to-list (empty-iterator))
;; nil
“‘
picl.
Yield two-element lists of indices (beginning at curr) and their corresponding elements in
‘iterable‘
“‘
(enumerate ’(a b c d))
;; (0 a), (1 b), (2 c), (3 d)
(enumerate ’(a b c d) 3)
;; (3 a), (4 b), (5 c), (6 d)
“‘
picl.
Yields elements of ‘iterable‘ for which ‘predicate‘ returns true
“‘
(filter (lambda (x) (evenp x) (count)))
;; 0, 2, 4, etc
“‘
picl.
Yields elements of ‘iterable‘ for which ‘predicate‘ returns false
“‘
(filterfalse (lambda (x) (evenp x) (count)))
;; 1, 3, 5, etc
“‘
picl.
Works like Python’s [islice](https://docs.python.org/3.8/library/itertools.html#itertools.islice)
picl.
Reads ‘iterable‘ into a list
“‘
(iter-to-list (range 4))
;; (0 1 2 3)
(iter-to-list (count))
;; Out of memory error!
“‘
picl.
Reads ‘iterable‘ into a vector
“‘
(iter-to-list (range 4))
;; #(0 1 2 3)
(iter-to-list (count))
;; Out of memory error!
“‘
picl.
Applies ‘fn‘ to the first elements of each iterable in ‘iterables‘, then to the seconds, etc
“‘
(map #’+ ’(1 2) ’(3 4))
;; 4, 6
“‘
picl.
Truthy iff every element of the argument is nil
“‘
(never ’(1 2 3))
;; nil
(never ’(nil))
;; t
(never nil)
t
“‘
picl.
Produces two values, the payload and the alive-indicator
While iterator is not yet exhausted, calling next will yield its next item and a
truthy alive-indicator
After iterator has been exhausted all further calls should yield an alive-indicator of nil, and the payload should be ignored by the callee
picl.
Computes the n-fold Cartesian product of an iterable with itself.
Essentially equivalent to ‘(apply #’product (iter-to-list (tee n iterable))‘, but with
much better memory usage
“‘
(nfold-product 3 ’(1 2))
;; #(1 1 1), #(1 1 2), #(1 2 1), #(1 2 2), #(2 1 1), #(2 1 2), #(2 2 1), #(2 2 2)
“‘
picl.
‘r‘-permutations of input iterable, returned as vectors in lexicographic order.
When a single argument is given, it should be an iterable and ‘r‘ will default to its length.
When two arguments are given, the first corresponds to ‘r‘ and the second to the iterable
“‘
(permutations ’(1 2 3))
;; #(1 2 3), #(1 3 2), #(2 1 3), #(2 3 1), #(3 1 2), #(3 2 1)
(permutations 2 ’(1 2 3))
;; #(1 2), #(1 3), #(2 1), #(2 3), #(3 1), #(3 2)
“‘
picl.
Cartesian product of input iterables, returned as vectors in lexicographic order.
Due to the awkwardness in mixing ‘&rest‘ and ‘&key‘ parameters in lambda lists, this function
does not implement the ‘repeat‘ argument supported in
[Python’s version](https://docs.python.org/3/library/itertools.html#itertools.product).
Use ‘picl:nfold-product‘ instead.
“‘
(product ’(1 2) ’(3 4))
;; #(1 3), #(1 4), #(2 3), #(2 4)
“‘
picl.
Works [as in Python](https://docs.python.org/3/library/stdtypes.html#typesseq-range) but produces an iterator (as defined by PICL) instead of a Python-esque range object
“‘
(range 5)
;; 0, 1, 2, 3, 4
(range 2 5)
;; 2, 3, 4
(range -2)
;; 0, -1
(range 1 7 2)
;; 1, 3, 5
“‘
picl.
If a single argument is given, yields ‘s0‘ repeatedly forever
If two arguments are given, then yields ‘s1‘ ‘s0‘ times
“‘
(repeat t)
;; t, t, etc
(repeat 4 t)
;; t, t, t, t
“‘
picl.
Applies ‘fn‘ to the first argument of ‘iterable-of-iterables‘, then the second, etc
“‘
(starmap #’+ ’(1 2) ’(3 4))
;; 3, 7
“‘
picl.
Returns a list consisting of the first ‘n‘ (or fewer, if the iterator runs out) items of iterable
“‘
(take 5 (count))
;; (0 1 2 3 4)
take 30 (range 4)
;; (0 1 2 3)
“‘
picl.
Yields elements of ‘iterable‘ for which ‘predicate‘ is truthy, terminating once it
first returns nil
“‘
(takewhile (lambda (x) (< 3 x) (count)))
;; 0, 1, 2
“‘
picl.
Returns a vector of ‘n‘ independent copies of ‘iterable‘. ‘iterable‘ itself should not be used
after it has been passed to ‘tee‘, otherwise the tees will not be properly updated
If the base iterable is large be careful not to advance any copy too far ahead of the others,
so as to avoid memory issues
“‘
tees = (tee 2 ’(1 2 3 4))
;; tees[0] => 1, 2, 3, 4
;; tees[1] => 1, 2, 3, 4
“‘
picl.
Returns vectors consisting of the first elements from each iterable in ‘iterable‘, then the
second, etc until one is consumed
“‘
(zip ’(1 2 3) ’(a b c d))
;; #(1 a). #(2 b), #(3 c)
“‘
picl.
Returns vectors consisting of the first elements from each iterable in ‘iterable‘, then the
second, etc until *all* are consumed. Once a constituent iterable has been exhausted,
‘fill-value‘ is used to pad the vector in its place.
“‘
(zip nil ’(1 2 3) ’(a b c d))
;; #(1 a). #(2 b), #(3 c), #(nil d)
“‘
picl.
Creates an iterator from ‘iterable‘: an iterator is simply anything which can be passed as an argument to ‘next‘
picl.
vector)) ¶Returns an iterator which traverses elements of a vector in sequential order
list)) ¶Returns an iterator which traverses elements of a list in sequential order
function)) ¶An anaphoric convenience macro which can be re-implemented to change how iterators are
structured. Exposes the local ‘init-state‘ macro within ‘constructor-body‘
If you don’t want to-use this macro (which I totally understand) just write constructors for your
iterators returning 0-argument closures representing the ‘next‘ function and you’ll be fine. This
macro just helped me get through a lot of waffling during development
Parameters
———-
‘name‘ is a synbol naming the iterator’s backing state. However it’s actually
ignored, since PICL doesn’t currently expose iterators’ backing state
‘state-vars‘ is a list of symbols naming the iterator’s state variables.
The ‘constructor-name/params/body‘ will be ‘defun‘’d to create the user-facing constructor
function. In ‘constructor-body‘, the return value should be an iterator or a call to local
‘init-state‘ macro
‘next-body‘ The definition of the ‘next‘ function for this iterator, which will be run in a
lexical environment consisting of the state vars
Both ‘constructor-body‘ and ‘next-body‘ are defined in the lexical environment of the ‘def-iter‘
form, and as such can access any lexical bindings not shadowed by the ‘constructor-params‘ and
‘state-vars‘ respectively
The local ‘init-state‘ macro.
—————————-
The arguments to ‘init-state‘ should be of the form ‘(statevar-symbol value-form)‘or
‘statevar-symbol‘. In the first case, the value of ‘value-form‘ will be used to initialize the
state variable named by ‘symbol‘. In the second case, ‘statevar-symbol‘ is also used as the
corresponding ‘value-form‘
Example
——-
What follows is a sample implementation of the ‘count‘ iterator using this macro
“‘
(def-iter ignored-backing-name (curr-val step)
(count (start step)
(init-state (curr-val start) step))
(prog1 curr-val (incf curr-val step))))
““
picl.
Function had no docstring, so this one was inserted
picl.
Function had no docstring, so this one was inserted
picl.
Function had no docstring, so this one was inserted
picl.
| Jump to: | A C D E F G I M N P R S T Z |
|---|
| Jump to: | A C D E F G I M N P R S T Z |
|---|
| Jump to: | C D F I M P S U |
|---|
| Jump to: | C D F I M P S U |
|---|