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.