Dictionary
[Data Storage]

In Max 5, we have a new "dictionary" object which can be used for object prototypes, object serialization, object constructors, and other tasks. 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 ()
	Create a new linklist object.
t_max_err	dictionary_appendlong (t_dictionary d, t_symbol key, 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 (t_dictionary d, t_symbol key, long *value)
	Retrieve a long integer from the dictionary.
t_max_err	dictionary_getfloat (t_dictionary d, t_symbol key, double *value)
	Retrieve a double-precision float from the dictionary.
t_max_err	dictionary_getsym (t_dictionary d, t_symbol key, t_symbol **value)
	Retrieve a t_symbol* from the dictionary.
t_max_err	dictionary_getatom (t_dictionary d, t_symbol key, t_atom *value)
	Copy a t_atom from the dictionary.
t_max_err	dictionary_getstring (t_dictionary d, t_symbol key, const char **value)
	Retrieve a C-string pointer from the dictionary.
t_max_err	dictionary_getatoms (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 (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 (t_dictionary d, t_symbol key, t_object **value)
	Retrieve a t_atomarray pointer from the dictionary.
t_max_err	dictionary_getdictionary (t_dictionary d, t_symbol key, t_object **value)
	Retrieve a t_dictionary pointer from the dictionary.
t_max_err	dictionary_getobject (t_dictionary d, t_symbol key, t_object **value)
	Retrieve a t_object pointer from the dictionary.
long	dictionary_entryisstring (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 (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 (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 (t_dictionary d, t_symbol key)
	Test a key to set if it exists in the dictionary.
long	dictionary_getentrycount (t_dictionary *d)
	Return the number of keys in a dictionary.
t_max_err	dictionary_getkeys (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.
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, long *value, 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 (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.
void	postdictionary (t_object *d)
	Print the contents of a dictionary to the Max window.

Detailed Description

In Max 5, we have a new "dictionary" object which can be used for object prototypes, object serialization, object constructors, and 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 guaranteed 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

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,
		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	(	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()

long dictionary_entryisatomarray	(	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	(	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	(	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_getatom	(	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	(	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	(	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,
		long *	value,
		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	(	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.

long dictionary_getentrycount ( 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	(	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	(	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	(	t_dictionary *	d,
		t_symbol *	key,
		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	(	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	(	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	(	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	(	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 ( )

Create a new linklist object.

You can free the linklist 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_dictionary* dictionary_sprintf	(	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.

void postdictionary ( t_object * d )

Print the contents of a dictionary to the Max window.

Parameters:

d

A pointer to a dictionary object.

Dictionary [Data Storage]

Data Structures

Functions

Detailed Description

Using Dictionaries

Understanding Dictionaries

When to Free a Dictionary

Some Common Uses of Dictionaries

Function Documentation

Dictionary
[Data Storage]