Set
A Set date type is a special type of string, within which discrete values are delimited by semicolons. When defining a Set in code, use the conventions are described for the List data type.
In terms of stored data the Set and List list are the same: a string containing one or more semi-colon delimited items. The difference is in the way Tinderbox handles the two data types, as lists may contain duplicate items. Although the Set-type pre-dates List-type in Tinderbox, Lists should be thought of as the underlying form and Sets as a refined (de-duplicated) form of List.
A Set is useful for lists of topics, categories, and tags where duplication of listed items is not wanted:
[astronomy;marine biology;chemistry]
[dogs;cats]
[3;9;15]
Note that the Set is always a string even if the values happen to be numbers: item values in a Set do not have explicit data types. A Set can have a single value, e.g. the third example above. With a single value there is no need to add a final semicolon and the same holds for the last of multiple values. Tinderbox will not mind if you supply a semicolon there (or after the last of multiple values), it will just strip it off as it processes the data. The default Set value is an empty string. A Set-type differs from a List-type in that duplicate values are not allowed, and the list of values is always A–Z lexically sorted.
To apply values directly to a Set-type attribute via the Displayed Attributes or via Info view or via the Inspector's Quickstamp, simply type the values as seen into the data box. In all these methods, you do not need to add enclosing quotes, but each discrete value should be separated with a semi-colon.
Sets and auto-sorting
From v9, Set attributes were reimplemented to improve performance with large sets, which makes a Set more aggressive in asserting its control of the sequence of their elements. Compared to previous use, the stored order of items in the Set's value list are much more likely to change from the order as originally entered into case-sensitive lexical sort order. This may catch out long term users being used to Sets generally retaining their as-created item order. It the latter is needed, it may make more sense to use a List type instead.
Declaring a new Set
If setting a Set's literal values via action code use the square bracket [ ] List/Set definition:
$MySet=[Frogs;Dogs;Logs];
Above, the brackets replace the older now-deprecated method of enclosing quotes:
$MySet="Frogs;Dogs;Logs"; NOTE: do not use this for new code!
Whilst both methods work and the latter, older, method will be found in many demos and tutorials, the bracketed notation is now the preferred method.
Importantly, when typing/pasting a Set's values into a UI input box such as the Inspector, Get Info, or Displayed Attributes, the enclosing brackets or quotes (as used above) should be omitted, i.e. using planes;trains;automobiles not [planes;trains;automobiles]. If brackets are used by mistake, the Tinderbox parser should ignore an outmost pair (as it it would quotes) abut still honour brackets within the overall list value as implying a nested list. If Tinderbox reads from a Set via code and reports (logs) a value with enclosing brackets, Tinderbox knows—in code—to ignore those as simply being list delimiters.
Adding values
With a Set you can add/remove individual or multiple values and test its contents. In actions, + adds an item to a set if it is not already present, and -- removes it if it is present. Values must be enclosed in double quotes. If $PetTypes' value is "cats;dogs"
$PetTypes=$PetTypes+[dogs] leaves $PetTypes unchanged, since 'dogs' is already in $PetTypes
The += increment operator can also be used. If the Set is 'cats;dogs;frogs':
$PetTypes=$PetTypes+[owls;dogs]; the Set is 'cats;dogs;frogs;owls'.
Deleting values
In actions using a - (minus) removes the supplied value(s) if present. Importantly, this removes all occurrences if the deleted item;
$PetTypes=$PetTypes-[dogs]; leaves only 'cats' as a value.
The -= decrement operator can also be used. If the Set is 'cats;dogs;frogs':
$PetTypes=$PetTypes-[cats;frogs]; this leaves only 'dogs' as a value.
Testing (querying) Sets & Lists
To test a Set or List, use the .contains() operator, syntax AttributeName.contains("tested_value"), returns true if any set/list discrete value exactly matches the designated tested_value; if case sensitivity is irrelevant for the query use .icontains(). If a user attribute $PetTypes has a value of 'dogs;cats' then
$PetTypes.contains("dogs"); istrue,
but
$PetTypes.contains("dog"); is false
This is because Set/List matching does not allow partial matches, as via regex, unlike with String-type data.
Other variants:
$PetTypes.contains("Dogs").lowercase() is true
$PetTypes.icontains("DOGS") is true
It can be useful to use a stored value as the search term, for instance using the name of an agent as the search term:
$PetTypes.contains($MyString) is true
Listing and exporting Sets
The format() action operator, and newer .format() dot operator offer ways to turn sets into HTML lists for export. See Exporting Set-type data for more.
Set data vs. List data
List-type attributes came to Tinderbox after Sets. Lists, unlike Sets, allow duplicate values and Sets can better be thought of as de-duped versions of Lists, i.e. lists with no duplicate entries.
To de-dupe a List, simply put its contents into a Set-type attribute:
$MySet=$MyList;
Escaping literal semi-colons
If a list item must contain a semi-colon, it must be escaped, using a backslash, '\;'. Once the backslash is entered, it disappears and the list item containing the semi-colon is enclosed in double-quotes. Do not try to escape a value by adding the quotes directly, use the backslash method. Action code methods to make lists will treat a '\;' in an input string as an escape and act accordingly. Consider using String.replace() as a method for escaping backslashes (though only where intended!).
Default/Empty value
An empty string.
Sorting order
As for a String Data Type, using the literal string values of the Set in case-sensitive lexical sort order. For example, the 5-item of values 'Ant', 'ant', 'bee', 'Cow', 'cow' when passed to a set would store as "Ant;Cow;ant;bee;cow".
Set-type System Attributes
Built-in attributes of the set data type are listed below: