Macro COLLECTING

Syntax:

collecting form* => result

with-collectors (collector*) form* => result*

Arguments and Values:

forms---an implicit progn.

collector---a symbol which will have a collection function bound to it.

result---a collected list.

Description:

collecting collects things into a list. Within the body of this macro, the collect function will collect its argument into result.

with-collectors collects some things into lists. The collector names are defined as local functions which each collect into a separate list. Returns as many values as there are collectors, in the order they were given.

Exceptional situations:

If the collector names are not all symbols, a type-error will be signalled.

Examples:

(collecting (dotimes (x 10) (collect x))) => (0 1 2 3 4 5 6 7 8 9)

(multiple-value-bind (a b)
    (with-collectors (x y)
      (x 1)
      (y 2)
      (x 3))
  (append a b)) => (1 2 3)

Implementation notes:

Opinions differ on how a collection macro should work. There are two major points for discussion: multiple collection variables and implementation method.

There are two main ways of implementing collection: sticking successive elements onto the end of the list with tail-collection, or using the PUSH/NREVERSE idiom. Tail-collection is usually faster, except on CLISP, where PUSH/NREVERSE is a little faster because it's implemented in C which is always faster than Lisp bytecode.

The collecting macro only allows collection into one list, and you can't nest them to get the same effect as multiple collection since it always uses the collect function. If you want to collect into multiple lists, use the with-collect macro.