Operator Type:
Operator Scope of Action:
Operator Purpose:
Operator First Added:
Operator Altered:
Function [other Function type actions]
Conditional Group [operators of similar scope]
Set & List operations [other Set & List operations operators]
Baseline
A function collect_if() builds a List; see collect() for a related new operator.
collect_if(group,condition,attribute)
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'.
condition is a valid conditional test, i.e. it equates to true when matched.
attribute can be any expression, but is typically an attribute.
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.