Tinderbox 8 Icon

collect_if(group,condition,attribute)


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,

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

will construct a set 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.



A Tinderbox Reference File : Actions & Rules : Operators : Full Operator List : collect_if(group,condition,attribute)