UTHASH(3)
===========
Troy D. Hanson <thanson@users.sourceforge.net>


NAME
----
uthash - C macros to add, find and delete items from a hash


SYNOPSIS
--------
    HASH_ADD        (hh_name, head, keyfield_name, key_len, item_ptr)
    HASH_ADD_KEYPTR (hh_name, head, key_ptr, key_len, item_ptr)
    HASH_FIND       (hh_name, head, key_ptr, key_len, item_ptr)
    HASH_DELETE     (hh_name, head, item_ptr)

    HASH_ADD_INT    (head, keyfield_name, item_ptr)
    HASH_FIND_INT   (head, key_ptr, item_ptr)
    HASH_ADD_STR    (head, keyfield_name, item_ptr)
    HASH_FIND_STR   (head, key_ptr, item_ptr)
    HASH_DEL        (head, item_ptr)

DESCRIPTION
-----------
These macros add, find and delete items from a hash.  

The first four generalized macros work with keys of any data type and fields
of any name. The latter five convenience macros do the same thing, but take
fewer arguments.  

In order to use the convenience macros, 

1. the structure's `UT_hash_handle` field must be named `hh`, and
2. the key field must be of type `int` or `char[]`

ARGUMENTS
---------
hh_name::
    name of the `UT_hash_handle` field in the structure. Conventionally called
    `hh`.
head::
    the structure pointer variable which acts as the "head" of the hash. So
    named because it points to the first item which is added to the hash.
keyfield_name::
    the name of the key field in the structure. (In the case of a multi-field
    key, this is the first field of the key).
key_len::
    the length of the key field in bytes. E.g. for an integer key, this is
    `sizeof(int)`, while for a string key it's `strlen(key)`. (For a
    multi-field key, see the notes in this guide on calculating key length).
key_ptr::
    for `HASH_FIND`, this is a pointer to the key to look up in the hash
    (since it's a pointer, you can't directly pass a literal value here). For
    `HASH_ADD_KEYPTR`, this is the address of the key of the item being added.
item_ptr::
    pointer to the structure being added, deleted or looked up. This is an
    input parameter for HASH_ADD and HASH_DELETE macros, and an output
    parameter for HASH_FIND.


NOTES
------
`HASH_ADD_KEYPTR` is used when the structure contains a pointer to the
key, rather than the key itself. 

`HASH_DEL` is a convenience macro but doesn't share the requirement that the
key be of type `int` or `char[]`.


AUTHOR
------
Written by Troy D. Hanson, <mailto:thanson@users.sourceforge.net[]>


RESOURCES
---------
See the http://uthash.sourceforge.net/[uthash web site] for the complete User's
Guide.

include::sflogo.txt[]

