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_dictionary *	dictionary_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_symbol *	dictionary_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_dictionary *	dictionary_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:

dictionary_new()
dictionary_clone()
dictionary_read()
dictionary_sprintf()
dictionary_vsprintf()
jsonreader_parse()
jpatcher_monikerforobject()
class_cloneprototype()
prototype_getdictionary()
clipboard_todictionary()
jpatchercontroller_copytodictionary()
probably others of course

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:

dictionary_prototypefromclass()
object_refpage_get_class_info_fromclassname()
object_refpage_get_class_info()
object_dictionaryarg()

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

Reading and Writing Dictionaries as JSON

The easiest way to get read a t_dictionary from a JSON file on disk is to use the dictionary_read() function. In some cases you may wish have more control, such as to generate JSON but not write it to disk. For that purpose you can create a jsonreader object as demonstrated below.

    t_dictionary    *d = NULL;
    t_max_err       err;
    t_atom          result[1];
    t_object        *jsonreader = (t_object*)object_new(_sym_nobox, _sym_jsonreader);

    // assume we have an argument called 'jsontext' which is a const char* with the JSON 
    // from which we wish to create a t_dictionary instance

    err = (t_max_err)object_method(jsonreader, _sym_parse, jsontext, result);
    if (!err) {
        t_object *ro = (t_object*)atom_getobj(result);
            
        if (ro) {
            if (object_classname_compare(ro, _sym_dictionary))
                d = (t_dictionary*)ro;
            else
                object_free(ro); 
        }
    }
    object_free(jsonreader);

    // we now have a t_dictionary in d that can be used as we see fit

Reading and Writing Dictionaries as JSON

The easiest way to get write a t_dictionary to disk as JSON is to use the dictionary_write() function. In some cases you may wish have more control, such as to generate JSON but not write it to disk. For that purpose you can create a jsonwriter object as demonstrated below.

    t_object    *jsonwriter = (t_object*)object_new(_sym_nobox, _sym_jsonwriter);
    t_handle    json;
    const char  *str;

    object_method(jsonwriter, _sym_writedictionary, d);
    object_method(jsonwriter, _sym_getoutput, &json);

    str = *json;

    // now str contains our JSON serialization of the t_dictionary d

    object_free(jsonwriter);

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:

d	The dictionary instance.
key	The 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.
value	The 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:

d	The dictionary instance.
key	The 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.
value	The 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:

d	The dictionary instance.
key	The 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.
argc	The number of atoms to append to the dictionary.
argv	The 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:

d	The dictionary instance.
key	The 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.
value	The 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:

d	The dictionary instance.
key	The 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.
value	The 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:

d	The dictionary instance.
key	The 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.
value	The 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:

d	The dictionary instance.
key	The 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.
value	The 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:

d	The dictionary instance.
key	The 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.
value	The 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:

d	The dictionary instance.
key	The 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.
value	The 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:

d	The dictionary instance.
key	The 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:

d	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
argc	The address of a variable to hold the number of atoms in the array.
argv	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
argc	The address of a variable to hold the number of atoms in the array.
argv	The 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().
def	The 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:

src	The source dictionary from which to copy entries.
dst	The destination dictionary to which the entries will be copied.
keys	The 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:

d	A dictionary instance. This will be the destination for any values that are copied.
copyfrom	A 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:

d	The dictionary instance.
key	The 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:

d	The dictionary instance.
recurse	If non-zero, the dictionary will be recursively unravelled to the Max window. Otherwise it will only print the top level.
console	If 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:

x	The 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:

x	The dictionary entry.
value	The 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:

x	The dictionary entry.
argc	The length of the returned t_atom vector.
argv	The 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:

d	The dictionary instance.
key	The 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:

d	The dictionary instance.
key	The 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:

d	The dictionary instance.
key	The 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:

d	The dictionary instance.
numkeys	The address of a long where the number of keys retrieved will be set.
keys	The 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:

d	The dictionary instance.
fun	The function to call, specified as function pointer cast to a Max method.
arg	An 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
ac	The number of return values
av	The return values
errstr	An 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
argc	The address of a variable to hold the number of atoms in the array.
argv	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The address of variable to hold the value associated with the key.
def	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
argc	The address of a variable to hold the number of atoms in the array.
argv	The address of a variable to hold a pointer to the first atom in the array.
def	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The address of variable to hold the value associated with the key.
def	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The address of variable to hold the value associated with the key.
def	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The address of variable to hold the value associated with the key.
def	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The address of variable to hold the value associated with the key.
def	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The 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:

d	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The 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:

d	The dictionary instance.
numkeys	The address of a long where the number of keys retrieved will be set.
keys	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The 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:

d	The dictionary instance.
key	The key associated with the value to lookup.
value	The 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:

d	The dictionary instance.
key	The 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:

filename	The name of the file.
path	The path of the file.
d	The 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:

filename	The name of the file.
path	The path of the file.
d	The 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:

fmt	An 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:

d	The dictionary to serialize into JSON format and write to disk.
filename	The name of the file to write.
path	The 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:

d	The dictionary to serialize into YAML format and write to disk.
filename	The name of the file to write.
path	The 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:

d	A pointer to a dictionary object.

Data Structures

Functions

Detailed Description

Using Dictionaries

Understanding Dictionaries

When to Free a Dictionary

Some Common Uses of Dictionaries

Reading and Writing Dictionaries as JSON

Reading and Writing Dictionaries as JSON

Reading and Writing Dictionaries as JSON

Function Documentation