libtable(8)             FreeBSD System Manager's Manual            libtable(8)

NAME
     libtable - Hash tables with int or char * keys

SYNOPSIS
     #include <table.h>
     -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_value value ),
                       union table_key key,
                       union table_value value );

     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 current value
     associated with the key if the key is already present in the table.  This
     function can be used to deallocate values.  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

                                 June 27, 2017