C语言开源uthash用法总结

uthash 是C的比较优秀的开源代码，它实现了常见的hash操作函数，例如查找、插入、删除等等。该套开源代码采用宏的方式实现hash函数的相关功能，支持C语言的任意数据结构最为key值，甚至可以采用多个值作为key，无论是自定义的struct还是基本数据类型，需要注意的是不同类型的key其操作接口方式略有不同。
使用uthash代码时只需要包含头文件"uthash.h"即可。由于该代码采用宏的方式实现，所有的实现代码都在uthash.h文件中，因此只需要在自己的代码中包含该头文件即可。
Uthash的三个数据结构：

typedef struct UT_hash_bucket {
   struct UT_hash_handle *hh_head;
   unsigned count;
   unsigned expand_mult;
} UT_hash_bucket;
UT_hash_bucket作用提供根据hash进行索引。

typedef struct UT_hash_table {
   UT_hash_bucket *buckets;
   unsigned num_buckets, log2_num_buckets;
   unsigned num_items;
   struct UT_hash_handle *tail; /* tail hh in app order, for fast append    */
   ptrdiff_t hho; /* hash handle offset (byte pos of hash handle in element */ 
   unsigned ideal_chain_maxlen;
   unsigned nonideal_items;             
   unsigned ineff_expands, noexpand;
   uint32_t signature; /* used only to find hash tables in external analysis */
#ifdef HASH_BLOOM
   uint32_t bloom_sig; /* used only to test bloom exists in external analysis */
   uint8_t *bloom_bv;
   char bloom_nbits;
#endif
} UT_hash_table;
UT_hash_table可以看做hash表的表头。

typedef struct UT_hash_handle {
   struct UT_hash_table *tbl;        /* 指向hash表 */
   void *prev;                       /* prev element in app order      */
   void *next;                       /* next element in app order      */
   struct UT_hash_handle *hh_prev;   /* previous hh in bucket order    */
   struct UT_hash_handle *hh_next;   /* next hh in bucket order        */
   void *key;                        /* ptr to enclosing struct's key  */
   unsigned keylen;                  /* enclosing struct's key len     */
   unsigned hashv;/*哈希值*/         /* result of hash-fcn(key)        */
} UT_hash_handle;
UT_hash_handle，用户自定义数据必须包含的结构。

1．uthash的效率
uthash的插入、查找、删除的操作时间都是常量，当然这个常量的值受到key以及所选择的hash函数的影响，uthash共提供了7种函数，一般情况下选择默认的即可。如果对效率要求特别高时，可以再根据自己的需求选择适合自己的hash函数。
2、uthash的使用
在hash操作中，都是按照“键-值“对的方式进行插、查等操作，在uthash中，其基本数据结构就是一个包含“键-值“对的结构体，另外，该结构体中还包含一个uthash内部使用的hash处理句柄，如下代码所示：

#include "uthash.h"  

struct my_struct {  
    int id;                    /* key */  
    char name[10];  
    UT_hash_handle hh;         /* makes this structure hashable */  
};  

其中：
id是键（key）；
name是值（val），即自己要保存的数据域，这里可以根据自己的需要让它变成结构体指针或者其他类型都可以；
hh是内部使用的hash处理句柄，在使用过程中，只需要在结构体中定义一个UT_hash_handle类型的变量即可，不需要为该句柄变量赋值，但必须在该结构体中定义该变量。
Uthash所实现的hash表中可以提供类似于双向链表的操作，可以通过结构体成员hh的 hh.prev和hh.next获取当前节点的上一个节点或者下一个节点。
3．Key类型为int的简单示例
1）定义一个键为int类型的hash结构体：

#include "uthash.h"  
   
struct my_struct {  
    int ikey;                    /* key */  
    char value[10];
    UT_hash_handle hh;
};  

struct my_struct *g_users = NULL;  

这里需要注意:
key的类型为int，key的类型不一样，后面的插入、查找调用的接口函数就不一样，因此要求确保key的类型与uthash的接口函数一致。
必须提供 UT_hash_handle 变量 hh，无需为其初始化。
定义一个hash结构的空指针 g_users，用于指向保存数据的hash表，必须初始化为空，在后面的查、插等操作中，uthash内部会根据其是否为空而进行不同的操作。
2）实现自己的查找接口函数：

struct my_struct *find_user(int user_ikey) {  
    struct my_struct *s;
    HASH_FIND_INT(g_users, &user_ikey, s);
    return s;  
}  

其实现过程就是先定义一个hash结构体指针变量，然后通过 HASH_FIND_INT接口找到该key所对应的hash结构体。这里需要注意：
Uthash为整型key提供的查找接口为 HASH_FIND_INT；
传给接口 HASH_FIND_INT的第一个参数就是在1）中定义的指向hash表的指针，传入的第二个参数是整型变量ikey的地址。
3）实现自己的插入接口函数：

void add_user(int user_ikey, char *value_buf) {  
    struct my_struct *s;  
    HASH_FIND_INT(g_users, &user_ikey, s);  /* 插入前先查看key值是否已经在hash表g_users里面了 */  
    if (s == NULL) {
    	s = (struct my_struct*)malloc(sizeof(struct my_struct));
    	s->ikey = user_ikey;
    	HASH_ADD_INT(g_users, ikey, s);  /* 这里必须明确告诉插入函数，自己定义的hash结构体中键变量的名字 */  
    }  
    strcpy(s->value, value_buf);  
}  

由于uthash要求键（key）必须唯一，而uthash内部未对key值得唯一性进行很好的处理，因此它要求外部在插入操作时要确保其key值不在当前的hash表中，这就需要，在插入操作时，先查找hash表看其值是否已经存在，不存在在时再进行插入操作，在这里需要特别注意以下两点：
插入时，先查找，当键不在当前的hash表中时再进行插入，以确保键的唯一性。
需调用插入接口函数时需要明确告诉接口函数，自己定义的键变量的名字是什么。
4）实现删除接口

void delete_user(int user_ikey) {  
    struct my_struct *s = NULL;  
    HASH_FIND_INT(g_users, &user_ikey, s);  
    if (s != NULL) {
    	HASH_DEL(g_users, s);
    	free(s);              
    }  
}  

删除操作的接口函数为HASH_DEL，只需要告诉该接口要释放哪个hash表（这里是g_users）里的哪个节点（这里是s），需要注意：释放申请的hash结构体变量，uthash函数只将结构体从hash表中移除，并未释放该结构体所占据的内存。
5）清空hash表

void delete_all() {
	struct my_struct *current_user, *tmp;
	HASH_ITER(hh, users, current_user, tmp) {
		HASH_DEL(g_users,current_user);
		free(current_user);
	}
}

这里需要注意：uthash内部提供了另外一个清空函数:
HASH_CLEAR(hh, g_users);
函数，但它不释放各节点的内存，因此尽量不要使用它.
6）统计hash表中的已经存在的元素数
该操作使用函数
HASH_COUNT
即可获取到当前hash表中的元素数，其用法为：

unsigned int num_users;  
num_users = HASH_COUNT(g_users);  
printf("there are %u items\n", num_users);  

7）遍历元素
在开发过程中，可能需要对整个hash表进行遍历，这里可以通过
hh.next
获取当前元素的下一个元素。具体遍历方法为：

struct my_struct *s, *tmp;  
HASH_ITER(hh, g_users, s, tmp) {  
    printf("user ikey %d: value %s\n", s->ikey, s->value);  
    /* ... it is safe to delete and free s here */  
}  

另外还有一种不安全的删除方法，尽量避免使用它：

void print_users() {  
    struct my_struct *s;  
   
    for(s=g_users; s != NULL; s=s->hh.next) {  
        printf("user ikey %d: value %s\n", s->ikey, s->value);  
    }  
}  

4． 其他类型key的使用
本节主要关于key值类型为其他任意类型，例如整型、字符串、指针、结构体等时的用法。
注意：在使用key值为浮点类型时，由于浮点类型的比较受到精度的影响，例如：1.0000000002被认为与1相等，这些问题在uthash中也存在。

struct my_struct {
    int id;                    /* key */
    char name[10];
    UT_hash_handle hh;         /* makes this structure hashable */
};
typedef struct my_struct HashNode;
typedef struct my_struct *HashHead;

向hashtable中添加数据:
key是int，可以使用 HASH_ADD_INT
key是字符串，可以使用 HASH_ADD_STR
key是指针,可以使用 HASH_ADD_KEYPTR
其它，可以使用 HASH_ADD，上述实际都是调用这个方法，不过简化了参数
void hashTabel_add(HashHead *head, HashNode *users) {
	// id是key的属性名字，虽然很奇怪，实际作为宏参数会被替换掉
	// 可以看下面源码，intfield会替换换成&((add)->fieldname)
	if(!find_user(*head, users->id))
    	HASH_ADD_INT(*head, id, users);
}

#define HASH_ADD_INT(head,intfield,add)                                          \
    HASH_ADD(hh,head,intfield,sizeof(int),add)
#define HASH_ADD(hh,head,fieldname,keylen_in,add)                                \
  HASH_ADD_KEYPTR(hh, head, &((add)->fieldname), keylen_in, add)

在hashtable中替换数据:
与添加差不多，会在添加前，删除key相同的节点，再添加新的节点
如果key是int，可以使用 HASH_REPLACE_INT

void replace_user(HashHead *head, HashNode *newNode) {
    HashNode *oldNode = find_user(*head, newNode->id);
    if (oldNode)
        HASH_REPLACE_INT(*head, id, newNode, oldNode);
}

遍历节点：
可以用循环或者使用 HASH_ITER

void print_user(HashHead head) {
    HashNode *s;
    printf("size is %d\n", count_user(head));
    for (s = head; s != NULL; s = s->hh.next) {
        printf("user id %d, name %s\n", s->id, s->name);
    }
}
void print_user_iterator(HashHead head) {
    HashNode *s, *tmp;
    printf("size is %d\n", count_user(head));
    HASH_ITER(hh, head, s, tmp) {
        printf("user id %d: name %s\n", s->id, s->name);
        /* ... it is safe to delete and free s here */
    }
}

4.1． int类型key
前面就是以int类型的key作为示例，总结int类型key使用方法，可以看到其查找和插入分别使用专用接口:HASH_FIND_INT和HASH_ADD_INT。
4.2． 字符指针char类型key与字符数组char key[100]类型key
特别注意在Strting类型中，uthash对指针char和字符数组（例如char key[100]）做了区分，这两种情况下使用的接口函数时不一样的。在添加的时候，
key的类型为指针时使用接口函数HASH_ADD_KEYPTR，key的类型为字符数组时，使用接口函数HASH_ADD_STR，除了添加的接口不一样外，其他的查找、删除、变量等接口函数都是一样的。
4.3．使用地址作为key
在uthash中也可使用地址做key进行hash操作，使用地址作为key值时，其类型为void*，这样它就可以支持任意类型的地址了。在使用地址作为key时，插入和查找的专用接口函数为
HASH_ADD_PTR和HASH_FIND_PTR，其余接口是一样的。
4.3．其他非常用类型key
在uthash中还可使用结构体作为key，甚至可以采用组合的方式让多个值作为key，这些在其官方的网站张均有较详细的使用示例。在使用uthash需要注意以下几点：
在定义hash结构体时不要忘记定义UT_hash_handle的变量
需确保key值唯一，如果插入key-value对时，key值已经存在，再插入的时候就会出错。
不同的key值，其增加和查找调用的接口函数不一样，具体可见第4节。一般情况下，不通类型的key，其插入和查找接口函数是不一样的，删除、遍历、元素统计接口是通用的，特殊情况下，字符数组和字符串作为key值时，其插入接口函数不一样，但是查找接口是一样的。
5．完整程序例子
5.1．key类型为int的完整的例子

#include <stdio.h>   /* gets */  
#include <stdlib.h>  /* atoi, malloc */  
#include <string.h>  /* strcpy */  
#include "uthash.h"  
  
struct my_struct {  
    int ikey;                    /* key */  
    char value[10];  
    UT_hash_handle