Common Lisp the Language, 2nd Edition

Next: End-Test Control Up: Loop Previous: Loop Constructs

# 26.6. Iteration Control

Iteration control clauses allow you to direct loop iteration. The loop keywords `as`, `for`, and `repeat` designate iteration control clauses.

Iteration control clauses differ with respect to the specification of termination conditions and the initialization and stepping of loop variables. Iteration clauses by themselves do not cause the Loop Facility to return values, but they can be used in conjunction with value-accumulation clauses to return values (see section 26.8).

All variables are initialized in the loop prologue. The scope of the variable binding is lexical unless it is proclaimed special; thus, the variable can be accessed only by expressions that lie textually within the loop. Stepping assignments are made in the loop body before any other expressions are evaluated in the body.

The variable argument in iteration control clauses can be a destructuring list. A destructuring list is a tree whose non-null atoms are symbols that can be assigned a value (see section 26.12.2).

The iteration control clauses `for`, `as`, and `repeat` must precede any other loop clauses except `initially`, `with`, and `named`, since they establish variable bindings. When iteration control clauses are used in a loop, termination tests in the loop body are evaluated before any other loop body code is executed.

If you use multiple iteration clauses to control iteration, variable initialization and stepping occur sequentially by default. You can use the `and` construct to connect two or more iteration clauses when sequential binding and stepping are not necessary. The iteration behavior of clauses joined by `and` is analogous to the behavior of the Common Lisp macro `do` relative to `do*`.

[X3J13 voted in March 1989 (LOOP-AND-DISCREPANCY) to correct a minor inconsistency in the original syntactic specification for `loop`. Only `for` and `as` clauses (not `repeat` clauses) may be joined by the `and` construct. The precise syntax is as follows.

    for-as ::= {for | as} for-as-subclause {and for-as-subclause}*
    for-as-subclause ::= for-as-arithmetic | for-as-in-list
    		| for-as-on-list | for-as-equals-then
    		| for-as-across | for-as-hash | for-as-package
    for-as-arithmetic ::= var [type-spec] [{from | downfrom | upfrom} expr1 ]
    		[{to | downto | upto | below | above} expr2]
    		[by expr3]
    for-as-in-list ::= var [type-spec] in expr1 [by step-fun]
    for-as-on-list ::= var [type-spec] on expr1 [by step-fun]
    for-as-equals-then ::= var [type-spec] = expr1 [then step-fun]
    for-as-across ::= var [type-spec] across vector
    for-as-hash ::= var [type-spec] being {each | the}
    		{hash-key | hash-keys | hash-value | hash-values}
    		{in | of} hash-table
    		[using ({hash-value | hash-key} other-var)]
    for-as-package ::= var [type-spec] being {each | the}
    		for-as-package-keyword
    		{in | of} package
    for-as-package-keyword ::= symbol | present-symbol | external-symbol
    		| symbols | present-symbols | external-symbols

This correction made `for` and `as` clauses syntactically similar to `with` clauses. I have changed all examples in this chapter to reflect the corrected syntax.-GLS]

In the following example, the variable `x` is stepped before `y` is stepped; thus, the value of `y` reflects the updated value of `x`:

    (loop for x from 1 to 9
          for y = nil then x
          collect (list x y))
       => ((1 NIL) (2 2) (3 3) (4 4) (5 5) (6 6) (7 7) (8 8) (9 9))

In the following example, `x` and `y` are stepped in parallel:

    (loop for x from 1 to 9
          and y = nil then x
          collect (list x y))
       => ((1 NIL) (2 1) (3 2) (4 3) (5 4) (6 5) (7 6) (8 7) (9 8))

The `for` and `as` clauses iterate by using one or more local loop variables that are initialized to some value and that can be modified or stepped after each iteration. For these clauses, iteration terminates when a local variable reaches some specified value or when some other loop clause terminates iteration. At each iteration, variables can be stepped by an increment or a decrement or can be assigned a new value by the evaluation of an expression. Destructuring can be used to assign initial values to variables during iteration.

The `for` and `as` keywords are synonyms and may be used interchangeably. There are seven syntactic representations for these constructs. In each syntactic description, the data type of var can be specified by the optional type-spec argument. If var is a destructuring list, the data type specified by the type-spec argument must appropriately match the elements of the list (see sections 26.12.1 and 26.12.2).

[Loop Clause]

    for var [type-spec] [{from | downfrom | upfrom} expr1]
        [{to | downto | upto | below | above} expr2]
        [by expr3]
    as var [type-spec] [{from | downfrom | upfrom} expr1]
        [{to | downto | upto | below | above} expr2]
        [by expr3]

[This is the first of seven `for`/`as` syntaxes.-GLS]

The `for` or `as` construct iterates from the value specified by expr1 to the value specified by expr2 in increments or decrements denoted by expr3. Each expression is evaluated only once and must evaluate to a number.

The variable var is bound to the value of expr1 in the first iteration and is stepped by the value of expr3 in each succeeding iteration, or by 1 if expr3 is not provided.

The following loop keywords serve as valid prepositions within this syntax.

`from`
  The loop keyword `from` marks the value from which stepping begins, as specified by expr1. Stepping is incremental by default. For decremental stepping, use `above` or `downto` with expr2. For incremental stepping, the default `from` value is `0`.

`downfrom`, `upfrom`
  The loop keyword `downfrom` indicates that the variable var is decreased in decrements specified by expr3; the loop keyword `upfrom` indicates that var is increased in increments specified by expr3.

`to`
  The loop keyword `to` marks the end value for stepping specified in expr2. Stepping is incremental by default. For decremental stepping, use `downto`, `downfrom`, or `above` with expr2.

`downto`, `upto`
  The loop keyword `downto` allows iteration to proceed from a larger number to a smaller number by the decrement expr3. The loop keyword `upto` allows iteration to proceed from a smaller number to a larger number by the increment expr3. Since there is no default for expr1 in decremental stepping, you must supply a value with `downto`.

`below`, `above`
  The loop keywords `below` and `above` are analogous to `upto` and `downto`, respectively. These keywords stop iteration just before the value of the variable var reaches the value specified by expr2; the end value of expr2 is not included. Since there is no default for expr1 in decremental stepping, you must supply a value with `above`.

`by`
  The loop keyword `by` marks the increment or decrement specified by expr3. The value of expr3 can be any positive number. The default value is `1`.

At least one of these prepositions must be used with this syntax.

In an iteration control clause, the `for` or `as` construct causes termination when the specified limit is reached. That is, iteration continues until the value var is stepped to the exclusive or inclusive limit specified by expr2. The range is exclusive if expr3 increases or decreases var to the value of expr2 without reaching that value; the loop keywords `below` and `above` provide exclusive limits. An inclusive limit allows var to attain the value of expr2; `to`, `downto`, and `upto` provide inclusive limits.

A common convention is to use `for` to introduce new iterations and `as` to introduce iterations that depend on a previous iteration specification. [However, `loop` does not enforce this convention, and some of the examples below violate it. De gustibus non disputandum est.-GLS]

Examples:

    ;;; Print some numbers.

    (loop as i from 1 to 5
          do (print i)) `;Prints 5 lines
    1
    2
    3
    4
    5
       => NIL

    ;;; Print every third number.

    (loop for i from 10 downto 1 by 3
          do (print i)) `;Prints 4 lines
    10
    7
    4
    1
       => NIL

    ;;; Step incrementally from the default starting value.

    (loop as i below 5
          do (print i)) `;Prints 5 lines
    0
    1
    2
    3
    4
       => NIL

[Loop Clause]
`for` var `[type-spec]` `in` expr1 `[by` `step-fun]` `
``as` var `[type-spec]` `in` expr1 `[by` `step-fun]`

[This is the second of seven `for`/`as` syntaxes.-GLS]

This construct iterates over the contents of a list. It checks for the end of the list as if using the Common Lisp function `endp`. The variable var is bound to the successive elements of the list expr1 before each iteration. At the end of each iteration, the function step-fun is called on the list and is expected to produce a successor list; the default value for step-fun is the `cdr` function.

The `for` or `as` construct causes termination when the end of the list is reached. The loop keywords `in` and `by` serve as valid prepositions in this syntax.

Examples:

    ;;; Print every item in a list.

    (loop for item in '(1 2 3 4 5) do (print item)) `;Prints 5 lines
    1
    2
    3
    4
    5
       => NIL

    ;;; Print every other item in a list.

    (loop for item in '(1 2 3 4 5) by #'cddr
          do (print item))  `;Prints 3 lines
    1
    3
    5
       => NIL

    ;;; Destructure items of a list, and sum the x values
    ;;; using fixnum arithmetic.
    (loop for (item . x) (t . fixnum)
              in '((A . 1) (B . 2) (C . 3))
          unless (eq item 'B) sum x)
       => 4

[Loop Clause]
`for` var `[type-spec]` `on` expr1 `[by` `step-fun]` `
``as` var `[type-spec]` `on` expr1 `[by` `step-fun]`

[This is the third of seven `for`/`as` syntaxes.-GLS]

This construct iterates over the contents of a list. It checks for the end of the list as if using the Common Lisp function `endp`. The variable var is bound to the successive tails of the list expr1. At the end of each iteration, the function step-fun is called on the list and is expected to produce a successor list; the default value for step-fun is the `cdr` function.

The loop keywords `on` and `by` serve as valid prepositions in this syntax. The `for` or `as` construct causes termination when the end of the list is reached.

Examples:

    ;;; Collect successive tails of a list.
    (loop for sublist on '(a b c d)
          collect sublist)
       => ((A B C D) (B C D) (C D) (D))

    ;;; Print a list by using destructuring with the loop keyword ON.
    (loop for (item) on '(1 2 3)
          do (print item))  `;Prints 3 lines
    1
    2
    3
       => NIL

    ;;; Print items in a list without using destructuring.
    (loop for item in '(1 2 3)
          do (print item))  `;Prints 3 lines
    1
    2
    3
       => NIL

[Loop Clause]
`for` var `[type-spec]` `=` expr1 `[then` expr2] `
``as` var `[type-spec]` `=` expr1 `[then` expr2]

[This is the fourth of seven `for`/`as` syntaxes.-GLS]

This construct initializes the variable var by setting it to the result of evaluating expr1 on the first iteration, then setting it to the result of evaluating expr2 on the second and subsequent iterations. If expr2 is omitted, the construct uses expr1 on the second and subsequent iterations. When expr2 is omitted, the expanded code shows the following optimization:

    ;;; Sample original code:
    (loop for x = expr1 then expr2 do (print x))

    ;;; The usual expansion:
    (tagbody
          (setq x expr1)
      tag (print x)
          (setq x expr2)
          (go tag))

    ;;; The optimized expansion:
    (tagbody
      tag (setq x expr1)
          (print x)
          (go tag))

The loop keywords `=` and `then` serve as valid prepositions in this syntax. This construct does not provide any termination conditions.

Example:

    ;;; Collect some numbers.
    (loop for item = 1 then (+ item 10)
          repeat 5
          collect item)
       => (1 11 21 31 41)

[Loop Clause]
`for` var `[type-spec]` `across` `vector` `
``as` var `[type-spec]` `across` `vector`

[This is the fifth of seven `for`/`as` syntaxes.-GLS]

This construct binds the variable var to the value of each element in the array vector.

The loop keyword `across` marks the array vector; `across` is used as a preposition in this syntax. Iteration stops when there are no more elements in the specified array that can be referenced.

Some implementations might use a [user-supplied-GLS] `the` special form in the vector form to produce more efficient code.

Example:

    (loop for char across (the simple-string (find-message port))
          do (write-char char stream))

[Loop Clause]

    for var [type-spec] being {each | the}
        {hash-key | hash-keys | hash-value | hash-values}
        {in | of} hash-table [using ({hash-value | hash-key} other-var)]
    as var [type-spec] being {each | the}
        {hash-key | hash-keys | hash-value | hash-values}
        {in | of} hash-table [using ({hash-value | hash-key} other-var)]

[This is the sixth of seven `for`/`as` syntaxes.-GLS]

This construct iterates over the elements, keys, and values of a hash table. The variable var takes on the value of each hash key or hash value in the specified hash table.

The following loop keywords serve as valid prepositions within this syntax.

`being`
  The keyword `being` marks the loop method to be used, either `hash-key` or `hash-value`.

`each`, `the`
  For purposes of readability, the loop keyword `each` should follow the loop keyword `being` when `hash-key` or `hash-value` is used. The loop keyword `the` is used with `hash-keys` and `hash-values`.

`hash-key`, `hash-keys`
  These loop keywords access each key entry of the hash table. If the name `hash-value` is specified in a `using` construct with one of these loop methods, the iteration can optionally access the keyed value. The order in which the keys are accessed is undefined; empty slots in the hash table are ignored.

`hash-value`, `hash-values`
  These loop keywords access each value entry of a hash table. If the name `hash-key` is specified in a `using` construct with one of these loop methods, the iteration can optionally access the key that corresponds to the value. The order in which the keys are accessed is undefined; empty slots in the hash table are ignored.

`using`
  The loop keyword `using` marks the optional key or the keyed value to be accessed. It allows you to access the hash key if iterating over the hash values, and the hash value if iterating over the hash keys.

`in`, `of`
  These loop prepositions mark the hash table hash-table.

Iteration stops when there are no more hash keys or hash values to be referenced in the specified hash table.

[Loop Clause]

    for var [type-spec] being {each | the}
        {symbol | present-symbol | external-symbol |
         symbols | present-symbols | external-symbols}
        {in | of} package
    as var [type-spec] being {each | the}
        {symbol | present-symbol | external-symbol |
         symbols | present-symbols | external-symbols}
        {in | of} package

[This is the last of seven `for`/`as` syntaxes.-GLS]

This construct iterates over the symbols in a package. The variable var takes on the value of each symbol in the specified package.

The following loop keywords serve as valid prepositions within this syntax.

`being`
  The keyword `being` marks the loop method to be used: `symbol`, `present-symbol`, or `external-symbol`.

`each`, `the`
  For purposes of readability, the loop keyword `each` should follow the loop keyword `being` when `symbol`, `present-symbol`, or `external-symbol` is used. The loop keyword `the` is used with `symbols`, `present-symbols`, and `external-symbols`.

`present-symbol`, `present-symbols`
  These loop methods iterate over the symbols that are present but not external in a package. The package to be iterated over is specified in the same way that package arguments to the Common Lisp function `find-package` are specified. If you do not specify the package for the iteration, the current package is used. If you specify a package that does not exist, an error is signaled.

`symbol`, `symbols`
  These loop methods iterate over symbols that are accessible from a given package. The package to be iterated over is specified in the same way that package arguments to the Common Lisp function `find-package` are specified. If you do not specify the package for the iteration, the current package is used. If you specify a package that does not exist, an error is signaled.

`external-symbol`, `external-symbols`
  These loop methods iterate over the external symbols of a package. The package to be iterated over is specified in the same way that package arguments to the Common Lisp function `find-package` are specified. If you do not specify the package for the iteration, the current package is used. If you specify a package that does not exist, an error is signaled.

`in`, `of`
  These loop prepositions mark the package package.

Iteration stops when there are no more symbols to be referenced in the specified package.

Example:

    (loop for x being each present-symbol of "COMMON-LISP-USER"
          do (print x)) `;Prints 7 lines in this example
    COMMON-LISP-USER::IN
    COMMON-LISP-USER::X
    COMMON-LISP-USER::ALWAYS
    COMMON-LISP-USER::FOO
    COMMON-LISP-USER::Y
    COMMON-LISP-USER::FOR
    COMMON-LISP-USER::LUCID
       => NIL

[Loop Clause]
`repeat` expr

The `repeat` construct causes iteration to terminate after a specified number of times. The loop body is executed n times, where n is the value of the expression expr. The expr argument is evaluated one time in the loop prologue. If the expression evaluates to zero or to a negative number, the loop body is not evaluated.

The clause `repeat` n is roughly equivalent to a clause such as

    for internal-variable downfrom (- n 1) to 0

but, in some implementations, the `repeat` construct might be more efficient.

Examples:

    (loop repeat 3 `;Prints 3 lines
          do (format t "What I say three times is true~%"))
    What I say three times is true
    What I say three times is true
    What I say three times is true
       => NIL

    (loop repeat -15 `;Prints nothing
          do (format t "What you see is what you expect~%"))
       => NIL

Next: End-Test Control Up: Loop Previous: Loop Constructs