Dictionary Operations

Operations involving dictionaries and other variables:

The result of any operation that uses a dictionary as one of the operands and a non-dictionary as the other will always take the root value of the dictionary as the value to be used for the operation.

Thus, if we use the dictionary from the preceding examples, having a root value of 5, the following would be true:

X = Dictionary(0,5); {X is a dictionary with a root value of 5 }

X["A"] = 42; {add a keyed value to the dictionary }

Y = 2;   

Z = X * Y; { the root value of X is used for the multiplication }

Z now holds the integer value, 10.

Accessing values in a dictionary:

Values within a dictionary can be accessed using an array-like syntax. The root value is accessed using empty quotation marks.

Examples:

(Using the dictionary X from the preceding example)

    Y  =  X[""];    { Y now holds the value  5 }

    Y  =  X["A"];   { Y now holds the value 42 }

Retrieving an array of the keys from a dictionary:

The function, ListKeys will return a one dimensional array of the keys stored in a dictionary

RVAL  =  ListKeys ( dictionary );

Example:

X =  Dictionary();

X["A"] = 15;

X["B"]  = 24;

RVAL = ListKeys ( X );

RVAL will now contain a two element array, containing the values "A" and "B".

Retrieving the root value from a dictionary:

The root value of a dictionary can be obtained by either of two methods:

Directly:                  Y =  X[""];    { where X is a dictionary }

Via a function:                   Y =  RootValue( X );

In general, the result will be identical, except for the case where the root value is another dictionary.  In such a case, RootValue will traverse the dictionaries until it finds the first root value that is not another dictionary.  (See example 1 below) 

In the case where all the root values are other dictionaries (a circle) then RootValue will return a dictionary, selecting the first root value after the one indicated in the command that points to an earlier value.  (See example 2 below)

 

Advanced Situation 1 – Dictionaries containing dictionaries:

 

The illustration to the right represents three dictionaries, where the dictionary Y is stored in the root of dictionary X and dictionary Z is stored in the root of dictionary Y.  The root of Z is the integer 42.

dictionary_chained_1.gifRetrieving the root of x directly:

RVAL =  X[""];

RVAL is now dictionary Y

Whereas, using the RootValue function:

RVAL = RootValue(X);

RVAL is now the integer 42

dictionary_chained_2.gif

Advanced Situation 2 – Dictionaries with circular links:

The illustration to the left represents three dictionaries, where the root of X is dictionary Y, the root of Y is dictionary Z. and the root of Z is a link back to dictionary Y.

 

Using the RootValue function:

RVAL = RootValue(X);

RVAL is now dictionary Y, that being the last root value found in the chain before it loops back to an earlier dictionary.  

Assignment operations involving dictionaries

The assignment operator (=) does a pass by reference rather than a pass by value.

Example:

X = Dictionary(); { create an empty dictionary }

    Y = X;            { assign it to Y }

    X["A"] = 42;      { create a node in X with key "A" & value 42 }

    Y["A"] == 42;     {  TRUE because Y is an alias for X }

 

A function exists to do a pass by value, allowing you to create a copy of a dictionary:

RVAL = DictionaryCopy( dictionary,  [deep],  [acyclic],  [lock]);

The three optional parameters, deep, acyclic and lock are each Boolean values with a default of FALSE.

Deep   … If true, all contained dictionaries are copied as well as the dictionary referred to by name.  Note that if Deep is set to FALSE, the copied dictionary will not be missing the contained dictionaries – the difference is that in one case, the contained dictionaries are copied as well as the base dictionary, and in the other, the copy of the base dictionary will also include the original, contained dictionaries.

Acyclic … If true, cyclic links are removed

Lock    … If true, all values in the copy will be locked as constants.

 

The results of Deep and Acyclic are described below:

dictionary_chained_2.gifRVAL = DictionaryCopy(X);

Rval contains a copy of dictionary X and the actual dictionaries Y and Z.

RVAL = DictionaryCopy(W, 1);

Rval contains copies all of dictionaries X, Y and Z.

RVAL = DictionaryCopy(W, 1, 1);

Rval contains copies of all the dictionaries, except that the link between the root value in Z and the dictionary Y will not be included.

Adding and Removing Keys

Keys and values can be added to a dictionary by simply referencing them like so:

X = Dictionary(); {  creates a new, empty dictionary }

X["A"]  =  42;        { adds a new key-value pair to dictionary X }

Keys and their associated values can be removed from a dictionary using the DictionaryRemove function as follows:

DictionaryRemove(dictionary, key);

The given key, specified in the second parameter, and its associated data will be removed from the given dictionary specified in parameter 1.

DictionaryRemove has no return value and no optional parameters.

 

Testing whether an object is a dictionary

Most operators and functions will treat a dictionary as if it were simply the variable stored as the root value. Attempting to use the ValueType() command on a dictionary will not work as expected for this reason, since if the dictionary has a root value, then only the value type of the root will be returned. 

The function HasMetaData will determine whether or not an object is a dictionary: 

Rval  =  HasMetaData(variable);

This function will return TRUE if the variable is a dictionary and FALSE otherwise.