Tinderbox v9 Icon

List/Set.collect_if(loopVar, condition, expressionStr)

Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Last Altered: 

Operator Has Conditional Arguments: 

Operator Uses Loop Variable Argument: 

List/Set.collect_if(loopVar, condition, expressionStr)

The dot-operator .collect_if() collects the members of a list that satisfy a condition. Each item in the list is bound in turn to loopVar, and then the expressionStr is evaluated.

loopVar is essentially the same as the loop variable used by the List.each() operator. In the examples below, for clarity the loopVar 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 true or false.

The operator applies the action code expressionStr to only those list items for which condition is true. For only list items meeting condition, the result of expressionStr on loopVar 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 expressionStr 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).