==== DOSUBS ====
<callout type="primary" color="" icon="fa fa-book" title="Synopsis">
----
Do a procedure on a subset of a list
</callout>

<callout color="green" icon="fa fa-indent" title="Stack Diagram">
----
^  __Input Stack__  ^^^  ^  __Output Stack__  ^
|  **L<sub>data</sub>**  |  **I<sub>n</sub>**  |  **P<sub>exec</sub>**  |  **→**  |  **L<sub>results</sub>**  |
|  **L<sub>data</sub>**  |  **I<sub>n</sub>**  |  **N<sub>exec</sub>**  |  **→**  |  **L<sub>results</sub>**  |
|  //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 ''DOSUBS'' command ''[[manual:chapter6:operators:cmd_ovr_eval|EVAL]]''uates a specified program (or a variable which contains one) to groups of elements in a list.\\
\\
The first iteration uses elements //1// through **I<sub>n</sub>** from the list; the second iteration uses elements //2// through **I<sub>n</sub>**// + 1//; and so on. In general, the //m//-th iteration uses the elements from the list corresponding to positions //m// through //m + //**I<sub>n</sub>**// – 1//.\\
\\
During an iteration, the position of the first element used in that iteration is available to the user using the local variable ''NSUB'', and the number of groups of elements is available using the local variable ''ENDSUB''.\\
\\
''DOSUBS'' is nominally designed for **P<sub>exec</sub>** (or **N<sub>exec</sub>**) __requiring **I<sub>n</sub>** arguments and returning one result__.
</callout>

<callout type="warning" icon="true" title="Compatibility">
----
''DOSUBS'' 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;
  * in **userRPL** ''NSUB'' and ''ENDSUBS'' are commands; in **newRPL** they are local variables;
  * the program launched by ''DOSUBS'' operates in a protected stack environment: no elements present on the stack before ''DOSUBS'' is launched can be reached or altered.
</callout>

<callout type="info" icon="true" title="Usage">
----
**__Input__**
<code>
{ 1 2 3 4 5 }
2
« → a b
  « CASE
      'NSUB==1'
    THEN
      a
    END
      'NSUB==ENDSUB'
    THEN
      b
    END
      'a+b' EVAL
    END
  »
»
DOSUBS
</code>
\\
**__Output__**
<code>
4:                                      
3:                                      
2:                                      
1:                           { 1 5 7 5 }
…………………………………………………………………………………………………………
                                        
</code>
</callout>

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