User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:macros:dolist [2019/10/13 03:00]
cl:macros:dolist [2019/10/18 02:00] (current)
Line 1: Line 1:
 +====== Macro DOLIST ======
 +
 +====Syntax====
 +  * **dolist** //(var list-form [result-form]) declaration''​*''​ {tag | statement}''​*''//​ → //​result''​*''//​
 +
 +====Arguments and Values====
 +  * //var// - a //​[[CL:​Glossary:​symbol]]//​.
 +  * //​list-form//​ - a //​[[CL:​Glossary:​form]]//​.
 +  * //​result-form//​ - a //​[[CL:​Glossary:​form]]//​.
 +  * //​declaration//​ - a **[[CL:​Symbols:​declare]]** //​[[CL:​Glossary:​expression]]//;​ not evaluated.
 +  * //tag// - a //​[[CL:​Glossary:​go tag]]//; not evaluated.
 +  * //​statement//​ - a //​[[CL:​Glossary:​compound form]]//; evaluated as described below.
 +  * //results// - if a **[[CL:​Macros:​return]]** or **[[CL:​Macros:​return-from]]** form is executed, the //​[[CL:​Glossary:​values]]//​ passed from that //​[[CL:​Glossary:​form]]//;​ otherwise, the //​[[CL:​Glossary:​values]]//​ returned by the //​result-form//​ or **[[CL:​Constant Variables:​nil]]** if there is no //​result-form//​.
 +
 +====Description====
 +
 +**dolist** iterates over the elements of a //​[[CL:​Glossary:​list]]//​. The body of **dolist** is like a **[[CL:​Special Operators:​tagbody]]**. It consists of a series of //tags// and //​statements//​.
 +
 +**dolist** evaluates //​list-form//,​ which should produce a //​[[CL:​Glossary:​list]]//​. It then executes the body once for each element in the //​[[CL:​Glossary:​list]]//,​ in the order in which the //tags// and //​statements//​ occur, with //var// bound to the element. Then //​result-form//​ is evaluated. //tags// label //​statements//​.
 +
 +At the time //​result-form//​ is processed, //var// is bound to **[[CL:​Constant Variables:​nil]]**.
 +
 +An //​[[CL:​Glossary:​implicit block]]// named **[[CL:​Constant Variables:​nil]]** surrounds **dolist**.
 +
 +**[[CL:​Macros:​return]]** may be used to terminate the loop immediately without performing any further iterations, returning zero or more //​[[CL:​Glossary:​value|values]]//​.
 +
 +The //​[[CL:​Glossary:​scope]]//​ of the binding of //var// does not include the //​list-form//,​ but the //​result-form//​ is included.
 +
 +It is //​[[CL:​Glossary:​implementation-dependent]]//​ whether **dolist** //​[[CL:​Glossary:​establish|establishes]]//​ a new //​[[CL:​Glossary:​binding]]//​ of //var// on each iteration or whether it //​[[CL:​Glossary:​establish|establishes]]//​ a binding for //var// once at the beginning and then //assigns// it on any subsequent iterations.
 +
 +====Examples====
 +
 +<​blockquote>​
 +([[CL:​Macros:​defparameter]] *temp-two* '()) <​r>​[[CL:​Constant Variables:​nil|NIL]] </r>
 +(dolist (*temp-one* '(1 2 3 4) *temp-two*) ([[CL:​Macros:​push]] *temp-one* *temp-two*)) <r>(4 3 2 1)</​r>​
 +
 +([[CL:​Macros:​defparameter]] *temp-two* 0) <r>0 </r>
 +(dolist (*temp-one* '(1 2 3 4)) ([[CL:​Macros:​incf]] *temp-two*)) <​r>​[[CL:​Constant Variables:​nil|NIL]] </r>
 +*temp-two* <​r>​4</​r>​
 +
 +(dolist (x '(a b c d)) ([[CL:​Functions:​prin1]] x) ([[CL:​Functions:​princ]] " "))
 +<o>A B C D </o>
 +<​r>​[[CL:​Constant Variables:​nil|NIL]]</​r>​
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Macros:​do|Macro DO]]**
 +  * **[[CL:​Macros:​dotimes|Macro DOTIMES]]**
 +  * **[[CL:​Special Operators:​tagbody|Special Operator TAGBODY]]**
 +  * {\secref\TraversalRules}
 +
 +====Notes====
 +**[[CL:​Special Operators:​go]]** may be used within the body of **dolist** to transfer control to a statement labeled by a //tag//.
 +
 +\issue{DECLS-AND-DOC} \issue{MAPPING-DESTRUCTIVE-INTERACTION:​EXPLICITLY-VAGUE}