Dictionary

Max 5, introduced the t_dictionary structure/object. More...

+ Collaboration diagram for Dictionary:

Data Structures

struct  t_dictionary_entry
 A dictionary entry. More...
struct  t_dictionary
 The dictionary object. More...

Functions

t_dictionarydictionary_new (void)
 Create a new dictionary object.
t_max_err dictionary_appendlong (t_dictionary *d, t_symbol *key, t_atom_long value)
 Add a long integer value to the dictionary.
t_max_err dictionary_appendfloat (t_dictionary *d, t_symbol *key, double value)
 Add a double-precision float value to the dictionary.
t_max_err dictionary_appendsym (t_dictionary *d, t_symbol *key, t_symbol *value)
 Add a t_symbol* value to the dictionary.
t_max_err dictionary_appendatom (t_dictionary *d, t_symbol *key, t_atom *value)
 Add a t_atom* value to the dictionary.
t_max_err dictionary_appendstring (t_dictionary *d, t_symbol *key, const char *value)
 Add a C-string to the dictionary.
t_max_err dictionary_appendatoms (t_dictionary *d, t_symbol *key, long argc, t_atom *argv)
 Add an array of atoms to the dictionary.
t_max_err dictionary_appendatomarray (t_dictionary *d, t_symbol *key, t_object *value)
 Add an Atom Array object to the dictionary.
t_max_err dictionary_appenddictionary (t_dictionary *d, t_symbol *key, t_object *value)
 Add a dictionary object to the dictionary.
t_max_err dictionary_appendobject (t_dictionary *d, t_symbol *key, t_object *value)
 Add an object to the dictionary.
t_max_err dictionary_getlong (C74_CONST t_dictionary *d, t_symbol *key, t_atom_long *value)
 Retrieve a long integer from the dictionary.
t_max_err dictionary_getfloat (C74_CONST t_dictionary *d, t_symbol *key, double *value)
 Retrieve a double-precision float from the dictionary.
t_max_err dictionary_getsym (C74_CONST t_dictionary *d, t_symbol *key, t_symbol **value)
 Retrieve a t_symbol* from the dictionary.
t_max_err dictionary_getatom (C74_CONST t_dictionary *d, t_symbol *key, t_atom *value)
 Copy a t_atom from the dictionary.
t_max_err dictionary_getstring (C74_CONST t_dictionary *d, t_symbol *key, const char **value)
 Retrieve a C-string pointer from the dictionary.
t_max_err dictionary_getatoms (C74_CONST t_dictionary *d, t_symbol *key, long *argc, t_atom **argv)
 Retrieve the address of a t_atom array of in the dictionary.
t_max_err dictionary_copyatoms (C74_CONST t_dictionary *d, t_symbol *key, long *argc, t_atom **argv)
 Retrieve copies of a t_atom array in the dictionary.
t_max_err dictionary_getatomarray (C74_CONST t_dictionary *d, t_symbol *key, t_object **value)
 Retrieve a t_atomarray pointer from the dictionary.
t_max_err dictionary_getdictionary (C74_CONST t_dictionary *d, t_symbol *key, t_object **value)
 Retrieve a t_dictionary pointer from the dictionary.
t_max_err dictionary_get_ex (t_dictionary *d, t_symbol *key, long *ac, t_atom **av, char *errstr)
 Retrieve the address of a t_atom array of in the dictionary within nested dictionaries.
t_max_err dictionary_getobject (C74_CONST t_dictionary *d, t_symbol *key, t_object **value)
 Retrieve a t_object pointer from the dictionary.
long dictionary_entryisstring (C74_CONST t_dictionary *d, t_symbol *key)
 Test a key to set if the data stored with that key contains a t_string object.
long dictionary_entryisatomarray (C74_CONST t_dictionary *d, t_symbol *key)
 Test a key to set if the data stored with that key contains a t_atomarray object.
long dictionary_entryisdictionary (C74_CONST t_dictionary *d, t_symbol *key)
 Test a key to set if the data stored with that key contains a t_dictionary object.
long dictionary_hasentry (C74_CONST t_dictionary *d, t_symbol *key)
 Test a key to set if it exists in the dictionary.
t_atom_long dictionary_getentrycount (C74_CONST t_dictionary *d)
 Return the number of keys in a dictionary.
t_max_err dictionary_getkeys (C74_CONST t_dictionary *d, long *numkeys, t_symbol ***keys)
 Retrieve all of the key names stored in a dictionary.
void dictionary_freekeys (t_dictionary *d, long numkeys, t_symbol **keys)
 Free memory allocated by the dictionary_getkeys() method.
t_max_err dictionary_deleteentry (t_dictionary *d, t_symbol *key)
 Remove a value from the dictionary.
t_max_err dictionary_chuckentry (t_dictionary *d, t_symbol *key)
 Remove a value from the dictionary without freeing it.
t_max_err dictionary_clear (t_dictionary *d)
 Delete all values from a dictionary.
void dictionary_funall (t_dictionary *d, method fun, void *arg)
 Call the specified function for every entry in the dictionary.
t_symboldictionary_entry_getkey (t_dictionary_entry *x)
 Given a t_dictionary_entry*, return the key associated with that entry.
void dictionary_entry_getvalue (t_dictionary_entry *x, t_atom *value)
 Given a t_dictionary_entry*, return the value associated with that entry.
void dictionary_entry_getvalues (t_dictionary_entry *x, long *argc, t_atom **argv)
 Given a t_dictionary_entry*, return the values associated with that entry.
t_max_err dictionary_copyunique (t_dictionary *d, t_dictionary *copyfrom)
 Given 2 dictionaries, copy the keys unique to one of the dictionaries to the other dictionary.
t_max_err dictionary_getdeflong (t_dictionary *d, t_symbol *key, t_atom_long *value, t_atom_long def)
 Retrieve a long integer from the dictionary.
t_max_err dictionary_getdeffloat (t_dictionary *d, t_symbol *key, double *value, double def)
 Retrieve a double-precision float from the dictionary.
t_max_err dictionary_getdefsym (t_dictionary *d, t_symbol *key, t_symbol **value, t_symbol *def)
 Retrieve a t_symbol* from the dictionary.
t_max_err dictionary_getdefatom (t_dictionary *d, t_symbol *key, t_atom *value, t_atom *def)
 Retrieve a t_atom* from the dictionary.
t_max_err dictionary_getdefstring (t_dictionary *d, t_symbol *key, const char **value, char *def)
 Retrieve a C-string from the dictionary.
t_max_err dictionary_getdefatoms (t_dictionary *d, t_symbol *key, long *argc, t_atom **argv, t_atom *def)
 Retrieve the address of a t_atom array of in the dictionary.
t_max_err dictionary_copydefatoms (t_dictionary *d, t_symbol *key, long *argc, t_atom **argv, t_atom *def)
 Retrieve copies of a t_atom array in the dictionary.
t_max_err dictionary_dump (t_dictionary *d, long recurse, long console)
 Print the contents of a dictionary to the Max window.
t_max_err dictionary_copyentries (t_dictionary *src, t_dictionary *dst, t_symbol **keys)
 Copy specified entries from one dictionary to another.
t_dictionarydictionary_sprintf (C74_CONST char *fmt,...)
 Create a new dictionary populated with values using a combination of attribute and sprintf syntax.
t_max_err dictionary_read (char *filename, short path, t_dictionary **d)
 Read the specified JSON file and return a t_dictionary object.
t_max_err dictionary_write (t_dictionary *d, char *filename, short path)
 Serialize the specified t_dictionary object to a JSON file.
t_max_err dictionary_read_yaml (const char *filename, const short path, t_dictionary **d)
 Read the specified YAML file and return a t_dictionary object.
t_max_err dictionary_write_yaml (const t_dictionary *d, const char *filename, const short path)
 Serialize the specified t_dictionary object to a YAML file.
void postdictionary (t_object *d)
 Print the contents of a dictionary to the Max window.

Detailed Description

Max 5, introduced the t_dictionary structure/object.

This is used for object prototypes, object serialization, object constructors, and many other tasks. A dictionary is ultimately a collection of atom values assigned to symbolic keys. In addition to primitive A_LONG, A_FLOAT, and A_SYM atom types, the A_OBJ atom type is used for t_atomarray (for a set of atoms assigned to a key), t_dictionary (for hierarhical use), t_string (for large blocks of text which we don't wish to bloat the symbol table), and potentially other object data types. Internally, the dictionary object uses a combination data structure of a hash table (for fast key lookup) and a linked-list (to maintain ordering of information within the dictionary).

Dictionaries are clonable entites, but note that all the member objects of a given dictionary may not be clonable. At the time of this writing, for example, the t_string object is not clonable, though it will be made clonable in the near future. In order for prototype entities to be g uaranteed their passage into the constructor, they must be clonable (currenlty a symbol conversion is in place for the t_string class).

Using Dictionaries

Dictionaries are used in many places in Max 5. They can be confusing in many respects. It is easy to produce memory leaks or bugs where objects are freed twice. It is easy to confuse what type of dictionary is used for what. This page will begin with some high level information to help understand when to free and when not to free. Then, we will offer recipies for using dictionaries to accomplish common tasks.

Understanding Dictionaries

A dictionary stores atom values under named key entries. These atoms can contain A_OBJ values. When the dictionary is freed, any A_OBJ values that are in the dictionary will also be freed. Thus, it is easy to mistakenly free objects twice, thus this is something to be careful about. For example, look at this code:

    t_dictionary *d = dictionary_new(); 
    t_dictionary *sd = dictionary_new();  
    dictionary_appenddictionary(d, gensym("subdictionary"), sd); 
    do_something(d);
    object_free(d);  // this will free *both* d and sd since sd is contained by d
    // freeing "sd" here would be bad

You primarily need to keep this in mind when calling dictionary_appendobject(), dictionary_appenddictionary(), or dictionary_appendatomarray(). So, what do you do if you need to free a dictionary but you also want to hang on to an object that is inside of the dictionary? In this case, chuck the entry in question first. For example, let's assume that for some reason you cannot free the "sd" dictionary in the code above. Perhaps it doesn't belong to you. But, to do some operation you need to append it to a new dictionary. Then, do this:

    void function_foo(t_dictionary *sd) {
      t_dictionary *d = dictionary_new(); 
      dictionary_appenddictionary(d, gensym("subdictionary"), sd); 
      do_something(d); 
      dictionary_chuckentry(d, gensym("subdictionary")); 
      object_free(d);  
    }

When to Free a Dictionary

So, how do you know when you need to free a dictionary? Well, generally if you make a dictionary, you need to free it when you are done (unless you transfer ownership of the dictionary to someone else). On the other hand, if you are passed a dictionary (i.e. as a parameter of your function or method) then it is not yours to free and you should just use it. However, it is not always obvious that you made a dictionary vs just borrowed it.

Here are some common (and not so common) ways to make a dictionary. These functions return a new dictionary and thus the dictionary you get should be freed when you are done, unless you pass the dictionary on to someone else who will free it at an appropriate time. Here they are:

Here are some functions that return borrowed dictionaries. These are dictionaries that you can use but you cannot free since you do not own them. Here they are:

Finally, most functions that accept dictionaries as parameters will not assume ownership of the dictionary. Usually the way ownership is assumed is if you add a dictionary as a subdictionary to a dictionary that you do not own. One exception is the utility newobject_fromdictionary_delete() who's name makes it clear that the dictionary will be deleted after calling the function.

Some Common Uses of Dictionaries

You can make a patcher by passing a dictionary to object_new_typed() when making a "jpatcher". Using atom_setparse() and attr_args_dictionary() makes this relatively easy.

Use newobject_sprintf() to programmatically make an object in a patch. Actually, you don't explicitly use a dictionary here! If you do want more control, so you can touch the dictionary to customize it, then see the next bullet.

Use dictionary_sprintf() to make a dictionary to specify a box (i.e. specify class with @maxclass attr). Then, make another dictionary and append your box dictionary to it under the key "box" via dictionary_appenddictionary(). Finally, make your object with newobject_fromdictionary().

See also:
Linked List
Hash Table
Version:
5.0

Function Documentation

t_max_err dictionary_appendatom ( t_dictionary d,
t_symbol key,
t_atom value 
)

Add a t_atom* value to the dictionary.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
valueThe new value to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_appendatomarray ( t_dictionary d,
t_symbol key,
t_object value 
)

Add an Atom Array object to the dictionary.

Note that from this point on that you should not free the t_atomarray*, because the atomarray is now owned by the dictionary, and freeing the dictionary will free the atomarray as discussed in When to Free a Dictionary.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
valueThe new value to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_appendatoms ( t_dictionary d,
t_symbol key,
long  argc,
t_atom argv 
)

Add an array of atoms to the dictionary.

Internally these atoms will be copied into a t_atomarray object, which will be appended to the dictionary with the given key.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
argcThe number of atoms to append to the dictionary.
argvThe address of the first atom in the array to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_appenddictionary ( t_dictionary d,
t_symbol key,
t_object value 
)

Add a dictionary object to the dictionary.

Note that from this point on that you should not free the t_dictionary* that is being added, because the newly-added dictionary is now owned by the dictionary to which it has been added, as discussed in When to Free a Dictionary.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
valueThe new value to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_appendfloat ( t_dictionary d,
t_symbol key,
double  value 
)

Add a double-precision float value to the dictionary.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
valueThe new value to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_appendlong ( t_dictionary d,
t_symbol key,
t_atom_long  value 
)

Add a long integer value to the dictionary.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
valueThe new value to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_appendobject ( t_dictionary d,
t_symbol key,
t_object value 
)

Add an object to the dictionary.

Note that from this point on that you should not free the t_object* that is being added, because the newly-added object is now owned by the dictionary to which it has been added, as discussed in When to Free a Dictionary.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
valueThe new value to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_appendstring ( t_dictionary d,
t_symbol key,
const char *  value 
)

Add a C-string to the dictionary.

Internally this uses the t_symbol object. It is useful to use the t_string in dictionaries rather than the t_symbol to avoid bloating Max's symbol table unnecessarily.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
valueThe new value to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_appendsym ( t_dictionary d,
t_symbol key,
t_symbol value 
)

Add a t_symbol* value to the dictionary.

Parameters:
dThe dictionary instance.
keyThe name of the key used to index the new value. All keys must be unique. If the key name already exists, then the existing value associated with the key will be freed prior to the new value's assignment.
valueThe new value to append to the dictionary.
Returns:
A Max error code.
t_max_err dictionary_chuckentry ( t_dictionary d,
t_symbol key 
)

Remove a value from the dictionary without freeing it.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to delete.
Returns:
A max error code.
See also:
dictionary_deleteentry()
t_max_err dictionary_clear ( t_dictionary d)

Delete all values from a dictionary.

This method will free the objects in the dictionary. If freeing the objects is inappropriate or undesirable then you should iterate through the dictionary and use dictionary_chuckentry() instead.

Parameters:
dThe dictionary instance.
Returns:
A max error code.
See also:
dictionary_getkeys()
dictionary_chuckentry()
dictionary_deleteentry()
t_max_err dictionary_copyatoms ( C74_CONST t_dictionary d,
t_symbol key,
long *  argc,
t_atom **  argv 
)

Retrieve copies of a t_atom array in the dictionary.

The retrieved pointer of t_atoms in the dictionary has memory allocated and copied to it from within the function. You are responsible for freeing it with sysmem_freeptr().

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
argcThe address of a variable to hold the number of atoms in the array.
argvThe address of a variable to hold a pointer to the first atom in the array. You should initialize this pointer to NULL prior to passing it to dictionary_copyatoms().
Returns:
A Max error code.
See also:
dictionary_getatoms()
t_max_err dictionary_copydefatoms ( t_dictionary d,
t_symbol key,
long *  argc,
t_atom **  argv,
t_atom def 
)

Retrieve copies of a t_atom array in the dictionary.

The retrieved pointer of t_atoms in the dictionary has memory allocated and copied to it from within the function. You are responsible for freeing it with sysmem_freeptr(). If the named key doesn't exist, then copy a default array of atoms, specified as a t_atomarray*.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
argcThe address of a variable to hold the number of atoms in the array.
argvThe address of a variable to hold a pointer to the first atom in the array. You should initialize this pointer to NULL prior to passing it to dictionary_copyatoms().
defThe default values specified as an instance of the t_atomarray object.
Returns:
A Max error code.
See also:
dictionary_getdefatoms()
dictionary_copyatoms()
t_max_err dictionary_copyentries ( t_dictionary src,
t_dictionary dst,
t_symbol **  keys 
)

Copy specified entries from one dictionary to another.

Parameters:
srcThe source dictionary from which to copy entries.
dstThe destination dictionary to which the entries will be copied.
keysThe address of the first of an array of t_symbol* that specifies which keys to copy.
Returns:
A Max error code.
See also:
dictionary_copyunique()
t_max_err dictionary_copyunique ( t_dictionary d,
t_dictionary copyfrom 
)

Given 2 dictionaries, copy the keys unique to one of the dictionaries to the other dictionary.

Parameters:
dA dictionary instance. This will be the destination for any values that are copied.
copyfromA dictionary instance from which we will copy any values with unique keys.
Returns:
A Max error code.
See also:
dictionary_copyentries()
t_max_err dictionary_deleteentry ( t_dictionary d,
t_symbol key 
)

Remove a value from the dictionary.

This method will free the object in the dictionary. If freeing the object is inappropriate or undesirable, use dictionary_chuckentry() instead.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to delete.
Returns:
A max error code.
See also:
dictionary_chuckentry()
dictionary_clear()
t_max_err dictionary_dump ( t_dictionary d,
long  recurse,
long  console 
)

Print the contents of a dictionary to the Max window.

Parameters:
dThe dictionary instance.
recurseIf non-zero, the dictionary will be recursively unravelled to the Max window. Otherwise it will only print the top level.
consoleIf non-zero, the dictionary will be posted to the console rather than the Max window. On the Mac you can view this using Console.app. On Windows you can use the free DbgView program which can be downloaded from Microsoft.
Returns:
A Max error code.
t_symbol* dictionary_entry_getkey ( t_dictionary_entry x)

Given a t_dictionary_entry*, return the key associated with that entry.

Parameters:
xThe dictionary entry.
Returns:
The key associated with the entry.
See also:
dictionary_entry_getvalue()
dictionary_funall()
void dictionary_entry_getvalue ( t_dictionary_entry x,
t_atom value 
)

Given a t_dictionary_entry*, return the value associated with that entry.

Parameters:
xThe dictionary entry.
valueThe address of a t_atom to which the value will be copied.
See also:
dictionary_entry_getkey()
dictionary_funall()
void dictionary_entry_getvalues ( t_dictionary_entry x,
long *  argc,
t_atom **  argv 
)

Given a t_dictionary_entry*, return the values associated with that entry.

Parameters:
xThe dictionary entry.
argcThe length of the returned t_atom vector.
argvThe address of a t_atom vector to which the values will be copied.
See also:
dictionary_entry_getkey()
dictionary_funall()
long dictionary_entryisatomarray ( C74_CONST t_dictionary d,
t_symbol key 
)

Test a key to set if the data stored with that key contains a t_atomarray object.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to test.
Returns:
Returns true if the key contains a t_atomarray, otherwise returns false.
long dictionary_entryisdictionary ( C74_CONST t_dictionary d,
t_symbol key 
)

Test a key to set if the data stored with that key contains a t_dictionary object.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to test.
Returns:
Returns true if the key contains a t_dictionary, otherwise returns false.
long dictionary_entryisstring ( C74_CONST t_dictionary d,
t_symbol key 
)

Test a key to set if the data stored with that key contains a t_string object.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to test.
Returns:
Returns true if the key contains a t_string, otherwise returns false.
void dictionary_freekeys ( t_dictionary d,
long  numkeys,
t_symbol **  keys 
)

Free memory allocated by the dictionary_getkeys() method.

Parameters:
dThe dictionary instance.
numkeysThe address of a long where the number of keys retrieved will be set.
keysThe address of the first of an array t_symbol pointers where the retrieved keys will be set.
Returns:
A max error code.
See also:
dictionary_getkeys()
void dictionary_funall ( t_dictionary d,
method  fun,
void *  arg 
)

Call the specified function for every entry in the dictionary.

Parameters:
dThe dictionary instance.
funThe function to call, specified as function pointer cast to a Max method.
argAn argument that you would like to pass to the function being called.
Remarks:
The dictionary_funall() method will call your function for every entry in the dictionary. It will pass both a pointer to the t_dictionary_entry, and any argument that you provide. The following example shows a function that could be called by dictionary_funall().
    void my_function(t_dictionary_entry *entry, void* my_arg)
    {
        t_symbol    *key;
        t_atom      value;
        
        key = dictionary_entry_getkey(entry);
        dictionary_entry_getvalue(entry, &value);
        
        // do something with key, value, and my_arg...
    }
See also:
dictionary_entry_getkey()
dictionary_entry_getvalue()
t_max_err dictionary_get_ex ( t_dictionary d,
t_symbol key,
long *  ac,
t_atom **  av,
char *  errstr 
)

Retrieve the address of a t_atom array of in the dictionary within nested dictionaries.

The address can index into nested dictionaries using the '::' operator. For example, the key "field::subfield" will look for the value at key "field" and then look for the value "subfield" in the value found at "field".

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
acThe number of return values
avThe return values
errstrAn error message if an error code was returned.
Returns:
A Max error code.
t_max_err dictionary_getatom ( C74_CONST t_dictionary d,
t_symbol key,
t_atom value 
)

Copy a t_atom from the dictionary.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
Returns:
A Max error code.
t_max_err dictionary_getatomarray ( C74_CONST t_dictionary d,
t_symbol key,
t_object **  value 
)

Retrieve a t_atomarray pointer from the dictionary.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
Returns:
A Max error code.
t_max_err dictionary_getatoms ( C74_CONST t_dictionary d,
t_symbol key,
long *  argc,
t_atom **  argv 
)

Retrieve the address of a t_atom array of in the dictionary.

The retrieved pointer references the t_atoms in the dictionary. To fetch a copy of the t_atoms from the dictionary, use dictionary_copyatoms().

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
argcThe address of a variable to hold the number of atoms in the array.
argvThe address of a variable to hold a pointer to the first atom in the array.
Returns:
A Max error code.
See also:
dictionary_copyatoms()
t_max_err dictionary_getdefatom ( t_dictionary d,
t_symbol key,
t_atom value,
t_atom def 
)

Retrieve a t_atom* from the dictionary.

If the named key doesn't exist, then return a specified default value.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
defThe default value to return in the absence of the key existing in the dictionary.
Returns:
A Max error code.
See also:
dictionary_getatom()
t_max_err dictionary_getdefatoms ( t_dictionary d,
t_symbol key,
long *  argc,
t_atom **  argv,
t_atom def 
)

Retrieve the address of a t_atom array of in the dictionary.

The retrieved pointer references the t_atoms in the dictionary. To fetch a copy of the t_atoms from the dictionary, use dictionary_copyatoms(). If the named key doesn't exist, then return a default array of atoms, specified as a t_atomarray*.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
argcThe address of a variable to hold the number of atoms in the array.
argvThe address of a variable to hold a pointer to the first atom in the array.
defThe default values specified as an instance of the t_atomarray object.
Returns:
A Max error code.
See also:
dictionary_getatoms()
dictionary_copydefatoms()
t_max_err dictionary_getdeffloat ( t_dictionary d,
t_symbol key,
double *  value,
double  def 
)

Retrieve a double-precision float from the dictionary.

If the named key doesn't exist, then return a specified default value.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
defThe default value to return in the absence of the key existing in the dictionary.
Returns:
A Max error code.
See also:
dictionary_getfloat()
t_max_err dictionary_getdeflong ( t_dictionary d,
t_symbol key,
t_atom_long value,
t_atom_long  def 
)

Retrieve a long integer from the dictionary.

If the named key doesn't exist, then return a specified default value.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
defThe default value to return in the absence of the key existing in the dictionary.
Returns:
A Max error code.
See also:
dictionary_getlong()
t_max_err dictionary_getdefstring ( t_dictionary d,
t_symbol key,
const char **  value,
char *  def 
)

Retrieve a C-string from the dictionary.

If the named key doesn't exist, then return a specified default value.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
defThe default value to return in the absence of the key existing in the dictionary.
Returns:
A Max error code.
See also:
dictionary_getstring()
t_max_err dictionary_getdefsym ( t_dictionary d,
t_symbol key,
t_symbol **  value,
t_symbol def 
)

Retrieve a t_symbol* from the dictionary.

If the named key doesn't exist, then return a specified default value.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
defThe default value to return in the absence of the key existing in the dictionary.
Returns:
A Max error code.
See also:
dictionary_getsym()
t_max_err dictionary_getdictionary ( C74_CONST t_dictionary d,
t_symbol key,
t_object **  value 
)

Retrieve a t_dictionary pointer from the dictionary.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
Returns:
A Max error code.
t_atom_long dictionary_getentrycount ( C74_CONST t_dictionary d)

Return the number of keys in a dictionary.

Parameters:
dThe dictionary instance.
Returns:
The number of keys in the dictionary.
t_max_err dictionary_getfloat ( C74_CONST t_dictionary d,
t_symbol key,
double *  value 
)

Retrieve a double-precision float from the dictionary.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
Returns:
A Max error code.
t_max_err dictionary_getkeys ( C74_CONST t_dictionary d,
long *  numkeys,
t_symbol ***  keys 
)

Retrieve all of the key names stored in a dictionary.

The numkeys and keys parameters should be initialized to zero. The dictionary_getkeys() method will allocate memory for the keys it returns. You are then responsible for freeing this memory using dictionary_freekeys(). You must use dictionary_freekeys(), not some other method for freeing the memory.

Parameters:
dThe dictionary instance.
numkeysThe address of a long where the number of keys retrieved will be set.
keysThe address of the first of an array t_symbol pointers where the retrieved keys will be set.
Returns:
A max error code.
Remarks:
The following example demonstrates fetching all of the keys from a dictionary named 'd' in order to iterate through each item stored in the dictionary.
    t_symbol    **keys = NULL;
    long        numkeys = 0;
    long        i;
    t_object    *anItem;

    dictionary_getkeys(d, &numkeys, &keys);
    for(i=0; i<numkeys; i++){
        // do something with the keys...
    }
    if(keys)
        dictionary_freekeys(d, numkeys, keys);
See also:
dictionary_freekeys()
t_max_err dictionary_getlong ( C74_CONST t_dictionary d,
t_symbol key,
t_atom_long value 
)

Retrieve a long integer from the dictionary.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
Returns:
A Max error code.
t_max_err dictionary_getobject ( C74_CONST t_dictionary d,
t_symbol key,
t_object **  value 
)

Retrieve a t_object pointer from the dictionary.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
Returns:
A Max error code.
t_max_err dictionary_getstring ( C74_CONST t_dictionary d,
t_symbol key,
const char **  value 
)

Retrieve a C-string pointer from the dictionary.

The retrieved pointer references the string in the dictionary, it is not a copy.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
Returns:
A Max error code.
t_max_err dictionary_getsym ( C74_CONST t_dictionary d,
t_symbol key,
t_symbol **  value 
)

Retrieve a t_symbol* from the dictionary.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to lookup.
valueThe address of variable to hold the value associated with the key.
Returns:
A Max error code.
long dictionary_hasentry ( C74_CONST t_dictionary d,
t_symbol key 
)

Test a key to set if it exists in the dictionary.

Parameters:
dThe dictionary instance.
keyThe key associated with the value to test.
Returns:
Returns true if the key exists, otherwise returns false.
t_dictionary* dictionary_new ( void  )

Create a new dictionary object.

You can free the dictionary by calling object_free(). However, you should keep in mind the guidelines provided in When to Free a Dictionary.

Returns:
Pointer to the new dictionary object.
See also:
object_free()
t_max_err dictionary_read ( char *  filename,
short  path,
t_dictionary **  d 
)

Read the specified JSON file and return a t_dictionary object.

You are responsible for freeing the dictionary with object_free(), subject to the caveats explained in When to Free a Dictionary.

Parameters:
filenameThe name of the file.
pathThe path of the file.
dThe address of a t_dictionary pointer that will be set to the newly created dictionary.
Returns:
A Max error code
t_max_err dictionary_read_yaml ( const char *  filename,
const short  path,
t_dictionary **  d 
)

Read the specified YAML file and return a t_dictionary object.

You are responsible for freeing the dictionary with object_free(), subject to the caveats explained in When to Free a Dictionary.

Parameters:
filenameThe name of the file.
pathThe path of the file.
dThe address of a t_dictionary pointer that will be set to the newly created dictionary.
Returns:
A Max error code
t_dictionary* dictionary_sprintf ( C74_CONST char *  fmt,
  ... 
)

Create a new dictionary populated with values using a combination of attribute and sprintf syntax.

Parameters:
fmtAn sprintf-style format string specifying key-value pairs with attribute nomenclature.
...One or more arguments which are to be substituted into the format string.
Returns:
A new dictionary instance.
Remarks:
Max attribute syntax is used to define key-value pairs. For example,
    "@key1 value @key2 another_value"
One common use of this to create dictionary that represents an element of a patcher, or even an entire patcher itself. The example below creates a dictionary that can be passed to a function like newobject_fromdictionary() to create a new object.
    t_dictionary *d;
    char text[4];
    
    strncpy_zero(text, "foo", 4);

    d = dictionary_sprintf("@maxclass comment @varname _name \
        @text \"%s\" @patching_rect %.2f %.2f %.2f %.2f \
        @fontsize %f @textcolor %f %f %f 1.0 \
        @fontname %s @bgcolor 0.001 0.001 0.001 0.",
        text, 20.0, 20.0, 200.0, 24.0,
        18, 0.9, 0.9, 0.9, "Arial");
    
    // do something with the dictionary here.
    
    object_free(d);
See also:
newobject_sprintf()
newobject_fromdictionary()
atom_setparse()
t_max_err dictionary_write ( t_dictionary d,
char *  filename,
short  path 
)

Serialize the specified t_dictionary object to a JSON file.

Parameters:
dThe dictionary to serialize into JSON format and write to disk.
filenameThe name of the file to write.
pathThe path to which the file should be written.
Returns:
A Max error code.
t_max_err dictionary_write_yaml ( const t_dictionary d,
const char *  filename,
const short  path 
)

Serialize the specified t_dictionary object to a YAML file.

Parameters:
dThe dictionary to serialize into YAML format and write to disk.
filenameThe name of the file to write.
pathThe path to which the file should be written.
Returns:
A Max error code.
void postdictionary ( t_object d)

Print the contents of a dictionary to the Max window.

Parameters:
dA pointer to a dictionary object.