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

Jump to the current version of aTbRef

Tinderbox 7 Icon

Set Data Type

Set

A Set is useful for lists of topics, categories, and tags. Sets are a special typeof string, within which discrete values are delimited by semicolons:

"astronomy;marine biology;chemistry" 

"dogs;cats" 

"cats" 

"3;9;15" 

"dog;9.66;15" 

"dogs;a big cat;lions" 

Note that the set is always string even if the values happen to be numbers. 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 is true 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. A default set value is an empty string. A set differs from a list in that duplicate values are not allowed.

To apply set values directly to a set-type attribute via the key 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 don't need to add enclosing quotes

If setting a set via action code note the string must the quoted:

$KeyAttributes="Width;Height;OnAdd"

Being based on a string, a set's value(s) - including the semicolons - can be up to 8191 characters in total.

With a set you can add/remove individual or multiple values and test its contents.

Adding and deleting values

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

$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

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.

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

Listing of Set-type system attributes.