values([scope, ]attributeNameStr)

---

values([scope, ]attributeNameStr)

values(attributeNameStr)

This returns a Set of unique values for the attribute attributeNameStr. As the output is a of Set data type, the list of possible values is de-duped thus giving a list of unique values, and should be sorted. Any suggested values not actually used by at least one note are omitted from the list return by values().

If the named attributeNameStr is a set or list, values() returns a list of all the unique discrete list item values that occur. If the named attribute is a string, values() returns all the unique strings.

From v9.5.2, attributeNameStr is evaluated in case it is something like a variable holding the desired target attribute name. The change is that, if the argument is not an attribute name, and if the argument trimmed of its $ is still not an attribute name, we now see if the evaluated expression turns out to be an attribute name.

Important: unlike other operators, be aware that values($MyString) returns a list of values found for $MyString, not a list of the values of the attribute whose name is stored in $MyString. This is unique to values(), and arises because writing values($MyString) instead of values("MyString") was a very common mistake. If needing to pass a value holding an attribute name, use an action code variable and not as a value stored in another attribute.

The returned set is sorted in lexical order.

If a document has a user List-Type attribute $SomeList, then to get a a list of all the unique values for $SomeList in the whole document:

$MyList = values("SomeList"); 

The attributeNameStr argument is evaluated so may be:

• A quoted attribute name without $-prefix: values("MyList").
• A string attribute name, whose current value is the name of an attribute (without a dollar prefix). If $MyString has the value "MyList", then values($MyString) will evaluate the unique values for $MyList (and output the same result as values("MyList") above).
• An expression resolving to an attribute name.

Thus if the document has a user List-Type attribute $SomeList and $MyString has the value "SomeList", then these are functionally equivalent:

$MyList = values("SomeList"); 

$MyList = values($MyString); 

It is envisaged that the first method (the quoted, un-prefixed, attribute name) will be the most usual method of using values().

Sorting. The data is returned in case-sensitive lexical sort order (i.e. all capitals sort before lower case letters, and numbers sorting textually not numerically) so chaining .isort() may often be the desired 'default', or use .nsort() if the list is entirely composed of numbers. Assume, the intention is to get a note whose $Text has one value per line. It could be coded thus:

$Text=values("MyList").format("\n"); 

This is a very useful way of making a set of per-value notes. Use values() to collect the values, pass them to a note's $Text as a one-value-per-line string and then explode the $Text.

However, a value list of [aardvark;amber;Ant] would actually list in this order: [Ant;aardvark;amber]. That is due the Set's auto-sort using case-sensitive lexical sorting, whereas a case-insensitive sort would be more appropriate. Thus:

$Text=values("MyList").isort.format("\n"); 

Similarly the default sort would order 1/2/10 and 1/10/2, so a numerical sort would be more sensible:

$Text=values("MyList").isort.format("\n"); 

De-duplication. values() differs from collect() in that values() returns Set-type data and collect() returns List-type data. For a list $MyList, the following are functionally equivalent in output:

$MyList = collect(all,$SomeList).unique; 

$MyList = values("SomeList"); 

$MyList = values($MyString); (where $MyString has the value "SomeList")

values(scope, attributeNameStr)

If an optional first scope argument is provided, the value(s) returned are drawn only from notes in that scope (defining scope). If no first argument is supplied, as in the short form above, the default scope-defined group is assumed as 'all' and thus at whole document scope.The reference point for groups like 'children' or 'siblings' is this note. Thus:

$MyList = values(children,"Subtitle"); 

will return all the discrete subtitles (i.e. values of $Subtitle) for children of this note, i.e. the note in which context the action is being evaluated.