Operator Type:
Operator Scope of Action:
Operator Purpose:
Operator First Added:
Operator Last Altered:
Operator Uses Regular Expressions:
Operator Has Conditional Arguments:
Operator Has Newer Dot-Operator Variant:
Function [other Function type actions]
Conditional Group [operators of similar scope]
Dictionary, Set & List operations [other Dictionary, Set & List operations operators]
Baseline
As at baseline
[More on regular expressions in Tinderbox]
[More on scoped arguments in Action Code]
[More on conditional operator arguments]
Yes
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. a 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().