foreach

foreach( 
s_formalVar 
g_exprList 
g_expr1 
[ g_expr2 ... ] 
)
=> l_valueList / l_result
foreach( 
( 
s_formalVar1... 
s_formalVarN 
) 
g_exprList1... 
g_exprListN 
g_expr1 
[ g_expr2 ... ] 
)
=> l_valueList / l_result
foreach( 
s_formalVar 
g_exprTable 
g_expr1 
[ g_expr2 ... ] 
)
=> o_valueTable / l_result

Description

Evaluates one or more expressions for each element of a list of values. This is a syntax form.

foreach( [s_mappingFunction]s_formalVar g_exprList g_expr1 [ g_expr2 ... ] )
=> l_valueList / l_result

The first syntax form evaluates g_exprList, which returns a list l_valueList. It then assigns the first element from l_valueList to the formal variable s_formalVar and  executes the expressions g_expr1, g_expr2 ... in sequence. The function then assigns the second element from l_valueList and repeats the process until l_valueList is exhausted.

foreach( [s_mappingFunction] (s_formalVar1...s_formalVarN ) g_exprList1... g_exprListN g_expr1 [ g_expr2 ... ] )
=> l_valueList / l_result

The second syntax form of foreach can iterate over multiple lists to perform vector operations. Instead of a single formal variable, the first argument is a list of formal variables followed by a corresponding number of expressions for value lists and the expressions to be evaluated.

foreach( [s_mappingFunction] s_formalVar g_exprTable g_expr1 [ g_expr2 ... ])
=> o_valueTable / l_result

The third syntax form of foreach can be used to process the elements of an association table. In this case, s_formalVar is assigned each key of the association table one by one, and the body expressions are evaluated each iteration. The syntax for association table processing is provided in this syntax statement.

Arguments

s_formalVar	Name of the variable.
s_mappingFunction	One of map, mapc, mapcan, mapcar, mapcon, or maplist.
g_exprList	Expression whose value is a list of elements to assign to the formal variable s_formalVar.
g_expr1, g_expr2	Expressions to execute.
g_exprTable	Association table whose elements are to be processed.

Value Returned

l_valueList	Value of the second argument, g_exprList.
l_result	Return value of the s_mappingFunction if that is used. It is not necessarily the result of the last expression evaluated (it depends on the mapping function).
o_valueTable	Value of g_exprTable.

Examples

foreach( x '(1 2 3 4) println(x))

1                   ; Prints the numbers 1 through 4.
2
3
4
=> (1 2 3 4)        ; Returns the second argument to foreach.

The next example shows foreach accessing an association table and printing each key and its associated data.

foreach(key myTable printf("%L : %L\n" key myTable[key]))

The following is an example with more than one loop variable:

(foreach (x y) '(1 2 3) '(4 5 6) (println x+y))
5
7
9
=> (1 2 3)

Errors and Warnings

The error messages from foreach might at times appear cryptic because some foreach forms get expanded to call the mapping functions mapc, mapcar, mapcan, and so forth.

Advanced Usage

The foreach function typically expands to call mapc; however, you can also request that a specific mapping function be applied by giving the name of the mapping function as the first argument to foreach. Thus, foreach can be used as an extremely powerful tool to construct new lists.

Mapping functions are not accepted when this form is applied to association tables.

foreach( mapcar x '(1 2 3) (x >1))=> (nil t t) 
foreach( mapcan x '(1 2 3) if((x > 1) ncons(x))) => (2 3)
foreach( maplist x '(1 2 3) length(x)) => (3 2 1)

Related Topics

Flow Control Functions

Return to top