Tinderbox v9 Icon

Dictionary Data Type


A Dictionary attribute acts like a Tinderbox lookup table, pairing keys with values.

key: value; 

The key part comes first with a terminating colon. The value part follows, terminated by a semi-colon. White space handling in key:value pairs is described below.

Dictionaries are faster to construct, and large dictionaries are far faster to check, than lookup tables. Dictionaries are not intended for handing large/complex values or for values including punctuation and symbols. Generally, a Dictionary may be better for tasks previously configured using look-up lists.

Like other attribute types, a Dictionary follow normal rules of scope and inheritance. A note using a prototype with a Dictionary holding data, will inherit that data dictionary. Similar to a Set type, a Dictionary does not allow duplicate keys, but multiple keys may use the same value

Like other attributes, dictionaries follow normal rules of scope and inheritance. In the last example above, the values are set in the current note, but nowhere else. A note using a prototype with a dictionary holding data, will inherit that dictionary.

Dictionary key:value syntax

A dictionary collects pairs of strings separated by a colon. The first string is the key, and the second string is the value. The dictionary() operator creates a dictionary (in the current note), here with 3 such key:value pairs.

$MyDictionary=dictionary("cat:animal; dog:animal; rock: mineral"); 

The key "cat" has the value "animal", while the key "rock" has the value "mineral".

Although it is possible to populate a directory by passing to a Dictionary-type attribute a single string, containing a dictionary-formatted list, this is deprecated in favour of the dictionary() method. For example:

$MyDictionary="cat:animal; dog:animal; rock: mineral"; DEPRECATED method!

This has the same outcome as the previous example but is deprecated: using the dictionary() operator is explicit and indicates intent unambigously when parsed by Tinderbox.


A key is case-sensitive and must be unique to the dictionary; the value may be the same as values for different keys within the current dictionary. Rather like the Set data type, duplicates are weeded. If a new key:pair is added to a dictionary and the key (case-sensitively) already exists, the existing value (only) for that key is updated to use the value from the new pair.

$MyDictionary = dictionary("cat:animal; dog:animal; rock: mineral"); 

$MyDictionary = $MyDictionary + "cat:mammal"; 

Now, the value of key "cat" becomes "mammal" and the older value is lost.

Use of whitespace, symbols etc., with keys & values

Any whitespace either side of a colon (:), or semi-colon (;), or at beginning or end of dictionary data is ignored. Multi-word strings are allowed in both key and value, but do not treat this an invitation to place long strings there, such as placeholder texts. The design intent of dictionaries is that they are fast and light, so retrieval of more complex texts may better be handled by other methods.

The expectation is that keys and values will be simple strings or numbers, so avoid use of characters like punctuation as you may experience unexpected results. A good rule of thumb is to think hard if using other than A-za-z0-9 or underscore/hyphen/period (the period might be needed for a decimal number value)

Adding key:value pairs

To add to a new key:value pair, use addition, as with Lists and Sets…

$MyDictionary = $MyDictionary+"apple:plant"; 

adds they key "apple" and associates it with the value "plant". If the key was already found in the dictionary, its value is replaced by the new value. If the key was not found in the dictionary, both the new key and the new value are added.

Deleting key:value pairs

Entries can be deleted from a dictionary by subtracting the key:

$MyDictionary=dictionary("dog:animal; cat:animal; rock:mineral"); 

$MyDictionary=$MyDictionary-"dog"; // gives "cat:animal; rock:mineral" 

It is not possible to subtract a list of keys. Instead, such a list must be iterated as a succession of individual key deletions.

Changing the value of a key

New values may be assigned to specific dictionary keys.

$MyDictionary["apple"] = "pie" 

Adds the key "apple" to $MyDictionary with the value "pie". If the dictionary previously contained a value for "apple", it is replaced by "pie"; if not, a new key and a new value are added to the dictionary.

It is not possible to delete a key's value - i.e. have no value (which would anyway delete the purpose of the dictionary).

Merging Dictionaries

Dictionaries may be merged by adding them.

$MyDictionary = $MyDictionary+"apple:plant" 

adds they key "apple" and associates it with the value "plant". If the key was already found in the dictionary, its value is replaced by the new value. If the key was not found in the dictionary, both the new key and the new value are added.

It is possible to add two dictionaries.

$MyNewDictionary = $MyDictionary+$MyOtherDictionary 

Note that if the dictionaries share (case-sensitive) keys that have differing values, the values from the last-added, therefore those in $MyDictionary, will replace those in $MyDictionary. Thus:

$MyFirstDictionary = dictionary("apple:fruit; granite:mineral"); 

$MyOtherDictionary = dictionary("pear:fruit; granite:rock"); 

$MyDictionary = $MyFirstDictionary + $MyOtherDictionary; 

MyDictionary now contains "granite: rock; pear: fruit; apple: fruit" 

Note the order of dictionary items is re-ordered, reinforcing the point that additions/subtraction of dictionary data may alter item order, and which the user does not control. It is not possible to:

Splitting Dictionaries

As described above, subtraction is not possible with dictionaries, so splitting a Dictionary will require direct editing by the user.

Dictionary and values()

You can get the values of a Dictionary, but you cannot look up a key that corresponds to a given value. Remember, multiple keys may same value. Therefore, using values() with dictionaries is not recommended as this returns all the unique key:pair values as opposed to only keys or only values.

Iterating Dictionaries

Use Dictionary.keys to get a list of the keys and then iterate that list using List.each().