Common Lisp the Language, 2nd Edition


next up previous contents index
Next: End-Test Control Up: Loop Previous: Loop Constructs

26.6. Iteration Control

change_begin
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


change_end



next up previous contents index
Next: End-Test Control Up: Loop Previous: Loop Constructs


AI.Repository@cs.cmu.edu