Next: , Previous: Numerical Iteration, Up: Drivers

2.1.2 Sequence Iteration

There are a number of clauses for iterating over sequences. In all of them, the argument following for may be a list instead of a symbol, in which case destructuring is performed. See Destructuring.

— Clause: for var in list &optional by step-function

var is set to successive elements of list. step-function, which defaults to cdr, is used to obtain the next sublist.

— Clause: for var on list &optional by step-function

var is set to successive sublists of list. step-function (default cdr) is used as in for... in.

These two clauses use atom to test for the end of a list. Hence, given a list whose final cdr is not nil, they will silently ignore the last cdr. Other choices are endp, which would signal an error, and null, which would probably result in an error somewhere else. If you wish to use an end-test other than atom, set the variable iterate::*list-end-test* to the name of the desired function.

— Clause: for var in-vector vector &sequence

var takes on successive elements from vector. The vector's fill-pointer is observed. Here and in subsequent clauses, the &sequence keywords include with-index, which takes a symbol as argument and uses it for the index variable instead of an internally generated symbol. The other &sequence keywords behave as in numerical iteration, except that the default iteration bounds are the bounds of the vector. E.g. in (for i in-vector v downto 3), i will start off being bound to the last element in v, and will be set to preceding elements down to and including the element with index 3.

— Clause: for var in-sequence seq &sequence

This uses Common Lisp's generalized sequence functions, elt and length, to obtain elements and determine the length of seq. Hence it will work for any sequence, including lists, and will observe the fill-pointers of vectors.

— Clause: for var in-string string &sequence

var is set to successive characters of string.

— Clause: for var index-of-vector vector &sequence
— Clause: for var index-of-sequence sequence &sequence
— Clause: for var index-of-string string &sequence

var is set to successive indices of the sequence. These clauses avoid the overhead of accessing the sequence elements for those applications where they do not need to be examined, or are examined rarely. They admit all the optional keywords of the other sequence drivers except the (redundant) with-index keyword.

— Clause: for (key value) in-hashtable table

key and value, which must appear as shown in a list and may be destructuring templates, are set to the keys and values of table. If key is nil, then the hashtable's keys will be ignored; similarly for value. The order in which elements of table will be retrieved is unpredictable.

— Clause: for var in-package package &optional external-only ext

Iterates over all the symbols in package, or over only the external symbols if ext is specified and non-nil. ext is not evaluated. The same symbol may appear more than once.

— Clause: for var in-packages &optional having-access symbol-types

Iterates over all the symbols from the list of packages denoted by the descriptor packages and having accessibility (or visibility) given by symbol-types. This defaults to the list (:external :internal :inherited) and is not evaluated. var must be a list of up to three variables: in each iteration, these will be set to a symbol, its access-type and package (as per with-package-iterator in ANSI CL). The same symbol may appear more than once.

— Clause: for var in-file name &optional using reader

Opens the file name (which may be a string or pathname) for input, and iterates over its contents. reader defaults to read, so by default var will be bound to the successive forms in the file. The iterate body is wrapped in an unwind-protect to ensure that the file is closed no matter how the iterate is exited.

— Clause: for var in-stream stream &optional using reader

Like for... in-file, except that stream should be an existing stream object that supports input operations.