Dictionary
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 follows 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. A note using a prototype with a dictionary holding data, will inherit that dictionary.
A key may have multiple (semi-colon delimited values).
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.
Case-sensitivity
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; additionally avoid using parentheses (), square [] or curly {} brackets, backward \ and forward / slashes, single/double quotes or commas.
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. From v9.1.0, .add() can be used:
$MyDictionary.add("apple","pie");
Note that the += and -= operators are not currently available for changes to dictionary (numerical) values of the form
$MyDictionary["key"] += 1; WRONG!
Instead, use the conventional form:
$MyDictionary["key"] = $MyDictionary["key"] + 1;
Deleting the value of a key
It is not possible to delete a key's value - i.e. have no value (which would anyway defeat the purpose of the dictionary). In such a case remove the key.
Keys with multi-item values are not supported
Currently, a value cannot be a list. The value for a key 'pie' might reasonably be apple, lemon and quince. Whilst it is possible to define a dictionary like this:
$MyDictionary["pie"] = "apple;lemon;quince"
… the fact a semi-colon is used as both a list delimiter (within the value) and as a key:value pair delimiter, means Tinderbox currently does not know how to parse this; work is in hand to support multi-item value, i.e. lists.
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:
- subtract a dictionary from a dictionary
- subtract lists of keys
- subtract individual values
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().
Sorting order
Unspecified, likely as per List-type.
Dictionary-type Attributes