MLib Alpha 1 API Reference

Trees

an MLib tree is a generic container that implements a simple ordered dictionary of (key,value) pairs, where keys and values can be of any pointer type.

See the M_HashTable type for fast unordered containers. Trees are implemented as balanced AVL trees, using a fast non-recursive implementation.

M_Tree


  typedef struct M_TreeRec_*    M_Tree;

handle to a generic tree container. A tree is a sorted map of (key,value) pairs

m_tree_new


  MLIB_API(M_Tree)     m_tree_new( M_Memory       memory,
                                   M_CompareFunc  key_compare );

create a new (empty) generic tree

input

memory	memory manager handle
key_compare	simple key comparison function

return

handle to new tree object

throws

m_err_memory_alloc

m_tree_new_full


  MLIB_API(M_Tree)     m_tree_new_full( M_Memory           memory,
                                        M_CompareDataFunc  key_compare,
                                        M_DestroyDataFunc  key_destroy,
                                        M_Pointer          key_data,
                                        M_DestroyDataFunc  val_destroy,
                                        M_Pointer          val_data );

create a new (empty) generic tree, with more specific parameters

input

memory	memory manager handle
key_compare	key comparison function
key_destroy	key destructor, can be NULL
key_data	key-specific data pointer
val_destroy	value destructor, can be NULL
val_data	value-specific data pointer

return

handle to new tree object

throws

m_err_memory_alloc

note

the key destructor is called whenever a non-NULL key is removed from the tree. the key data pointer is passed to both the comparison function and the destructor

the value destructor is called whenever a non-NULL value is removed or replaced from the tree. it receives the value data pointer as its second argument

the desctructors should _never_ raise an exception. the comparison function can raise an exception, but should be avoided whenever necessary

m_tree_destroy


  MLIB_API(void)       m_tree_destroy( M_Tree  tree );

destroy a given tree (after clearing it)

input

tree

handle to target tree

m_tree_get_size


  MLIB_API(M_ULong)    m_tree_get_size( M_Tree  tree );

return the size (i.e. number of nodes) in a tree

input

tree

handle to target tree

return

number of nodes in the tree

m_tree_get_depth


  MLIB_API(M_UInt)     m_tree_get_depth( M_Tree  tree );

return the depth of a given tree

input

tree

handle to target tree

return

depth of the tree

m_tree_get


  MLIB_API(M_Pointer)  m_tree_get( M_Tree     tree,
                                   M_Pointer  key );

retrieve the value associated to a given key.

input

tree	handle to target tree
key	lookup key

return

value associated to key. NULL if the key isn't part of the tree

m_tree_lookup


  MLIB_API(M_Bool)     m_tree_lookup( M_Tree      tree,
                                      M_Pointer   key,
                                      M_Pointer  *avalue );

tests wether a key is part of a tree, and return its value

input

tree	handle to target tree
key	lookup key

output

avalue

key value, if any. (this parameter is optional)

return

boolean. set iff the key is set in the tree

m_tree_set


  MLIB_API(void)       m_tree_set( M_Tree     tree,
                                   M_Pointer  key,
                                   M_Pointer  value );

set or replace the value corresponding to a given key in the tree

input

tree	handle to target tree
key	lookup key
value	new value for this key

throws

m_err_memory_alloc

m_tree_remove


  MLIB_API(void)       m_tree_remove( M_Tree     tree,
                                      M_Pointer  key );

removes a given key, and its associated value, from the tree

input

tree	handle to target tree
key	lookup key

generated on Tue Oct 09 23:59:46 2001