MLib Alpha 1 API Reference

Hash Tables

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

for ordered dictionaries, see the M_Tree type

M_HashTable


  typedef struct M_HashTableRec_*    M_HashTable;

a handle to a hash table object. Hash tables are simple unordered containers that are used to map arbitrary keys to pointer values

m_hash_table_new


  MLIB_API(M_HashTable)
  m_hash_table_new( M_Memory      memory,
                    M_HashFunc    key_hash,
                    M_CompareFunc key_compare );

create a new (empty) hash table

input

memory	current memory manager handle
key_hash	the function used to compute hash values on keys
key_compare	the function used to compare keys

return

handle to new hash table

throws

m_err_memory_alloc

m_hash_table_new_full


  MLIB_API(M_HashTable)
  m_hash_table_new_full( M_Memory            memory,
                         M_HashDataFunc      key_hash,
                         M_CompareDataFunc   key_compare,
                         M_DestroyDataFunc   key_destroy,
                         M_Pointer           key_data,
                         M_DestroyDataFunc   val_destroy,
                         M_Pointer           val_data );

create a new (empty) hash table

input

memory	current memory manager handle
key_hash	the function used to compute hash values on keys
key_compare	the function used to compare keys
key_destroy	the function called when the keys are destroyed
key_data	the user data passed to the key hash and compare functions
val_destroy	the function called when a value is destroy
val_data	the user data passed to the value destructor

return

handle to new hash table

throws

m_err_memory_alloc

note

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

the value key destructor is called whenever a non-NULL value is removed or replaced in the table. it is optional, and receives the value data pointer as its second argument

m_hash_table_destroy


  MLIB_API(void)
  m_hash_table_destroy( M_HashTable  table );

destroy a given hash table

input

table

handle to target table

note

this function will not destroy the key values. You'll need to call m_hash_table_iterate to do that before destroying the table

m_hash_table_get_size


  MLIB_API(M_ULong)
  m_hash_table_get_size( M_HashTable  table );

return the number of elements in a given hash table

input

table

handle to target table

return

number of elements in table

m_hash_table_set


  MLIB_API(void)
  m_hash_table_set( M_HashTable  table,
                    M_Pointer    key,
                    M_Pointer    value );

set the value of a given key in the hash table. You can also unset it (i.e. remove the corresponding element) by passing a NULL pointer in "data"

input

table	handle to target table
key	target key
value	new value. can be NULL, in which case the key is removed from the hash table

throws

m_err_memory_alloc

m_hash_table_get


  MLIB_API(M_Pointer)
  m_hash_table_get( M_HashTable  table,
                    M_Pointer    key );

retrieve the value associated to a given key. NULL if not found

input

table	handle to target table
key	target key

return

key value, NULL if the key wasn't set..

note

see m_hash_table_lookup

m_hash_table_lookup


  MLIB_API(M_Bool)
  m_hash_table_lookup( M_HashTable  table,
                       M_Pointer    key,
                       M_Pointer   *avalue );

retrieve the value associated to a given key. NULL if not found

input

table	handle to target table
key	target key

output

avalue

value, if any, NULL otherwise

return

TRUE whenever the key was already set

note

'avalue' is optional. It set to NULL, nothing will be returned

m_hash_table_remove


  MLIB_API(void)
  m_hash_table_remove( M_HashTable  table,
                       M_Pointer    key );

remove a given key from the hash table, if it is present

input

table	handle to target table
key	target key

return

the previsou key value, if any

M_Hash_IterateFunc


  typedef  M_Bool     (*M_Hash_IterateFunc)( M_Pointer  key,
                                             M_Pointer  value,
                                             M_Pointer  user_data );

a function used to iterate over all keys of a given hash table

input

key	element key
value	element value
user_data	user-specified data

return

boolean.

note

the function m_hash_table_iterate uses a function of this type. where the result is interpreted as a stop flag (i.e., when the result is TRUE, iteration is stopped)

the function m_hash_table_remove_selection also uses a function of this type, where the result is interpreted as a selection flag (i.e. when the result is TRUE, the corresponding element is removed from the table)

m_hash_table_iterate


  MLIB_API(void)
  m_hash_table_iterate( M_HashTable         table,
                        M_Hash_IterateFunc  iterator,
                        M_Pointer           user_data );

iterate over all elements of a given hash table

input

table	handle to target table
iterator	iteration function
user_data	user-supplied data passed to the iterator on each hash table element

note

if an iterator call returns a value of TRUE, the iteration is stopped immediately, and the function returns

m_hash_table_remove_selection


  MLIB_API(void)
  m_hash_table_remove_selection( M_HashTable         table,
                                 M_Hash_IterateFunc  selector,
                                 M_Pointer           user_data );

remove selected elements from a hash table.

input

table	handle to target table
selector	selection function
user_data	user-supplied data passed to the selector on each hash table element

note

this function only removes the elements where the selector returns a value of TRUE

generated on Tue Oct 09 23:59:46 2001