General:. The dictionary
container is a balanced binary tree designed for quick access by key.
Dictionaries contain associations. Dictionary associations are
unique keys with associated values.
Simple insertion illustration:
You create a dictionary object with the niladic #dict operator. You
save the created object by assignment into a variable. You then index
the value objects into that dictionary variable. The technique is the
same used for puting items into a vector with two differences. First, the slot
does not have to exist before using the index (key). Second, the index key does
not have to be an integer. With few exceptions, it can be any GLEE object.
Realisticly, keys should probably be numerics, strings, or sequences. If the
key doesn't exist, an association for it is added. If it exists, the value
replaces the existing value. With few exceptions, the value may be any
Glee object ... including another dictionary. You retrieve values
by indexing out of the dictionary. The result of indexing out is always
a sequence (usually a one item sequence). To use the result you usually
disclose ( < ) it. The :seq method returns the contents of
the dictionary as a sequence. This is good for debugging but you wouldn't want
to do it for a large dictionary or a dictionary persisted on a file. This
sequence object may also be assigned into an empty index to load a dictionary.
Overwriting and indexing out
values: A dictionary key has only one value. If you assign a different
value to the key, it replaces. If you index out a key which doesn't exist a
non-value object (NV) is returned in the resulting sequence. As illustrated
here, you can check for equality against any non-defined variable. You can also
check the object type to be 18 or the character string
"NoValue". Be sure to disclose the result ... it is always a
sequence corresponding to keys used in the indexing.
Vector operations: The
dictionary objects use intuitive rules for conformity. The best way to
determine if your intuition agrees with Glee is to experiment. If
your code is not ambiguous, Glee should do what you want
regardless.
Removing a key ( ~ the
without operator): Glee uses the familiar without
(~) operator to remove keys from the dictionary. If the key is found,
it is removed. If it is not found, it is quietly not removed. You can
test for successful removal by indexing with the removed key and checking for
the NV (non-value) object return.
Removing multiple keys:
Removing multiple keys works as you would expect with Glee. Just
be careful to be sure you have the right type, shape and depth of your keys. If
they don't match, the removal will not happen.
Bulk loading of a dictionary:The
contents of a complete dictionary may be obtained using the :seq
method. This result is a sequence of sequences. The inner sequence items are
pairs. The first item of a pair is the index. The second items is the value for
that index. If you assign such a structure into an empty index (e.g.
seq=>[]dict) you effectively bulk load the dictionary.