Dictionaries can be created by either of the 2 following methods:
Method 1: the Dictionary() function
X = Dictionary ([ case sensitive ], [ root ]);
Both parameters are optional. The first will default to 0 and the second to ‘invalid’.
The root can be any value, including another dictionary.
[case sensitive] is a Boolean.
Note: Once a dictionary contains a value, the case sensitive attribute cannot be changed.
Examples:
X = Dictionary();
X becomes a reference to a blank, empty dictionary that is not case sensitive
X = Dictionary(1, "rate");
X becomes a reference to a dictionary having a root value of "rate", that is not case sensitive
X = Dictionary(0, 42);
X becomes a reference to a dictionary having a root value of 42, and that is case sensitive.
Note: Whether or not a dictionary contains a root value has an impact on the result that the ValueType command will return from it. If there is a root value, then, in effect the dictionary serves to attach metadata to that existing variable and the ValueType command will return the value type of the root value. If there is no root value, then the ValueType command will return type 47 from the dictionary.
Method 2: The MetaData command
The command MetaData can be used for two different purposes. If used with a parameter that is not a dictionary, the result is to attach metadata to that object (thereby turning it into a dictionary).
MetaData(Dictionary, Key, [case sensitive]);
Example:
MetaData(X, "Width", 1) = 5;
X becomes a non-case sensitive dictionary having no root value and possessing one key named "Width" that has the associated value, 5.
More commonly, you would use this to attach extended information to an existing variable as shown in the following example:
Y = 10;
MetaData(Y, "Area") = 20;
In this example, Y starts as an integer and then becomes a non-case sensitive dictionary having a root value of 10 (the original value) and possessing one key named "Area" which initially has a value of 20.
You can even use this technique to turn an array into a dictionary – something that could not be done using method 2.
Z = New(5, 10);
MetaData(Z, "Rate", 0) = 42.7;
Z becomes a case sensitive dictionary having a root value which is the array [5, 10] and possessing one key named "Rate" which has a value of 42.7.