Dictionary Values

Value > Collections > Collection Types > Dictionary Values

Values and Collections - Quick Navigation

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:<bool> -- 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.

free <dictionary>

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