Next: Termination Test Clauses, Previous: Variable Initialization and Stepping Clauses, Up: The LOOP Facility
The constructs collect, collecting,
append, appending,
nconc, nconcing,
count, counting,
maximize, maximizing,
minimize, minimizing,
sum, and summing,
allow values to be accumulated in a loop.
The constructs collect,
collecting, append, appending,
nconc, and nconcing,
designate clauses that
accumulate values in lists and return them.
The constructs count, counting,
maximize, maximizing, minimize, minimizing,
sum, and summing designate clauses that accumulate and
return numerical values.
During each iteration, the constructs
collect and collecting
collect the value of the supplied
form into a list.
When iteration terminates, the list is returned.
The argument var is
set to the list
of collected values; if var is supplied, the loop
does not return the final list automatically. If
var is not
supplied, it is equivalent to supplying an internal name for
var and returning its value in a finally clause.
The var argument
is bound as if by the construct with.
No mechanism is provided for declaring the type of var;
it must be of type list.
The constructs append, appending,
nconc, and nconcing
are similar to collect except that the
values of the supplied form must be lists.
append keyword causes its list values to be concatenated
into a single list, as if
they were arguments to the function append.
nconc keyword causes its list values to be concatenated
into a single list,
as if they were arguments to the function nconc.
The argument var is
set to the list of
concatenated values; if var is supplied,
loop
does not return the final list automatically.
The var argument
is bound as if by the construct with.
A type cannot be supplied for var;
it must be of type list.
The construct nconc
destructively modifies its argument lists.
The count construct counts the number of times
that the supplied form returns true.
The argument var accumulates the number of occurrences;
if var is supplied,
loop does not return the final count automatically.
The var argument is bound as if by the construct with
to a zero of the appropriate type.
Subsequent values (including any necessary coercions)
are computed as if by the function 1+.
If into var is used,
a type can be supplied for var with the type-spec argument;
the consequences are unspecified if a nonnumeric type is supplied.
If there is no into variable,
the optional type-spec argument
applies to the internal variable that is keeping the count.
The default type is implementation-dependent;
but it must be
a supertype of type fixnum.
The maximize and
minimize
constructs compare
the value of the supplied form obtained during the first
iteration with values obtained in successive iterations.
The maximum (for maximize) or minimum (for minimize)
value encountered is determined
(as if by the function max for maximize and
as if by the function min for minimize)
and returned.
If the maximize or minimize clause
is never executed, the accumulated value is unspecified.
The argument var accumulates the maximum or minimum value;
if var is supplied,
loop does not return the maximum or minimum automatically.
The var argument is bound as if by the construct with.
If into var is used,
a type can be supplied for var with the type-spec argument;
the consequences are unspecified if a nonnumeric type is supplied.
If there is no into variable,
the optional type-spec argument applies to the internal variable
that is keeping the maximum or minimum value.
The default type
is implementation-dependent; but it
must be a supertype of type real.
The sum construct forms a cumulative sum
of the successive primary values of the supplied form
at each iteration.
The argument var is used to accumulate the sum;
if var is supplied,
loop does not return the final sum automatically.
The var argument is bound as if by the construct with
to a zero of the appropriate type.
Subsequent values (including any necessary coercions) are computed as if by the function +.
If into var is used,
a type can be supplied for var with the type-spec argument;
the consequences are unspecified if a nonnumeric type is supplied.
If there is no into variable,
the optional type-spec argument applies to the internal variable
that is keeping the sum.
The default type
is implementation-dependent; but it
must be a supertype of type number.
If into is used,
the construct does not provide a default return value;
however, the variable is available
for use in any finally clause.
Certain kinds of accumulation clauses can be combined in a loop
if their destination is the same
(the result of loop or an into var)
because they are considered to accumulate conceptually compatible quantities.
In particular,
any elements of following sets of accumulation clauses can be mixed
with other elements of the same set for the same destination
in a loop form:
collect, append, nconc
sum, count
maximize, minimize
;; Collect every name and the kids in one list by using
;; COLLECT and APPEND.
(loop for name in '(fred sue alice joe june)
for kids in '((bob ken) () () (kris sunshine) ())
collect name
append kids)
→ (FRED BOB KEN SUE ALICE JOE KRIS SUNSHINE JUNE)
Any two
clauses that do not accumulate the same type of
object
can coexist in a loop only
if each clause accumulates its values into
a different
variable.
;; Collect all the symbols in a list.
(loop for i in '(bird 3 4 turtle (1 . 4) horse cat)
when (symbolp i) collect i)
→ (BIRD TURTLE HORSE CAT)
;; Collect and return odd numbers.
(loop for i from 1 to 10
if (oddp i) collect i)
→ (1 3 5 7 9)
;; Collect items into local variable, but don't return them.
(loop for i in '(a b c d) by #'cddr
collect i into my-list
finally (print my-list))
▷ (A C)
→ NIL
;; Use APPEND to concatenate some sublists.
(loop for x in '((a) (b) ((c)))
append x)
→ (A B (C))
;; NCONC some sublists together. Note that only lists made by the
;; call to LIST are modified.
(loop for i upfrom 0
as x in '(a b (c))
nconc (if (evenp i) (list x) nil))
→ (A (C))
(loop for i in '(a b nil c nil d e)
count i)
→ 5
(loop for i in '(2 1 5 3 4)
maximize i)
→ 5
(loop for i in '(2 1 5 3 4)
minimize i)
→ 1
;; In this example, FIXNUM applies to the internal variable that holds
;; the maximum value.
(setq series '(1.2 4.3 5.7))
→ (1.2 4.3 5.7)
(loop for v in series
maximize (round v) of-type fixnum)
→ 6
;; In this example, FIXNUM applies to the variable RESULT.
(loop for v of-type float in series
minimize (round v) into result of-type fixnum
finally (return result))
→ 1
(loop for i of-type fixnum in '(1 2 3 4 5)
sum i)
→ 15
(setq series '(1.2 4.3 5.7))
→ (1.2 4.3 5.7)
(loop for v in series
sum (* 2.0 v))
→ 22.4