2.2 Iteration control

2.2.2 Reference pages

for Iteration Control Clause Keyword

as Iteration Control Clause Keyword

Syntax 1

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

Thefor andas 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 andas keywords are synonyms; you can use them interchangeably. There are five syntactic representations for these constructs, which are described in the following pages. 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 Section 2.8.1 on page 38 and Section 2.8.2 on page 39 for more information.

Thefor oras 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:

The loop keywordfrom marks the value from which stepping begins, as specified by expr1. Stepping is incremental by default. If you want decremental stepping, you must use either the prepositiondownto or the prepositionabove with expr2. For incremental stepping, the defaultfrom value is 0.

The loop keyworddownfrom indicates that the variable var is decreased in decrements specified by expr3; the loop keywordupfrom indicates that var is increased in increments specified by expr3.

The loop keywordto marks the end value for stepping specified in expr2. Stepping is incremental by default. If you want decremental stepping, you must use either the prepositiondownto,downfrom, orabove with expr2.

The loop keyworddownto allows iteration to proceed from a larger number to a smaller number by the decrement expr3. The loop keywordupto 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 withdownto.

The loop keywordsbelow andabove are analogous toupto anddownto 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 withabove.

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

You must use at least one of the three classes of prepositions:

In an iteration control clause, thefor oras construct causes termination when the specified limit is reached. That is, iteration continues until the value var is stepped to the exclusive limit 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 keywordsbelow andabove provide exclusive limits. An inclusive limit allows var to attain the value of expr2;to,downto, andupto provide inclusive limits.

By convention,for introduces new iterations andas introduces iterations that depend on a previous iteration specification.

;; Print some numbers.
> (loop as i from 1 to 3
        do (print i))
1
2
3
NIL

;; Print every third number. > (loop for i from 10 downto 1 by 3 do (print i)) 10 7 4 1 NIL

;; Step incrementally from the default starting value. > (loop as i below 3 do (print i)) 0 1 2 NIL

Syntax 2

{for|as} var [type-spec]in expr1 [by step-fun]

This construct iterates over the contents of a list. It checks for the end of the list as if by using the Common Lisp functionendp. 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 applied to the list; the default value for step-fun is thecdr function.

The loop keywordsin andby serve as valid prepositions in this syntax.

Thefor oras construct causes termination when the end of the list is reached.

;; Print every item in a list.
> (loop for item in '(1 2 3) do (print item))
1
2
3
NIL

;; Print every other item in a list. > (loop for item in '(1 2 3 4 5) by #'cddr do (print item)) 1 3 5 NIL

;; Destructure 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

See Also: for/as, Syntax 3

Syntax 3

{for|as} var [type-spec]on expr1[by step-fun]

This construct iterates over the contents of a list. It checks for the end of the list as if by using the Common Lisp functionatom. The variable var is bound to the successive tails of the list expr1. At the end of each iteration, the function step-fun is applied to the list; the default value for step-fun is thecdr function.

The loop keywordson andby serve as valid prepositions in this syntax.

Thefor oras construct causes termination when the end of the list is reached.

;; 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)) 1 2 3 NIL

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

See Also: for/as, Syntax 2

Syntax 4

{for|as} var [type-spec]= expr1[then expr2]

This construct binds the variable var to the result of evaluating expr1 within the loop prologue; when you supply an optionalthen clause, expr1 is evaluated one time only. At the end of each nonterminating iteration, var is bound to the value of expr2, if such an expression is specified.

The loop keywords = andthen serve as valid prepositions in this syntax.

This construct does not provide any termination conditions.

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

See Also: for/as, Syntax 5

Syntax 5

{for|as} var [type-spec]first expr1 then expr2

This construct binds the variable var to the result of evaluating expr1 within the loop body; expr1 is evaluated one time only. At the end of each nonterminating iteration, var is bound to the value of expr2.

The following loop keywords are valid within this syntax:

The loop keywordfirst marks the expression expr1 that is evaluated in the first iteration.

Usefirst rather than= in cases where expr1 depends on a previous iteration value.

The loop keywordthen marks the expression expr2.

This construct does not provide any termination conditions.

  ;; Collect birthdays.
  > (loop for b-day in '(birthdays (joe jan) 
                                   (alice dec) 
                                   (curly jul))
          for bday-info first b-day then (car b-day)
          collect bday-info)
  (BIRTHDAYS JOE ALICE CURLY)

See Also: for/as, Syntax 4

repeat Iteration Control Clause Keyword

Syntax:repeat expr

Therepeat construct causes iteration to terminate after a specified number of times.

The loop body executes 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 0 or to a negative number, the loop body is not evaluated.

> (loop repeat 3
        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 do (format t "What you see is what you expect~%")) NIL


The Loop Facility - 9 SEP 1996

Generated with Harlequin WebMaker