==== DOLIST ====
<callout type="primary" color="" icon="fa fa-book" title="Synopsis">
----
Do a procedure with elements of lists
</callout>

<callout color="green" icon="fa fa-indent" title="Stack Diagram">
----
^  __Input Stack__  ^^^^^  ^  __Output Stack__  ^
|  **L<sub>1</sub>**  |  **...**  |  **L<sub>n</sub>**  |  **I<sub>n</sub>**  |  **P<sub>exec</sub>**  |  **→**  |  **L<sub>results</sub>**  |
|  **L<sub>1</sub>**  |  **...**  |  **L<sub>n</sub>**  |  **I<sub>n</sub>**  |  **N<sub>exec</sub>**  |  **→**  |  **L<sub>results</sub>**  |
|  //Level n+2//  |  //...//  |  //Level 3//  |  //Level 2//  |  //Level 1//  |  //→//  |  //Level 1//  |

{{page>manual:chapter6:aux:legend&nofooter&noeditbtn&inline}}

| **Keyword type**  | [[manual:chapter5:basics#commands|Command]]  ||
| **Parallel list processing capabilities**  | [[manual:chapter5:listproc#group-2commands-that-must-use-dolist-to-parallel-process|Group 2]]  | //Commands that must use //''[[manual:chapter6:lists:cmd_cmddolist|DOLIST]]''// to parallel process//  |
| **Affected by flags**  | //None//  ||














</callout>

<callout color="orangered" icon="fa fa-comment" title="Description">
----
The ''DOLIST'' command ''[[manual:chapter6:operators:cmd_ovr_eval|EVAL]]''uates a specified program (or a variable which contains one) to lists of objects.\\
\\
All lists must be the same length //len//. The program is executed //len// times: on the //i//-th iteration, **I<sub>n</sub>** objects each taken from the //i//-th position in each list are entered on the stack in the same order as in their original lists, and the program **P<sub>exec</sub>** is ''[[manual:chapter6:operators:cmd_ovr_eval|EVAL]]''uated. The results from each execution are left on the stack.\\
\\
After the final iteration, any new results are combined into a single list: the ''UNMIX'' program presented [[manual:chapter5:listproc#group-8multiple-result-commands|here]] can help disentangling the results.
</callout>

<callout type="warning" icon="true" title="Compatibility">
----
''DOLIST'' is not fully equivalent to its **userRPL** counterpart.

In particular:

  * in **userRPL** the number of arguments can be omitted under certain conditions; in **newRPL** it must be always specified;
  * the program launched by ''DOLIST'' operates in a protected stack environment: no elements present on the stack before ''DOLIST'' is launched can be reached or altered.
</callout>

<callout type="info" icon="true" title="Usage">
----
**__Input__**
<code>
5:                             { 1 2 3 }
4:                             { 4 5 6 }
3:                             { 7 8 9 }
2:                                     3
1:                               « + * »
…………………………………………………………………………………………………………
DOLIST                                  
</code>
\\
**__Output__**
<code>
4:                                      
3:                                      
2:                                      
1:                          { 11 26 45 }
…………………………………………………………………………………………………………
                                        
</code>
</callout>

<callout color="darkgray" icon="fa fa-hand-o-right" title="Related Commands">
----
{{page>manual:chapter6:lists&nofooter&noeditbtn&inline}}
</callout>