List-Type Attributes

List

A semi-colon delimited list of string values. 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 the Set-type pre-dates List-type in Tinderbox, Lists should be thought of as the underlying form and Sets as a type of List with special features (de-duplicated, always sorted, etc.).

List items can be read/set via their list order number (see below) but note that this is zero-based, i.e. list item #1 has address value zero (0).

A List, even a list of numbers or boolean values, is stored as a semi-colon delimited string, i.e. list items are not stored with an explicit data type, though multi-value value can be list or dictionaries.

In actions, + adds an item to a List if it is not already present, and -- removes it if it is present. These are now generally replaced by the += increment and -= (minus) decrement operators. Values should be enclosed in square brackets (previous, and still supported is to use enclosing double quotes).

Declaring a new List

If setting a List's literal values via action code use the square bracket [ ] List definition:

$MyList=[Frogs;Dogs;Logs];

Importantly, the bracket notation replaces the older now-deprecated legacy method of using enclosing quotes:

~~$MyList="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 List'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 would quotes) abut still honour brackets within the overall list value as implying a nested list. If Tinderbox reads from a List via code and reports (logs) a value with enclosing brackets, Tinderbox knows—in code—to ignore those as simply being list delimiters.

Adding new list items to the end of the List

With a List you can add/remove individual or multiple values and test its contents. A value added is inserted at the end of the existing list. Unlike a set-type, no deduplication occurs so adding a value a second time will create two entries. If $PetTypes' value is "cats;dogs", then:

$PetTypes+=[rabbits];

adds the new value to the end of the list, i.e. 'cats;dogs;rabbits', after which repeating the call

$PetTypes+=[rabbits];

this adds a second instance of "dogs" to the end of the List, i.e. 'cats;dogs;rabbits;rabbits'. This unlike a Set, were the second instance would be discarded as being a duplicate.

Adding new list items to the beginning of the List

To add new—not replacement—item(s) to the beginning of a list, add the existing value to the new list items:

$PetTypes=[rabbits;hamsters]+$PetTypes;

Legacy code note: the last fails if using to old quote-enclosed format instead of square brackets.

Adding an list item that is itself a list

To add a new item that is itself a list, note the extra set of brackets needed. The following adds a new list item whose value is a two-item list.

$PetTypes=$PetTypes+[[rabbits;bunnies]];

Adding items at a specific list position

To insert a new list at a specified location, i.e. adding a list item as opposed to replacing an existing value, iterate the list using List.each() with a custom counter. Store existing items in a new list and add the term when the loop reaches the desired place in the list. At the end of the loop write the new list back over the original List.

Deleting items

In actions using a - (minus) removes the supplied value(s) if present. Importantly, this removes all occurrences if the deleted item. If the List is 'cats;dogs;frogs':

$PetTypes=$PetTypes-[cats;frogs]; this leaves only 'dogs' as a value.

If there are multiple instances of the target item the first, by list order, is deleted. If the List is 'cats;dogs;cats;frogs':

$PetTypes=$PetTypes-[cats;frogs]; this leaves only 'dogs' as a value.

Replacing a list item's value

The List[N] notation addresses any single List item using a zero-based address. Thus List[1] addresses item #2, whilst List[0] addresses the first. To replace item #3 in a list (assuming a big enough list):

$MyList=[Frogs;Dogs;Logs];

$MyList[2]=[Pogs]; results in a list of "Frogs;Dogs;Pogs"

Additional list definition mark-up

Lists and Sets may be written by enclosing them in square brackets, rather than inside quotes, as in the past. The newer form is more declarative of intent to the user and the app, so is recommended. Lists may be nested; for example, the list

[ 1; [2;3]; 4]

contains a 3 elements — 1, the nested list 2;3, and 4.

Long Tinderbox precedent holds that list addition adds each element of the two lists. For example

$MyList = [1] + [2;3]

$MyList += [2;3]

both result in the list 1;2;3 and not 1;[2;3]. To add a sublist to a list, use the operator list.extend(). Thus:

$MyList = [1].extend( [2;3])

results in the list [1;[2;3]].

Offset assignment to a list of notes recognises bracket-enclosed lists correctly, for example:

$Status([this;parent])="urgent";

Implicit evaluation is no longer performed in bracketed lists. Thus,

$DisplayedAttributes=[MyList;MyString];

is now equivalent to

$DisplayedAttributes="MyList;MyString";

If new List terms need evaluation, use list() instead.

Accessing nested lists

Consider the following:

$MyTestList = [1;[a;b];3];

To retrieve the nested list:

$MyString = $MyTestList[1]; results in '[a;b]'

Note the square brackets are retrieved too, so for further use of the list this might be better:

$MyString = $MyTestList[1].substr(1,-1); results in '[a;b]'

To retrieve a value from that list:

$MyString = $MyTestList[1][1]; results in 'b'

De-duplicating a List: List vs. Sets

Lists, unlike Sets, allow duplicate values. To de-dupe a List, use the .unique dot-operator:

$MyList=$MyList.unique;

An older alternate method, which may be found in old demos is simply put its contents into a Set-type attribute:

$MySet=$MyList; (deprecated in favour of the method above)

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 does not add the duplicate value but the List attribute does. List data values are stored in the order added.

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") is true,

but

$PetTypes.contains("dog") is false

This is because Let/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

A query can test a single item from a list. For instance, if $MyList for note A is [3;4;5] and for note B is [1;5;10], then query:

$MyList[1]==$MyNumber(agent)

will match B but not A. This is because only B has the number 5 as the second list item ('1' in a zero-based list).

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!).

Listing and Exporting sets

The format() action operator and more recent .format() dot operator offer 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 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 $DisplayedAttributes 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.

Default/Empty value

An empty string.

Empty values in lists

From v11.6.0, lists now allow blank (empty) list items when using the [ ] list notation. As a result, a trailing semi-colon will imply the intent of a last list item that is empty.

Sorting order

Lists are not sorted, so retain the order in which items were passed into the list, most recent being at the end. Lists can be sorted using action code sort operators or by setting the sort attributes of containers.

List-type System Attributes

Built-in attributes of the List data type are listed below:

See also—notes linking to here: