Function: forEach()

Iterates over an Array or Recordset and processes a script for each entry.

Syntax

forEach($var, set, script)

forEach() is like every other function in that it returns a value: 

• Its return value is a list containing the last statement executed in each iteration.
• All the $-variables used in the call to forEach() keep their values between iterations.
• All the $-variables used in the call to forEach() will be available after it has returned.

See also:

• Using $-variables in Calculations
• Multiline Statements and $-variables

Use in Conjunction With

• continue, will continue to the next item in the set.
• break, will break out of the forEach loop. 

Examples

In the first two examples, let

$numberList = [1,2,3,4,5,6,7,8,9,10]

forEach($number, $numberList, 

   $currentValue = $number*2

),

Returns [2,4,6,8,10,12,14,16,18,20], as forEach() returns the value of the final expression to be evaluated in each iteration.

do(
  forEach($number, $numberList,  
   $sumOfNumbers = $sumOfNumbers + $number
  ),
  $sumOfNumbers
)

Returns 55. The forEach will return the value at each iteration ([1, 3, 6, 10, 15, 21, 28, 36, 45, 55]), the do then returns the final value of $sumOfNumbers.

Detailed example: (step-by-step)

forEach( $customerType, customers.type, 

   $total = $total + 1, 

   if( $customerType == "Business", continue() ), 

   $nonBusiness = $nonBusiness + 1, 

   subString($customerType, 1, 6) 
)

All entries after the second parameter of the above forEach() comprise the script that will be processed for each entry in customers.type. Processing is as follows:

For each customer type in customers.type the following steps are taken:

1. Assign the value of the customer type to the $-Variable $customerType.
2. The first expression then increments the value of $total by 1 (i.e. counting the total number of types in the list).
3. The second expression checks if the type is "Business" and if so calls continue() which causes forEach() to immediately skip to the next customer type in customers.type and starts again from the first expression (i.e. it does not reach the 3rd expression to increment the $-Variable $nonBusiness).
4. If the type is not "Business" the third expression will be processed incrementing a count of the non-business types.
5. The final expression is evaluated and the result added to the result Array of the forEach() function.

The forEach() function above therefore returns an Array of the first 6 characters of each non business customer type in the supplied list. The values of $total (a count of all customer types), $nonBusiness (a count of all non-business customer types) and $customerType (the last customer type processed) will be available to subsequent Attribute Expressions for the current Stream Item calculation.

Commonly, you might not want to return a list from forEach(), but calculate some values in the loop to use later. For example, if you had an attribute TotalCustNumber, you might create an attribute expression:

do( 
   forEach( $customerType, customers.type, 

      $total = $total + 1, 
      if( $customerType == "Business", continue() ), 
      $nonBusiness = $nonBusiness + 1 
   ), 

   $total 
)

This would calculate the total number of customers (in $total) and write this value to the attribute.

Then the next attribute might be NonBusinessCustNumber, and you could write the number of non-business customers calculated in the loop to this attribute simply using the expression:

$nonBusiness

See Also

• Functions