VEX includes a dict datatype. Because VEX is strongly typed, it is difficult to work with parameter sets whose value and type will vary per parameter. The dict type provides a way to work with these.

The dict type will be considerably less efficient than expanding the dictionary as a variable per entry; so should only be used where the set of variables and types are varying.

The only dictionary literal supported is the empty dictionary: {}.

dict s = {};

To declare a dictionary variable, the general form is dict ‹var_name›:

// My string is a normal dictionary
dict   mydict;

To declare a function that returns a dictionary:

// A function which returns a dictionary
dict rgb_table()
{
...
};    

The index, or key, of a dictionary is always a string. The string can have any value, but for ease of processing it is recommended to avoid empty strings or strings with . in them.

The value of the dictionary can be most of the basic VEX types: int, float, vector2, vector, vector4, matrix2, matrix3, matrix, string, int[], float[], string[], dict, dict[].

Use dict[‹index›] to look up a value by its key in the dictionary.

The index is a string that is used to lookup the value. If they key isn’t in the dictionary, the result is a default-initialized value.

VEX requires type to be known at compile time, but the actual stored type may vary at run time. Thus you will often need an explicit function cast to select what type to extract. Where possible, the native type will be converted to the desired type.

dict dictionary;        // Create empty dictionary
dictionary['key'] = 3;        // Store 3 in the index key
float three = dictionary['key'];        // Extract key
dictionary['newkey'] = dictionary['key'];  // Error: Ambiguous type!
dictionary['newkey'] = int(dictionary['key']);  // Extract key as int and copy

The getcomp function can be used with a default argument to select the type and provide a different result if the key is missing. If it is present, but is the wrong type, the default initialization value is still used.

dict dictionary;
dictionary['key'] = 3;
int three = getcomp(dictionary, 'key', 52);
int fiftytwo = getcomp(dictionary, 'nonkey', 52);

The typeid function can be used to identify the dictionary value’s type. This id can be compared against the typeid() of a specific VEX data type, allowing you to take different code paths depending on the exact type of the value.

dict dictionary;
dictionary['key'] = set(1, 2, 3);

int value_type = typeid(dictionary, 'key');
if (value_type == typeid(vector()))
{
    // This code path is taken since the key has a 'vector' type.
    vector val = dictionary['key'];
    // ... do something with the vector value.
}
else if (value_type == typeid(vector4()))
{
    vector4 val = dictionary['key'];
    // ... do something with the vector4 value.
}

The contents of a key in one dictionary can be copied into another without exposing the type to VEX through the insert command. This can also be used to join two dictionaries together.

dict a, b;
a['key'] = 3;
b['oldkey'] = 5;
insert(b, 'newkey', a, 'key'); // Makes b['newkey'] == 3
insert(b, 'oldkey', a, 'nonkey'); // Removes b['oldkey'] as nonkey missing in a.
insert(b, a); // Adds all entries of a to b, overwriting on conflict.

Dictionaries can be built using the set command.

dict a;
a = set("key", 3.0, "nextkey", 5.0, "lastkey", "stringvalue");

The following functions let you query and manipulate dictionaries.