Dictionary Container (#dict) Commentary

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.