Contents|Symbol Index|Up: Chapter 5 Dictionary|Prev: defparameter, defvar|Next: let, let*

Macro `destructuring-bind`

Syntax:

destructuring-bind lambda-list expression {declaration}^* {form}^* → {result}^*

Arguments and Values:

8.1.0 9 8.1.0 10 8.1.0 11 8.1.0 12 tweaked --sjl 5 Mar 92 \param{lambda-list}---a \term{lambda list}; can contain the \term{lambda list keywords} \keyref{allow-other-keys}, \keyref{aux}, \keyref{body}, \keyref{key}, \keyref{optional}, \keyref{rest}, and \keyref{whole}.lambda-list—a destructuring lambda list.

expression—a form.

declaration—a declare expression; not evaluated.

forms—an implicit progn.

results—the values returned by the forms.

Description:

destructuring-bind binds the variables specified in lambda-list to the corresponding values in the tree structure resulting from the evaluation of expression; then destructuring-bind evaluates forms.

All of this text is redundant; a simple cross-reference will do. --sjl 5 Mar 92 Anywhere in \param{lambda-list} where a parameter name can appear, and where ordinary \term{lambda list} syntax as described in {\secref\OrdinaryLambdaLists} does not otherwise allow a \term{list}, a \term{lambda list} can appear in place of the parameter name. When this is done, then the portion of the tree structure resulting from the evaluation of \param{expression} that would match the parameter is treated as a tree structure for satisfying the parameters in the embedded \term{lambda list}. If any of the \term{lambda list keywords} \keyref{optional}, \keyref{rest}, \keyref{key}, \keyref{allow-other-keys} and \keyref{aux} appears in \param{lambda-list}, it is treated as it would be in an \term{ordinary lambda list}. If the \term{lambda list keyword} \keyref{body} appears, it is treated the same as if \keyref{rest} had appeared. (Only one of \keyref{body} or \keyref{rest} can be used at any one level.) If the \term{lambda list keyword} \keyref{whole} appears, it must be immediately followed by a single variable that is bound to the entire tree at the current level. \keyref{whole} and its following variable should appear first in the list, before any other \term{parameter} or \term{lambda list keyword}. It is also permissible for any level of \param{lambda-list} to be a \term{dotted list}, ending in a parameter name. This situation is treated exactly as if the parameter name that ends the \term{dotted list} had appeared preceded by \keyref{rest} in a \term{proper list}. For example, the notation \f{(x y . z)} is equivalent to \f{(x y \&rest z)}. For \keyref{optional} and \keyref{key} parameters, initialization forms and ``supplied-p'' parameters can be supplied, just as for \macref{defun}.

The lambda-list supports destructuring as described in Section 3.4.5 (Destructuring Lambda Lists).

Examples:

 (defun iota (n) (loop for i from 1 to n collect i))       ;helper
 (destructuring-bind ((a &optional (b 'bee)) one two three)
     `((alpha) ,@(iota 3))
   (list a b three two one)) → (ALPHA BEE 3 2 1)

Affected By:

None.

Exceptional Situations:

If the result of evaluating the expression does not match the destructuring pattern, an error of type error should be signaled.

Notes: