uthash 英文介绍

C开源hash代码uthash的用法总结

https://blog.csdn.net/const_gong/article/details/50487806

Macro reference

Convenience macros

The convenience macros do the same thing as the generalized macros, but require fewer arguments.

In order to use the convenience macros,

1. the structure’s UT_hash_handle field must be named hh, and

2. for add or find, the key field must be of type int or char[] or pointer

Table 3. Convenience macros

macro	arguments
HASH_ADD_INT	(head, keyfield_name, item_ptr)
HASH_REPLACE_INT	(head, keyfiled_name, item_ptr,replaced_item_ptr)
HASH_FIND_INT	(head, key_ptr, item_ptr)
HASH_ADD_STR	(head, keyfield_name, item_ptr)
HASH_REPLACE_STR	(head,keyfield_name, item_ptr, replaced_item_ptr)
HASH_FIND_STR	(head, key_ptr, item_ptr)
HASH_ADD_PTR	(head, keyfield_name, item_ptr)
HASH_REPLACE_PTR	(head, keyfield_name, item_ptr, replaced_item_ptr)
HASH_FIND_PTR	(head, key_ptr, item_ptr)
HASH_DEL	(head, item_ptr)
HASH_SORT	(head, cmp)
HASH_COUNT	(head)

General macros

These macros add, find, delete and sort the items in a hash. You need to use the general macros if your UT_hash_handle is named something other than hh, or if your key’s data type isn’t int or char[].

Table 4. General macros

macro	arguments
HASH_ADD	(hh_name, head, keyfield_name, key_len, item_ptr)
HASH_ADD_BYHASHVALUE	(hh_name, head, keyfield_name, key_len, hashv, item_ptr)
HASH_ADD_KEYPTR	(hh_name, head, key_ptr, key_len, item_ptr)
HASH_ADD_KEYPTR_BYHASHVALUE	(hh_name, head, key_ptr, key_len, hashv, item_ptr)
HASH_ADD_INORDER	(hh_name, head, keyfield_name, key_len, item_ptr, cmp)
HASH_ADD_BYHASHVALUE_INORDER	(hh_name, head, keyfield_name, key_len, hashv, item_ptr, cmp)
HASH_ADD_KEYPTR_INORDER	(hh_name, head, key_ptr, key_len, item_ptr, cmp)
HASH_ADD_KEYPTR_BYHASHVALUE_INORDER	(hh_name, head, key_ptr, key_len, hashv, item_ptr, cmp)
HASH_REPLACE	(hh_name, head, keyfield_name, key_len, item_ptr, replaced_item_ptr)
HASH_REPLACE_BYHASHVALUE	(hh_name, head, keyfield_name, key_len, hashv, item_ptr, replaced_item_ptr)
HASH_REPLACE_INORDER	(hh_name, head, keyfield_name, key_len, item_ptr, replaced_item_ptr, cmp)
HASH_REPLACE_BYHASHVALUE_INORDER	(hh_name, head, keyfield_name, key_len, hashv, item_ptr, replaced_item_ptr, cmp)
HASH_FIND	(hh_name, head, key_ptr, key_len, item_ptr)
HASH_FIND_BYHASHVALUE	(hh_name, head, key_ptr, key_len, hashv, item_ptr)
HASH_DELETE	(hh_name, head, item_ptr)
HASH_VALUE	(key_ptr, key_len, hashv)
HASH_SRT	(hh_name, head, cmp)
HASH_CNT	(hh_name, head)
HASH_CLEAR	(hh_name, head)
HASH_SELECT	(dst_hh_name, dst_head, src_hh_name, src_head, condition)
HASH_ITER	(hh_name, head, item_ptr, tmp_item_ptr)
HASH_OVERHEAD	(hh_name, head)

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

The HASH_VALUE and ..._BYHASHVALUE macros are a performance mechanism mainly for the special case of having different structures, in different hash tables, having identical keys. It allows the hash value to be obtained once and then passed in to the ..._BYHASHVALUE macros, saving the expense of re-computing the hash value.

Argument descriptions

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 initially points to the first item that 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). If you’re new to macros, it might seem strange to pass the name of a field as a parameter. See note.

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 this note.)

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.

hashv

the hash value of the provided key. This is an input parameter for the ..._BYHASHVALUE macros, and an output parameter for HASH_VALUE. Reusing a cached hash value can be a performance optimization if you’re going to do repeated lookups for the same key.

item_ptr

pointer to the structure being added, deleted, replaced, or looked up, or the current pointer during iteration. This is an input parameter for the HASH_ADD, HASH_DELETE, and HASH_REPLACE macros, and an output parameter for HASH_FIND and HASH_ITER. (When using HASH_ITER to iterate, tmp_item_ptr is another variable of the same type as item_ptr, used internally).

replaced_item_ptr

used in HASH_REPLACE macros. This is an output parameter that is set to point to the replaced item (if no item is replaced it is set to NULL).

cmp

pointer to comparison function which accepts two arguments (pointers to items to compare) and returns an int specifying whether the first item should sort before, equal to, or after the second item (like strcmp).

condition

a function or macro which accepts a single argument (a void pointer to a structure, which needs to be cast to the appropriate structure type). The function or macro should evaluate to a non-zero value if the structure should be "selected" for addition to the destination hash.