List
A semi-colon delimited list of string values; new to v5.6.0. In terms of stored data sets and lists 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 sets pre-date lists in Tinderbox, lists should be thought of as the underlying form and sets as a refined - de-duplicated - form of list.
Being based on a string, a list's value(s) - including the semicolons - can be up to 8191 characters in total.
Lists, unlike Sets, allow duplicate values. To de-dupe a List, simply put its contents into a Set-type attribute:
$MySet=$MyList;
Or, from v5.9.2, use the .unique dot-operator:
$MyList=$MyList.unique;
If $MySet and $MyList both have the value "cats;dogs": the following have different outcomes:
$MySet=$MySet + "dogs" gives "cats;dogs"
$MyList=$MyList + "dogs" gives "cats;dogs;dogs"
The Set attribute doesn't add the duplicate value but the List does; list data values are stored in the order added. Be careful using this method to add a list value as if run in a rule, the terms will be re-added as a new value each time the rule runs!
Also beware an assumed pre-assignment concatenation:
$MyList=$MyList + "gun" + " " + "dogs" gives "cats;gun;dogs" not "cats;gun dogs"
Instead try:
$MyList=$MyList +( "gun" + " " + "dogs") gives "cats;gun dogs"
If setting a list's literal values via action code note the string must the quoted:
$MyList="Frogs;Dogs;Logs"
Adding and deleting values
With a list 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", then:
$PetTypes=$PetTypes+"rabbits" adds the new value
$PetTypes=$PetTypes+"rabbits" unlike a Set, this adds a second instance of "dogs" to the end of the list.
$PetTypes=$PetTypes-"dogs" leaves only "cats" 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 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") is true,
but
$PetTypes.contains("dog") is false
This is because set/list matching doesn't allow partial (regex) matches 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 pattern, 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 offers ways to turn sets into HTML lists for export. See Exporting Set-type data for more.
System Attributes - Sets vs. Lists
Most group-scope operators have been modified in v5.6.0 so that they can work with lists or sets, as well as the find() operator (whose own output is a list) and literal list-based group designators; exceptions include $KeyAttributes where duplicates would not be helpful. It is the declared data type of the attribute being collected that informs the operator to return a list or set.