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