Max 5 API Reference

datastore.h

/**
   @defgroup datastore Data Storage
    
    Max provides a number of ways of storing and manipulating data at a high level.
    It is recommended to use Max's data storage mechanisms where possible, 
    as Max's systems are designed for thread-safety and integration with the rest of Max API.
*/






/**
    @defgroup atomarray Atom Array
    @ingroup datastore
    
    Max's atomarray object is a container for an array of atoms with an interface for manipulating that array. 
    It can be useful for passing lists as a single atom, such as for the return value of an #A_GIMMEBACK method.
    It also used frequently in when working with Max's #t_dictionary object.
    
    @see dictionary
*/


/**
    @defgroup database Database
    @ingroup datastore
    
    Max's database support currently consists of a SQLite ( http://sqlite.org ) extension which is loaded 
    dynamically by Max at launch time.
    Because it is loaded dynamically, all interfacing with the sqlite object relies on Max's message passing interface,
    using object_method() and related functions.
    
    For most common database needs, a C-interface is defined in the ext_database.h header file and implemented in the
    ext_database.c source file.  The functions defined in this interface wrap the message passing calls and provide
    a convenient means by which you can work with databases.
    ext_database.c is located in the 'common' folder inside of the 'max-includes' folder.
    If you use any of the functions defined ext_database.h, you will need to add ext_database.c to your project.
*/  


/**
    @defgroup dictionary Dictionary
    @ingroup datastore
    
    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).
    
    
    @section using_dictionaries 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.
    
    
    @subsection understanding_dictionaries 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:

    @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
    @endcode
    
    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:
    
    @code
    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);  
    }
    @endcode
    
    
    @subsection when_to_free_a_dictionary 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:
    <ul>
        <li>dictionary_new()                        </li>
        <li>dictionary_clone()                      </li>
        <li>dictionary_read()                       </li>
        <li>dictionary_sprintf()                    </li>
        <li>dictionary_vsprintf()                   </li>
        <li>jsonreader_parse()                      </li>
        <li>jpatcher_monikerforobject()             </li>
        <li>class_cloneprototype()                  </li>
        <li>prototype_getdictionary()               </li>
        <li>clipboard_todictionary()                </li>
        <li>jpatchercontroller_copytodictionary()   </li>
        <li>probably others of course</li>
    </ul>
    
    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:
    <ul>
        <li>dictionary_prototypefromclass()                  </li>
        <li>object_refpage_get_class_info_fromclassname()    </li>
        <li>object_refpage_get_class_info()                  </li>
        <li>object_dictionaryarg()                           </li>
    </ul>
    
    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.
    
    
    @subsection dictionaries_common_uses 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 linklist
    @see hashtab
    
    @version 5.0
*/



/**
    @defgroup hashtab Hash Table
    @ingroup datastore
    
    Max's hashtab object implements a hash table ( http://en.wikipedia.org/wiki/Hash_table ). 
    Any type of value may be stored in the table, indexed using a #t_symbol as the unique key.
    
    @see linklist
    
*/



/**
    @defgroup indexmap Index Map
    @ingroup datastore
    
    An indexmap is basically a managed array of pointers, 
    but it allows you to derive relatively quickly the index from a pointer in the array.
    
    The index is assumed to be 0-N (where N is the current size of the array).
    You can sort the data and retain access to an index from the data relatively quickly.
    There is a hashtab which holds pieces of memory that hold indices that can be referenced by the data pointer.
    There is also an array of data pointers -- this is in "index" order.
    When operations take place on the array (insert, delete, sort), the pointers in the hashtab are updated with new indices.
*/





/**
    @defgroup linklist Linked List
    @ingroup datastore
    
    Max's linklist object implements a doubly-linked-list ( http://en.wikipedia.org/wiki/Linked_list ) together
    with a high-level interface for manipulating and accessing values in the list.
*/



/**
    @defgroup quickmap Quick Map
    @ingroup datastore
    
    A quickmap implements a pair of #t_hashtab hash tables so that it is fast to look up a unique value for a unique key or vice-versa.
    This implies that both the keys and the values must be unique so that look-ups can be performed in both directions.
*/



/**
    @defgroup string String Object
    @ingroup datastore
    
    Max's string object is a simple wrapper for c-strings, useful when working with Max's #t_dictionary, #t_linklist, or #t_hashtab.
    
    @see dictionary
*/




/**
    @defgroup symobject Symbol Object
    @ingroup datastore
    
    The symobject class is a simple object that wraps a #t_symbol* together with a couple of additional fields.
    It is useful for storing symbols, possibly with additional flags or pointers, into a @ref hashtab or  @ref linklist.
    
    @version 5.0
*/

Copyright © 2008, Cycling '74