collect_if(group,condition,attribute)

---

---

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

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