manual:chapter6:lists:cmd

Synopsis

Do a procedure on a subset of a list

Stack Diagram

Input Stack				Output Stack
L_data	I_n	P_exec	→	L_results
L_data	I_n	N_exec	→	L_results
Level 3	Level 2	Level 1	→	Level 1

Legend

Legend	Object type
O	Any object
I	Integer number
R	Real number
#	Binary number
Num	Scalar (Integer, Real or Binary number)
Z	Complex number
U	Unit
∡	Angle
A	Symbolic expression
C	Symbolic constant
V	Vector
M	Matrix
S	String
1/0	Any expression evaluating to True or False
G	Grob
F	Font
D	Binary data container
T	Tag object
L	List
cL	Case list
N	Variable name / Identifier
Dir	Directory
pDir	Packed Directory
P	Program
Lib	Library

Keyword type	Command
Parallel list processing capabilities	Group 2	Commands that must use `DOLIST` to parallel process
Affected by flags	None

Description

The DOSUBS command EVALuates a specified program (or a variable which contains one) to groups of elements in a list.

The first iteration uses elements 1 through I_n from the list; the second iteration uses elements 2 through I_n + 1; and so on. In general, the m-th iteration uses the elements from the list corresponding to positions m through m + I_n – 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_exec (or N_exec) requiring I_n arguments and returning one result.

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.

Usage

Input

{ 1 2 3 4 5 }
2
« → a b
  « CASE
      'NSUB==1'
    THEN
      a
    END
      'NSUB==ENDSUB'
    THEN
      b
    END
      'a+b' EVAL
    END
  »
»
DOSUBS

Output

4:                                      
3:                                      
2:                                      
1:                           { 1 5 7 5 }
…………………………………………………………………………………………………………

Related Commands

Operations with Lists 15 2 NEW

Command	Short Description
→LIST	Assemble a list from its elements
LIST→	Split a list into its elements
DOLIST	Do a procedure with elements of lists	CHANGED
DOSUBS	Do a procedure on a subset of a list	CHANGED
MAP	Do a procedure on each element of a list, recursively
MAPLIST→	Do a procedure on each element recursively, return individual elements	NEW
STREAM	Do a procedure on consecutive elements of a list
ΔLIST	First differences on the elements of a list
ΣLIST	Sum of all elements in a list	CHANGED
ΠLIST	Product of all elements in a list	CHANGED
ADD	Concatenate lists and/or elements	CHANGED
SORT	Sort elements in a list
REVLIST	Reverse the order of elements in a list
ADDROT	Add elements to a list, keep only the last N elements	NEW
SEQ	Assemble a list from results of sequential procedure