Operator Scope of Action:
Operator First Added:
builds a set by collecting all the notes corresponding to group, testing each note to see if it meets condition, and adding the value of the designated attribute to the set.
collect_if() has modified behaviour. If the collected attribute type is multi-value, i.e. Set or a List type, collect() adds its elements to the result. If the collected attribute 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. The change should correct a variety of confusing edge cases.
group may be any group designator, or group defined by find(). In addition, group may be argument that designates a particular (single) note other than 'this'. collect_if() omits notes for which $Searchable is false.
condition is action code forming a valid conditional test, i.e. it equates to true when matched.
attribute can be any expression, but is typically an attribute's name.
$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().