Operator Scope of Action:
Operator First Added:
List/Set.collect_if(label, condition, expression)
Each item in the list is bound in turn to label, and then the expression is evaluated.
label is essentially the same as the loop variable used by the List.each() operator. In the examples below, for clarity the label value "anItem" is used, but as with any loop variable a shorter less expressive values such a "x" can be used (e.g. by more expert users).
The condition argument is a conditional expression for which each tested item must return
The operator applies the action code expression to only those list items for which condition is
true. For only list items meeting condition, the result of expression on label is returned as List-type data. Unlike List/set.collect(), the returned list may well contain fewer items than the source list, unless all source items match condition.
If $MyList is "1;2;3;4;5", anItem, is 1, then 2, etc. For example:
$MyListA = $MyList.collect_if(anItem, anItem <3, anItem); returns 1;2 (only 2 of 5 source items match condition)
$MyListA = $MyList.collect_if(anItem, mod(anItem,2), anItem); returns 1;3;5 (only 3 of 5 source items match condition)
$MyListA = $MyList.collect_if(anItem, mod(anItem,2), anItem* anItem); returns 1;9;25 (only 3 of 5 source items match condition)
$MyListA = $MyList.collect_if(anItem, anItem>0, anItem* anItem); returns 1;4;9;16;25 (all 5 source items match condition)
In the first three examples above note how only some of the original 5 source list items are returned as some input items fail the the condition test. In the last example, as all 5 items are greater than zero (the condition) to the expression is applied to every one of them and all are returned.
If $MyList is "Winken;Blinken;Nod", then:
$MyListA = $MyList.collect_if(anItem, anItem.contains('i'),anItem.lowercase); returns "winken;blinken" (only 2 items are returned)
In the last example note how only 2 of the original 3 source list items are returned as the item "Nod" does not contain the letter 'i' and so fails the condition test.
List/Set.collect_if() vs. collect-if()
Although the two appear similar. This operator works directly on the source list values, whereas collect_if() creates a list of $Path values and returns on an attribute value from each of those paths (where the item at the $Path meets the condition).