This version is out of date, covering development from v9.0.0 to v9.3.0. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon

List/Set.collect_if(label, condition, expression)

Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Altered: 

 Function   [other Function type actions]

 List   [operators of similar scope]

 Dictionary, Set & List operations   [other Dictionary, Set & List operations operators]



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 true or false.

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).

A Tinderbox Reference File : Actions & Rules : Operators : Full Operator List : List/Set.collect_if(label, condition, expression)