This version is out of date, covering development from v9.5.0 to v9.7.3. 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

collect_if(scope, condition, expressionStr)


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Last Altered: 

Operator Uses Regular Expressions: 

Operator Uses Scoped Arguments: 

Operator Has Conditional Arguments: 

Operator Has Newer Dot-Operator Variant: 


collect_if(group, condition, expressionStr)

The function collect_if() returns a List by collecting all the notes in scope (defining scope), testing each note in scope and ignoring it if it fails to meet condition, then adding the value of each list item evaluated using the designated expressionStr. Be aware that the per-item value might be a literal value, an attribute value, or a value/string of content based on that item's expressionStr.

For a related, less focussed, operator see collect().

scope may be any group designator, or group defined by find(). In addition, scope may be argument that designates a particular (single) note other than 'this' collect() omits notes for which $Searchable is false.

condition is action code forming a valid conditional test, i.e. it equates to true when matched.

expressionStr can be any expression, but is typically an attribute's name. If the collected per-item value type is multi-value, i.e. Set or a List type data , collect() adds its elements to the returned list. Thus if an item's evaluated value is a list of 3 terms, that item contributes 3 items to the operator's returned list rather than 1 item.

If the collected expressionStr is not a Set or List type attribute, but contains a semicolon, quotation mark, or parentheses, the value will be added to the result as a quoted string. This behaviour is designed correct a variety of confusing edge cases.

For example,

$MyList = collect_if(children,$Status=="Important",$Name); 

will construct a List of the names of all of this note's important children.

Note that collect_if's function is related to agents; many tasks you might perform with collect_if could be done as well, or better, with an agent. 

If a list of unique values is required, i.e. set rather than a list, simply pass the output to a Set attribute. Thus if:

$MyList = collect_if(children,$Age>6,$FavFruit); $MyList is [Apples;Oranges;Pears;Apples]

$MySet = collect(children,$Age>6,$FavFruit); $MySet is [Apples;Oranges;Pears] 

If the collected attribute is a set or a list, collect() adds its elements to the result. If the collected attribute is not a set or a list, but contains a semicolon, quotation mark, or parentheses, the value will be added to the result as a quoted string. This should avoid a variety of confusing edge case outcomes.

collect_if() resets its regular expression match list for each note it tests. Thus, $1 will be the first matched subexpression for this note, rather than the first matched subexpression for the entire collect_if() statement.

collect_if() vs. List/Set.collect_if()

For working with Lists or Sets of actual values, also see List/Set.collect_if().