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 you 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)

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)

 

Advanced Situation 1 - Dictionaries containing dictionaries:

Given three nested dictionaries where:

  • The root of dictionary X is dictionary Y
  • The root of dictionary Y is dictionary Z
  • The root of Z is the integer 42.

If you retrieve the root of x directly:

RVAL =  X[""];

Then, RVAL is now dictionary Y

 

If you were to use the RootValue() function instead:

RVAL = RootValue(X);

RVAL is now the integer 42

 

Advanced Situation 2 - Dictionaries with circular links:

Given three dictionaries as follows:

  • The root of dictionary X is dictionary Y.
  • The root of Y is dictionary Z.
  • The root of dictionary Z is a link back to dictionary Y.

If you apply the RootValue() function to dictionary X...

RVAL = RootValue(X);

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

Assignment operations involving dictionaries

When assigning a dictionary to a variable using the assignment operator (=) , the result is a pass-by-reference, effectively creating an alias for the dictionary rather than a copy.

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.

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.

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 an object is a dictionary:  

Rval  =  HasMetaData(variable);

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