Available in 3ds Max 2017.1 Update and higher: A Dictionary is a collection of key/value pairs, also known as an associative array. Keys can be of type name, string, or integer. For a given dictionary, the key type specified at the time of creation, and is always the same. The value can be of any type.

Dictionaries support iteration in a for loop, where each element is processed as a DataPair. Each DataPair contains the key as v1, the value as v2, the value1_name of #key, and value2_name of #value.

Example

d = Dictionary #(#ss, 1) #(#tt, 2)
for ele in d do print ele

Results

Dictionary #name ss:1 tt:2 
(DataPair key:#ss value:1)
(DataPair key:#tt value:2)
OK

The Dictionary value class can be specified in a persistent global variable. All values in the Dictionary must be specifiable as a persistent global variable in order for the Dictionary to be fully restored on scene file load.

Constructors

Dictionary() -- empty dictionary of type #name
Dictionary (#integer | #name | #string) -- empty dictionary of the specified type
Dictionary {#(key, value)}+ -- one or more two-value arrays
Dictionary {key:value}+ -- one or more explicit key:value pairs
Dictionary {(DataPair key value)} -- one or more DataPair objects

Dictionaries can be constructed using different types at once, for example with an array and a DataPair, but the key type must always be the same.

The default key type for a dictionary is #name. If the dictionary constructor uses DataPairs, the key type is the type of the first DataPair's key value. All remaining DataPairs must have the same key value type. If the dictionary constructor uses Arrays, the key type is the type of the first Array’s element 1 value. All remaining Arrays must have the same element 1 value type. If keyword arguments are used, their key type is #name. For dictionaries of type #integer, the actual key value type can be any of Integer, IntegerPtr, or Integer64, interchangeably.

Properties

<dictionary>.count : Integer, read-only

A count of items in the dictionary

<dictionary>.type read-only 

The type of the dictionary, which can be #name, #string, #integer.

<dictionary>.keys : Array, read-only

An array of the dictionary's keys. Note: changing this array does not affect the dictionary.

Operators

<dictionary>[key] 

Gets the value for key. If there is not an entry for the key, the value undefined is returned.

<dictionary>[key] = <value>

Sets the value for key. An existing entry does not need to exist for the key.

Methods

GetDictValue <dictionary> <key >

Gets a value from the dictionary based on key. If there is no entry for the key, a value of undefined is returned.

SetDictValue <dictionary> <key > <value>

Sets the value for an existing entry in dictionary based on key. If there is no entry for the key, nothing happens.

PutDictValue <dictionary> <key > <value> putOnlyIfNew:<boolean> -- defaults false

Puts a value in dictionary based on key.

If putOnlyIfNew is true, the value is added only if there is no existing entry for the key. If putOnlyIfNew is false, the value is added even if there is an existing entry for the key. If there is an entry, its value is set.

RemoveDictValue <dictionary> <key >

Removes the existing entry in the dictionary based on key. If there is no entry for the key, nothing happens.

HasDictValue <dictionary> <key >

Returns whether there is an existing entry in the dictionary for the given key.

GetDictKeys <dictionary>

Returns an array of key values in the dictionary.

GetDictKeyType <dictionary>

Returns the key type of the dictionary - #name, #string, or #integer.

copy <dictionary> [#nomap]

Creates a shallow copy of the dictionary. Note that unlike with other collection types, copy() always makes a shallow copy of Dictionaries, the #nomap option is not actually required.

deepCopy <dictionary> [copyAllValuesAsUnique:<boolean>]

Creates a deep copy of the dictionary. Available in 3ds Max 2019 and higher. The dictionary is recursively traversed, and new copies are generated of all items in the dictionary. Note that if the dictionary contains multiple references to a single value, the deep copy will contain multiple references to a single, new value.

The copyAllValuesAsUnique keyword parameter can be specified as true if you know that all members are unique. This can significantly improve the performance of the copy operation.

free <dictionary>

Frees the internal memory associated with the dictionary. This effectively removes all items from the dictionary.

deepEqual <dictionary> <dictionary>  [strictCompare:<bool>]

Performs a comparison of the elements in two dictionaries, and returns true if they have the same number of keys, the keys are the same type, and the key/value pairs compare as true.

The optional strictCompare keyword parameter specifies whether to compare without coercing the second element's value to the first element's value type. The default is false.

For example:

dict1 = Dictionary #("one",1) #("two",2)
dict2 = Dictionary #("one",1) #("two",2)
dict3 = Dictionary #("two",2) #("one",1)
dict1==dict2
--> false, not implemented for dictionaries
deepEqual dict1 dict2
--> true
deepEqual dict1 dict3
--> also true, order does not matter, dictionaries are unordered