Common Lisp the Language, 2nd Edition

26.3.2. Kinds of Loop Clauses

Loop clauses fall into one of the following categories:

• variable initialization and stepping
  • The for and as constructs provide iteration control clauses that establish a variable to be initialized. You can combine for and as clauses with the loop keyword and to get parallel initialization and stepping.

  • The with construct is similar to a single let clause. You can combine with clauses using and to get parallel initialization.

  • The repeat construct causes iteration to terminate after a specified number of times. It uses an internal variable to keep track of the number of iterations.

  You can specify data types for loop variables (see section 26.12.1). It is an error to bind the same variable twice in any variable-binding clause of a single loop expression. Such variables include local variables, iteration control variables, and variables found by destructuring.

• value accumulation
  • The collect construct takes one form in its clause and adds the value of that form to the end of a list of values. By default, the list of values is returned when the loop finishes.

  • The append construct takes one form in its clause and appends the value of that form to the end of a list of values. By default, the list of values is returned when the loop finishes.

  • The nconc construct is similar to append, but its list values are concatenated as if by the Common Lisp function nconc. By default, the list of values is returned when the loop finishes.

  • The sum construct takes one form in its clause that must evaluate to a number and adds that number into a running total. By default, the cumulative sum is returned when the loop finishes.

  • The count construct takes one form in its clause and counts the number of times that the form evaluates to a non-nil value. By default, the count is returned when the loop finishes.

  • The minimize construct takes one form in its clause and determines the minimum value obtained by evaluating that form. By default, the minimum value is returned when the loop finishes.

  • The maximize construct takes one form in its clause and determines the maximum value obtained by evaluating that form. By default, the maximum value is returned when the loop finishes.

• termination conditions
  • The loop-finish Lisp macro terminates iteration and returns any accumulated result. If specified, any finally clauses are evaluated.

  • The for and as constructs provide a termination test that is determined by the iteration control clause.

  • The repeat construct causes termination after a specified number of iterations.

  • The while construct takes one form, a condition, and terminates the iteration if the condition evaluates to nil. A while clause is equivalent to the expression (if (not condition) (loop-finish)).

  • The until construct is the inverse of while; it terminates the iteration if the condition evaluates to any non-nil value. An until clause is equivalent to the expression (if condition (loop-finish)).

  • The always construct takes one form and terminates the loop if the form ever evaluates to nil; in this case, it returns nil. Otherwise, it provides a default return value of t.

  • The never construct takes one form and terminates the loop if the form ever evaluates to non-nil; in this case, it returns nil. Otherwise, it provides a default return value of t.

  • The thereis construct takes one form and terminates the loop if the form ever evaluates to non-nil; in this case, it returns that value.

• unconditional execution
  • The do construct simply evaluates all forms in its clause.

  • The return construct takes one form and returns its value. It is equivalent to the clause do (return value).

• conditional execution
  • The if construct takes one form as a predicate and a clause that is executed when the predicate is true. The clause can be a value accumulation, unconditional, or another conditional clause; it can also be any combination of such clauses connected by the loop keyword and.

  • The when construct is a synonym for if.

  • The unless construct is similar to when except that it complements the predicate; it executes the following clause if the predicate is false.

  • The else construct provides an optional component of if, when, and unless clauses that is executed when the predicate is false. The component is one of the clauses described under if.

  • The end construct provides an optional component to mark the end of a conditional clause.

• miscellaneous operations
  • The named construct assigns a name to a loop construct.

  • The initially construct causes its forms to be evaluated in the loop prologue, which precedes all loop code except for initial settings specified by the constructs with, for, or as.

  • The finally construct causes its forms to be evaluated in the loop epilogue after normal iteration terminates. An unconditional clause can also follow the loop keyword finally.