哈希表(uthash)详解

哈希表(uthash)

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

一、 uthash的使用

这里先要明确一点, uthash 中的函数接口大多是以宏的形式实现 ,在执行时用宏进行替换

定义HASH结构体

struct my_struct {
    int id;                //整形
    char name[10];
    UT_hash_handle hh;   //必须存在的句柄,一般声明为 hh      
};
//hh是内部使用的hash处理句柄，在使用过程中，只需要在结构体中定义一个UT_hash_handle类型的变量即可，不需要为该句柄变量赋值，但必须在该结构体中定义该变量。


struct my_struct {
    char name[10];        //字符数组
    int id;
    UT_hash_handle hh;         
};
struct my_struct {
    const char *name;     //字符指针  
    int id;
    UT_hash_handle hh;        
};
struct my_struct{
    void *key;            //指针健(这里可以是void* ,也可以是定义过的类型,例如 (struct ListNode*)
    int i;
    UT_hash_handle hh;
};

• id是键（key），也可以是其他的数据结构，不同的数据结构对应hash操作可能不一样

• name是值（value），其类型根据实际情况定义

• hh是内部使用的hash处理句柄，在使用过程中，只需要在结构体中定义一个UT_hash_handle类型的变量即可，不需要为该句柄变量赋值，但必须在该结构体中定义该变量。

FIND 查找接口

HASH_FIND( hh, Hash, &val, sizeof( val ), temp);

为 Uthash 中查找接口的原型 , HASH_FIND 是一个宏 , 包括 HASH_FIND_STR, HASH_FIND_INT 等在内的 HASH 查找函数底层都是以HASH_FIND为接口实现的

struct my_struct* temp=NULL;
HASH_FIND( hh,    Hash,     &val,      sizeof( val ),      temp);
//        句柄 | HASH头节点 | 键值取地址 | 键值占用字节数  | HASH类型的指针  (如果HASH_FIND查找到,那么会返回键值所在的HASH节点,反之返回NULL);

HASH_FIND_INT(Hash, &val, temp);  //整形               
HASH_FIND_STR(Hash, "betty", s); //字符数组类型
HASH_FIND_PTR(hash, &someaddr, d);//指针类型

HASH_FIND(hh,Hash,&val,sizeof(val),temp);  //结构体类型 ,前三种都是针对整形,字符数组以及指针进行优化的查找接口,若HASH表中要存储自定义类型,则使用初始的HASH_FIND函数   
      // ps: HASH_FIND 中第四个参数是 键值 的大小

ADD 增添接口

HASH_ADD( hh, Hash, val, sizeof( val ), temp);

​ 为 Uthash 中增添接口的原型 , HASH_ADD 是一个宏 , 包括 HASH_ADD_STR, HASH_ADD_INT 等在内的 HASH 增添函数底层都是以HASH_ADD为接口实现的

HASH_ADD( hh,     Hash,             val,          sizeof( val ),      temp);
//        句柄 | HASH头节点 | 结构体中键值的变量名 | 键值占用字节数  | HASH类型的指针  (用于将malloc的哈希节点插入HASH表)

HASH_ADD_INT(Hash, id, s);
HASH_ADD_STR(Hash, name, s);
HASH_ADD_PTR(Hash, key, e);

具体用法示例:

HASH_FIND_INT(Hash, &val, s);   //先进行查找,若在HASH中查找成功,则返回该HASH节点,否则返回NULL
    
if (s == NULL) {
        s = (struct my_struct*)malloc(sizeof *s);  //没有查找到,那么malloc一个新的哈希节点用于存储该键值
        s->id = val;
        // 若结构体中的键值是字符数组类型 , 这里赋值需要  strcpy(s->id,user_id);
        // 若结构体中的键值是字符串指针类型 , 这里赋值需要 s->id = user_id ;
        // 若这里是自定义类型,那么最好在赋值前加上 s->id = (自定义类型 *)user_id; //加上类型强制转换
        HASH_ADD_INT(Hash, val, s);    //将malloc的HASH节点增添至HASH
    }

DEL 删除接口

HASH_DEL(Hash, temp);

​ 若要从哈希中删除结构，必须具有指向该结构的指针。（如果你有了键值，先用 HASH_FIND,获取对应结构的指针）

HASH_DEL(Hash, temp);   //Hash指向哈希表 , temp 指向有对应键值的HASH节点
free(temp);           //注意:需要手动释放HASH节点

UTHASH永远不会释放你的结构

​ 删除结构只是将其从哈希表中删除 , 何时释放结构的选择完全取决于程序员自己

ITER 迭代接口

HASH_ITER(hh, Hash，ele，tmp);

​ 这个是一个大体的格式，最底层是通过for循环，通过指针操作来对哈希表进行遍历的，主要是通过更新 ele 和 tmp 的指针，每次循环迭代中会遍历哈希表中的所有的元素

HASH_ITER(hh, Hash，ele，tmp)   //宏替换后,这是一个循环,对HASH进行遍历
{
    cout<<ele->val<<"  ";
}

//当然也可以使用for循环进行遍历
for (s = Hash; s != NULL; s = s->hh.next) {
        printf("user id %d: name %s\n", s->id, s->name);
    }

SORT 排序接口

HASH_SORT(Hash, hash_sort);

​ 第一个参数为指向HASH的指针 , 第二参数为比较大小的函数指针,该函数指针对应的函数需要程序员自行设计 (原理与qsort的自定义函数类似)

int hash_sort(const struct my_struct *a, const struct my_struct *b) {
    return strcmp(a->name, b->name);  
}

int hash_sort(const struct my_struct *a, const struct my_struct *b) {
    return (a->id > b->id);    //从小到大排序
}

void sort_by_name() {
    HASH_SORT(Hash, hash_sort);
}

void sort_by_id() {
    HASH_SORT(Hash, hash_sort);
}

COUNT 计数接口

unsigned int num_users;
num_users = HASH_COUNT(users);  //统计Hash中的节点个数
printf("there are %u users\n", num_users);

二、封装接口

定义一hash结构体

struct MyStruct {
	int  key;                    /* key */
    char value[10];			   /* value, 若无value也可以去掉该变量 */
	UT_hash_handle hh;         
};
struct MyStruct *g_users = NULL;

注意：定义一个hash结构的空指针g_users，用于指向保存数据的hash表，必须初始化为空，在后面的查、插等操作中，uthash内部会根据其是否为空而进行不同的操作。

封装自己的查找接口

void AddUser(int iKey, char *iValue)
{
    struct MyStruct *s;
    HASH_FIND_INT(g_users, &iKey, is);  /* 插入前先查看key值是否已经在hash表g_users里面了 */
    if (s==NULL) {
		s = (struct MyStruct *)malloc(sizeof(struct MyStruct));
		s->key = iKey;
		HASH_ADD_INT(g_users, key, s);  /* 第二个参数为hash结构里面，hash key值的变量名 */
    }
    strcpy(s->value, iValue);
}

由于uthash要求键（key）必须唯一，而uthash内部未对key值得唯一性进行很好的处理，因此它要求外部在插入操作时要确保其key值不在当前的hash表中。若插入相同的key值到一个hash中，会被当做一种错误。

封装实现删除接口

void DeleteUser(int ikey)
{
    struct MyStruct *s = NULL;
    HASH_FIND_INT(g_users, &ikey, s);
    if (s==NULL) {
		HASH_DEL(g_users, s);      // HASH_DEL 只将结构体从hash表中移除，并未释放结构体内容需要自行free
		free(s);            
    }
}

统计hash表中的元素个数

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

遍历元素

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

清空hash表

void DeleteHash() 
{
	struct MyStruct *currentUser, *tmp;
 //HASH_ITER是一个宏定义，程序执行时被替换为一个循环。 g-users是指向哈希表的指针
	HASH_ITER(hh, g_users, currentUser, tmp) {
		HASH_DEL(g_users, currentUser);   //HASH_DEL将哈希节点从哈希表移除,没有释放
		free(currentUser);            
	}
}

三、 完整的例子

2.1 key为int

#include <stdio.h>   /* gets */
#include <stdlib.h>  /* atoi, malloc */
#include <string.h>  /* strcpy */
#include "uthash.h"

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

struct my_struct *users = NULL;

void add_user(int user_id, char *name) {
    struct my_struct *s;

    HASH_FIND_INT(users, &user_id, s);  /* id already in the hash? */
    if (s==NULL) {
      s = (struct my_struct *)malloc(sizeof *s);
      s->id = user_id;
      HASH_ADD_INT( users, id, s );  /* id: name of key field */
    }
    strcpy(s->name, name);
}

struct my_struct *find_user(int user_id) {
    struct my_struct *s;

    HASH_FIND_INT( users, &user_id, s );  /* s: output pointer */
    return s;
}

void delete_user(struct my_struct *user) {
    HASH_DEL(users, user);  /* user: pointer to deletee */
    free(user);
}

void delete_all() {
  struct my_struct *current_user, *tmp;

  HASH_ITER(hh, users, current_user, tmp) {
    HASH_DEL(users, current_user);  /* delete it (users advances to next) */
    free(current_user);             /* free it */
  }
}

void print_users() {
    struct my_struct *s;

    for(s=users; s != NULL; s=(struct my_struct*)(s->hh.next)) {
        printf("user id %d: name %s\n", s->id, s->name);
    }
}

int name_sort(struct my_struct *a, struct my_struct *b) {
    return strcmp(a->name,b->name);
}

int id_sort(struct my_struct *a, struct my_struct *b) {
    return (a->id - b->id);
}

void sort_by_name() {
    HASH_SORT(users, name_sort);
}

void sort_by_id() {
    HASH_SORT(users, id_sort);
}

int main(int argc, char *argv[]) {
    char in[10];
    int id=1, running=1;
    struct my_struct *s;
    unsigned num_users;

    while (running) {
        printf(" 1. add user\n");
        printf(" 2. add/rename user by id\n");
        printf(" 3. find user\n");
        printf(" 4. delete user\n");
        printf(" 5. delete all users\n");
        printf(" 6. sort items by name\n");
        printf(" 7. sort items by id\n");
        printf(" 8. print users\n");
        printf(" 9. count users\n");
        printf("10. quit\n");
        gets(in);
        switch(atoi(in)) {
            case 1:
                printf("name?\n");
                add_user(id++, gets(in));
                break;
            case 2:
                printf("id?\n");
                gets(in); id = atoi(in);
                printf("name?\n");
                add_user(id, gets(in));
                break;
            case 3:
                printf("id?\n");
                s = find_user(atoi(gets(in)));
                printf("user: %s\n", s ? s->name : "unknown");
                break;
            case 4:
                printf("id?\n");
                s = find_user(atoi(gets(in)));
                if (s) delete_user(s);
                else printf("id unknown\n");
                break;
            case 5:
                delete_all();
                break;
            case 6:
                sort_by_name();
                break;
            case 7:
                sort_by_id();
                break;
            case 8:
                print_users();
                break;
            case 9:
                num_users=HASH_COUNT(users);
                printf("there are %u users\n", num_users);
                break;
            case 10:
                running=0;
                break;
        }
    }

    delete_all();  /* free any structures */
    return 0;
}

2.2 key为字符数组

#include <string.h>  /* strcpy */
#include <stdlib.h>  /* malloc */
#include <stdio.h>   /* printf */
#include "uthash.h"

struct my_struct {
    char name[10];             /* key (string is WITHIN the structure) */
    int id;
    UT_hash_handle hh;         /* makes this structure hashable */
};


int main(int argc, char *argv[]) {
    const char *names[] = { "joe", "bob", "betty", NULL };
    struct my_struct *s, *tmp, *users = NULL;

    for (int i = 0; names[i]; ++i) {
        s = (struct my_struct *)malloc(sizeof *s);
        strcpy(s->name, names[i]);
        s->id = i;
        HASH_ADD_STR(users, name, s);
    }

    HASH_FIND_STR( users, "betty", s);
    if (s) printf("betty's id is %d\n", s->id);

    /* free the hash table contents */
    HASH_ITER(hh, users, s, tmp) {
      HASH_DEL(users, s);
      free(s);
    }
    return 0;
}

2.3 key为字符

#include <string.h>  /* strcpy */
#include <stdlib.h>  /* malloc */
#include <stdio.h>   /* printf */
#include "uthash.h"
 
struct my_struct {
    const char *name;          /* key */
    int id;
    UT_hash_handle hh;         /* makes this structure hashable */
};
 
 
int main(int argc, char *argv[]) {
    const char **n, *names[] = { "joe", "bob", "betty", NULL };
    struct my_struct *s, *tmp, *users = NULL;
    int i=0;
 
    for (n = names; *n != NULL; n++) {
        s = (struct my_struct*)malloc(sizeof(struct my_struct));
        s->name = *n;
        s->id = i++;
        HASH_ADD_KEYPTR(hh, users, s->name, strlen(s->name), s);
    }
 
    HASH_FIND_STR(users, "betty", s);
    if (s) printf("betty's id is %d\n", s->id);
 
    /* free the hash table contents */
    HASH_ITER(hh, users, s, tmp) {
      HASH_DEL(users, s);
      free(s);
    }
    return 0;
}

使用注意事项总结

• 在定义hash结构体时不要忘记定义UT_hash_handle的变量

• 需确保key值唯一，如果插入key-value对时，key值已经存在，再插入的时候就会出错

• 不同的key值，其增加和查找调用的接口函数不一样。一般情况下，不通类型的key，其插入和查找接口函数是不一样的，删除、遍历、元素统计接口是通用的，特殊情况下，字符数组和字符串作为key值时，其插入接口函数不一样，但是查找接口是一样的

• 如果函数如AddUser想将hash结构体的指针Hash作为参数传入。则有以下问题

  /* bad */
  void AddUser(struct Mytruct *Hash, int key, char *name)
  {
    ...
    HASH_ADD_INT(Hash, key, s);
  }
  /* good */
  void AddUser(struct Mytruct **Hash, int key, char *name)
  { 
    ...
    HASH_ADD_INT( *Hash, key, s );
  }
  

  官方给出的解释如下：

  The reason it’s necessary to deal with a pointer to the hash pointer is simple: the hash macros modify it (in other words, they modify the pointer itself not just what it points to).

  就是这个指针的值会变化。