General:. The dictionary
container is a skip list 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.
Realistically, 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 of sequences (usually a one item sequence). To use the result you
usually double disclose ( < < ) it. Even though for a
dictionary, the inner sequences all contain just one element, for other objects
in this collection class (e.g. #idx and #bag), the inner
sequences may contain multiple items. I chose the unnecessary to maintain
consistency of access across all these collection classes. 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 the preexisting value. 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 (:typen) to
be 18 or the character type (:typec) to be
"NoValue". Be sure to double disclose the result ... it is
always a sequence of sequences 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 item is the value
sequence for that index. If you assign such a structure into an empty index
(e.g. seq=>[]dict) you effectively bulk load the dictionary.