This version is out of date, covering development from v6.0.0 to v6.6.5. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

TinderboxSix Icon

List Data Type

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

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 does not 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 does not 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

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

Listing of List-type system attributes.



A Tinderbox Reference File : Objects & Concepts : Concepts : Attributes : Attributes: Data Types : List Data Type