libtable(3) FreeBSD Library Functions Manual libtable(3) NAME libtable – Hash tables with int or char * keys SYNOPSIS #include -I/usr/local/include -L/usr/local/lib -ltable DESCRIPTION LibTable provides hash tables with integer or character array keys. LibTable uses the FNV Hash Function to distribute string keys and the Jenkins Hash Function to distribute integer keys. All library functions are reentrant if concurrent invocations are applied to different structures. USAGE The library uses structures defined in table.h: union table_key { char *str; int idx; }; union table_value { void *ptr; int num; }; struct table_element { union table_key key; union table_value value; struct table_element *next; }; #define TABLE_STRING 0 #define TABLE_INTEGER 1 struct table { int size, type; struct table_element **data; }; TABLE_MAKE() Create a new hash table with table_make(). struct table *table_make( int type, int size ); table_make() returns a pointer to a new table initialized for use. If memory allocation fails, table_make() returns NULL. The first argument is the type of the table. The type must be either TABLE_STRING or TABLE_INTEGER. The second argument is the size of the data array. TABLE_INSERT() Insert new keys or update values with table_insert(). int table_insert( struct table *table, void ( *func )( union table_key, union table_value ), union table_key key, union table_value value ); key and value are assigned to an internal struct table_element by structure assigment. On success, table_insert() returns 0. If memory allocation fails, table_insert() returns 1. The first argument is the table. The second argument is a function to be applied to the element currently associated with the key before updating the element. This function can be used to deallocate keys and values. Note that both the key and the value are overwritten when updating an existing element. The second argument can be NULL. The third argument is the key. The fourth argument is the new value to associate with the key. TABLE_DELETE() Remove keys with table_delete(). void table_delete( struct table *table, void ( *func )( union table_key key, union table_value value ), union table_key key ); The first argument is the table. The second argument is a function to be applied to the key and value of the element to be deleted before it is deleted. This function can be used to deallocate keys and values. The second argument can be NULL. The fourth argument is the key to delete. TABLE_LOOKUP() Retrieve an element to examine or modify with table_lookup(). struct table_element *table_lookup( struct table *table, union table_key key ); table_lookup() returns NULL if the key is not in the table. The first argument is the table. The second argument is the key of the desired element. TABLE_TRAVERSE() Use table_traverse() to apply a function to all the elements in a table. void table_traverse( struct table *table, void ( *func )( struct table_element *element, void *data ), void *data ); The first argument is the table. The second argument is a function to apply to elements. The function is called with an element pointer and a caller specified opaque data pointer. The third argument is the opaque data pointer to be passed to the second argument. TABLE_DESTROY() Use table_destroy() to deallocate a table. void table_destroy( struct table *table, void ( *func )( union table_key key, union table_value )); The first argument is the table. The second argument is a caller-supplied function to be applied to the keys and values of each element before it is deallocated. This function can be used to deallocate keys and values. The second argument can be NULL. TABLE_RESIZE() Use table_resize() to create a new table initialized with the key/value mappings of another table. struct table *table_resize( struct table *table, int size ); table_resize() returns the new table or NULL if memory allocation fails. When successful, table_resize() deallocates the old table with table_destroy(). The first argument is the old table. The second argument is the size of the new table's data array. AUTHORS James Bailie ⟨jimmy@mammothcheese.ca⟩ http://www.mammothcheese.ca Wed, Oct 10, 2018