Tinderbox v9 Icon

collect(scope, expressionStr)

Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Last Altered: 

Operator Uses Scoped Arguments: 

Operator Has Newer Dot-Operator Variant: 

 Function  [other Function type actions]

 Group  [operators of similar scope]

 Dictionary, Set & List operations  [other Dictionary, Set & List operations operators]


 As at baseline

 [More on scoped arguments in Action Code]


collect(scope, expressionStr)

The function collect returns a List by collecting all the notes in scope (defining scope), and 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, more focussed, operator see collect_if().

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.

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(children,$Name); 

constructs a set with the name of each child of the note.

For example,

$MyList = collect(children(/agents/books),$Name); 

does the same for children of the note 'books' inside 'agents'.

$MyList = collect(children,$Width * $Height); 

collects a series of numerical values of each child's map icon height/width in Tinderbox map units. Thus if a child had a $Width of 4 and $Height of 2, the collect() result for that item would be 8.

If a list of unique values is required, i.e. set rather than a list, simply pass the output to a Set attribute. Thus if:

$MyList = collect(children,$FavFruit); $MyList is [Apples;Oranges;Pears;Apples]

$MySet = collect(children,$FavFruit); $MySet is [Apples;Oranges;Pears]

collect() vs. List/Set.collect()

For working with Lists or Sets of actual values, also see List/Set.collect().