哈希表

类型定义
typedef struct CstlHashInfo	CstlHash
	hash表句柄
typedef struct TagHashNode *	CstlHashIterator
	hash表迭代器定义，指向hash节点
typedef size_t(*	CstlHashCodeCalcFunc) (uintptr_t key, size_t bktSize)
	根据输入的Key生成hash表索引。
typedef bool(*	CstlHashMatchFunc) (uintptr_t key1, uintptr_t key2)
	该函数把输入数据与Key进行匹配比较。第一个哈希表中保存的key，第二个是用户需要匹配的Key。如果不匹配，返回值为false。

函数
size_t	CstlHashCodeCalcInt (uintptr_t key, size_t bktSize)
	默认整型哈希函数。
size_t	CstlHashCodeCalcStr (uintptr_t key, size_t bktSize)
	默认字符串哈希函数。
bool	CstlHashMatchInt (uintptr_t key1, uintptr_t key2)
	默认整型匹配函数。
bool	CstlHashMatchStr (uintptr_t key1, uintptr_t key2)
	默认字符串匹配函数。
CstlHash *	CstlHashCreate (size_t bktSize, CstlHashCodeCalcFunc hashFunc, CstlHashMatchFunc matchFunc, CstlDupFreeFuncPair *keyFunc, CstlDupFreeFuncPair *valueFunc)
	创建一个Hash表，返回Hash表的句柄
int32_t	CstlHashInsert (CstlHash *hash, uintptr_t key, size_t keySize, uintptr_t value, size_t valueSize)
	插入hash数据
int32_t	CstlHashPut (CstlHash *hash, uintptr_t key, size_t keySize, uintptr_t value, size_t valueSize)
	插入或更新hash数据
int32_t	CstlHashAt (const CstlHash *hash, uintptr_t key, uintptr_t *value)
	查找节点，返回节点数据。
CstlHashIterator	CstlHashFind (const CstlHash *hash, uintptr_t key)
	查找key所在迭代器。
bool	CstlHashEmpty (const CstlHash *hash)
	判断当前HASH表是否为空。
size_t	CstlHashSize (const CstlHash *hash)
	获取HASH表的节点数量。
CstlHashIterator	CstlHashErase (CstlHash *hash, uintptr_t key)
	从hash表中移除指定结点。
void	CstlHashClear (CstlHash *hash)
	删除hash表所有节点。
void	CstlHashDestory (CstlHash *hash)
	删除hash表
CstlHashIterator	CstlHashIterBegin (const CstlHash *hash)
	获取hash表中的第一个节点的迭代器。
CstlHashIterator	CstlHashIterEnd (const CstlHash *hash)
	获取hash表中最后一个节点之后预留的迭代器。
CstlHashIterator	CstlHashIterNext (const CstlHash *hash, CstlHashIterator it)
	获取hash表的下一个节点迭代器。
uintptr_t	CstlHashIterKey (const CstlHash *hash, CstlHashIterator it)
	获取迭代器的key。
uintptr_t	CstlHashIterValue (const CstlHash *hash, CstlHashIterator it)
	获取迭代器的value。

详细描述

类型定义说明

CstlHash

typedef struct CstlHashInfo CstlHash

hash表句柄

CstlHashCodeCalcFunc

typedef size_t(* CstlHashCodeCalcFunc) (uintptr_t key, size_t bktSize)

根据输入的Key生成hash表索引。

参数

key	[IN] hash key
bktSize	[IN] hash桶大小

CstlHashIterator

typedef struct TagHashNode* CstlHashIterator

hash表迭代器定义，指向hash节点

CstlHashMatchFunc

typedef bool(* CstlHashMatchFunc) (uintptr_t key1, uintptr_t key2)

该函数把输入数据与Key进行匹配比较。第一个哈希表中保存的key，第二个是用户需要匹配的Key。如果不匹配，返回值为false。

参数

key1	[IN] 哈希表中保存的key
key2	[IN] 待匹配的key

返回值

true	key1和key2匹配。
false	key1和key2不匹配。

函数说明

CstlHashAt()

int32_t CstlHashAt	(	const CstlHash *	hash,
		uintptr_t	key,
		uintptr_t *	value
	)

查找节点，返回节点数据。

描述: 根据key查找并返回节点数据。

参数

hash	[IN] hash表的句柄。
key	[IN] key或保存key的地址。
value	[OUT] 查到的数据。

返回值

CSTL_OK	查找成功。
CSTL_ERROR	查找失败。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashClear()

void CstlHashClear

(

CstlHash *

hash

)

删除hash表所有节点。

描述：删除所有节点，回收节点内存（hash表还在，只是没有成员）。

注意

注意：如果用户数据中有私有资源，则需要在创建时注册free钩子函数。

参数

hash	[IN] hash表句柄。

返回值

无。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashCodeCalcInt()

size_t CstlHashCodeCalcInt	(	uintptr_t	key,
		size_t	bktSize
	)

默认整型哈希函数。

默认整型哈希函数。

注意

1.key为用户调用其他接口时的入参。
2.若key为整型，用户可在创建hash时将该函数作为hashFunc参数。

参数

key	[IN] 待计算的key。
bktSize	[IN] 哈希桶大小。

返回值

#哈希值	根据用户key计算出的哈希值。

依赖：无

• cstl_hash.h：该接口声明所在的头文件。

CstlHashCodeCalcStr()

size_t CstlHashCodeCalcStr	(	uintptr_t	key,
		size_t	bktSize
	)

默认字符串哈希函数。

默认字符串哈希函数。

注意

1.key为用户调用其他接口时的入参，用户必须保证传入的key为合法的字符串首地址。
2.若key为字符串，用户可在创建hash时将该函数作为hashFunc参数。

参数

key	[IN] 待计算的key。
bktSize	[IN] 哈希桶大小。

返回值

#哈希值	根据用户key计算出的哈希值。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashCreate()

CstlHash * CstlHashCreate	(	size_t	bktSize,
		CstlHashCodeCalcFunc	hashFunc,
		CstlHashMatchFunc	matchFunc,
		CstlDupFreeFuncPair *	keyFunc,
		CstlDupFreeFuncPair *	valueFunc
	)

创建一个Hash表，返回Hash表的句柄

注意

1、关于key和data的拷贝函数：
如下场景不需要注册拷贝函数：如果是int型数据，且长度<=sizeof(uintptr_t)。
其它场景必须注册拷贝函数：
a）是int型数据，但长度 >sizeof(uintptr_t)；
b）字符串；
c）用户自定义数据结构；
2、关于free函数：简单来说，如果注册了duplicate函数，就必须注册相应的free函数。
3、提供默认的整型、字符串哈希函数：::CstlHashCodeCalcInt、::CstlHashCodeCalcStr。
4、提供默认的整型、字符串匹配函数：::CstlHashMatchInt、::CstlHashMatchStr。

参数

bktSize	[IN] hash桶的个数
hashCalcFunc	[IN] hash值计算函数。如果为NULL，则默认key为整型，使用::CstlHashCodeCalcInt。
matchFunc	[IN] hash key匹配函数。如为NULL，则默认key为整型，使用::CstlHashMatchInt。
keyFunc	[IN] hash key拷贝及释放函数对，如果用户未注册keyFunc->dupFunc，则默认为key为整型。
valueFunc	[IN] hash data拷贝及释放函数对。如果用户未注册valueFunc->dupFunc，则默认为data为整型。

返回值

hash表句柄。NULL表示创建失败。

依赖：无

参见

#CstlHashCodeCalcInt、#CstlHashCodeCalcStr、#CstlHashMatchInt、#CstlHashMatchStr。

• cstl_hash.h：该接口声明所在的头文件.

CstlHashDestory()

void CstlHashDestory

(

CstlHash *

hash

)

删除hash表

描述：删除hash表，如里面有节点先删除节点，回收内存。

注意

注意：如果用户数据中有私有资源，则需要在创建时注册free钩子函数。

参数

hash	[IN] hash表句柄。

返回值

无。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashEmpty()

bool CstlHashEmpty

(

const CstlHash *

hash

)

判断当前HASH表是否为空。

描述: 判断当前HASH表是否为空，为空返回true，否则返回false。

参数

hash	[IN] hash表句柄。取值范围为有效指针。

返回值

#true，	表示HASH表为空。
#false，表示HASH表非空。

参见

CstlHashSize

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashErase()

CstlHashIterator CstlHashErase	(	CstlHash *	hash,
		uintptr_t	key
	)

从hash表中移除指定结点。

描述: 根据key查找到节点并删除（释放内存），同时释放相应的节点内存。

参数

hash	[IN] hash表句柄。取值范围为有效指针。
key	[IN] 移除节点key。

返回值

key存在时，返回key所在迭代器的下一个迭代器（指向Node所在地址）,其他则返回::CstlHashIterEnd()。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashFind()

CstlHashIterator CstlHashFind	(	const CstlHash *	hash,
		uintptr_t	key
	)

查找key所在迭代器。

描述: 根据key查找并返回key所在的迭代器。

参数

hash	[IN] hash表的句柄。
key	[IN] key或保存key的地址。

返回值

key存在时，返回key所在迭代器（指向Node所在地址）,其他情况返回::CstlHashIterEnd()。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashInsert()

int32_t CstlHashInsert	(	CstlHash *	hash,
		uintptr_t	key,
		size_t	keySize,
		uintptr_t	value,
		size_t	valueSize
	)

插入hash数据

描述：创建节点，把数据(key、value)插入hash表

注意

1.不支持重复key。
2.key和value为整型值或指向用户key或value的地址。
3.如果扩展数据的生命周期小于节点的生命周期，则需要在创建哈希表时注册拷贝函数及释放函数。

参数

hash	[IN] hash表的句柄。
key	[IN] key或保存key的地址。
keySize	[IN] key拷贝长度，若用户未注册dupFunc，该参数将不被使用
value	[IN] value或保存value的地址。
valueSize	[IN] value拷贝长度，若用户未注册dupFunc，该参数将不被使用

返回值

CSTL_OK	插入节点成功。
CSTL_ERROR	插入失败。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashIterBegin()

CstlHashIterator CstlHashIterBegin

(

const CstlHash *

hash

)

获取hash表中的第一个节点的迭代器。

描述：获取hash表中的第一个节点所在的迭代器。

参数

hash	[IN] hash表的句柄。

返回值

第一个节点迭代器，若hash为空则返回::CstlHashIterEnd()。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashIterEnd()

CstlHashIterator CstlHashIterEnd

(

const CstlHash *

hash

)

获取hash表中最后一个节点之后预留的迭代器。

描述：获取hash表中的最后一个节点之后预留的迭代器。该节点指向最后保留的hash桶，该桶没有任何成员。

参数

hash	[IN] hash表的句柄。

返回值

最后一个节点之后预留的迭代器。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashIterKey()

uintptr_t CstlHashIterKey	(	const CstlHash *	hash,
		CstlHashIterator	it
	)

获取迭代器的key。

描述：获取hash表中迭代器当前key。

注意

1.当hash为空指针或it等于::CstlHashIterEnd()时，接口返回0，该接口无法区分是错误码还是用户数据， 用户调用该接口时必须保证hash为合法指针，并且it不等于::CstlHashIterEnd()

参数

hash	[IN] hash表的句柄。
it	[IN] 当前迭代器。

返回值

迭代器对应的key。it等于::CstlHashIterEnd()时则返回0。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashIterNext()

CstlHashIterator CstlHashIterNext	(	const CstlHash *	hash,
		CstlHashIterator	it
	)

获取hash表的下一个节点迭代器。

描述：获取hash表下一个节点迭代器。

参数

hash	[IN] hash表的句柄。
it	[IN] 当前迭代器。

返回值

下一个节点迭代器。若当前节点已是最后一个迭代器则返回::CstlHashIterEnd()。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashIterValue()

uintptr_t CstlHashIterValue	(	const CstlHash *	hash,
		CstlHashIterator	it
	)

获取迭代器的value。

描述：获取hash表中迭代器当前key。

注意

1.当hash为空指针或it等于::CstlHashIterEnd()时，接口返回0，该接口无法区分是错误码还是用户数据， 用户调用该接口时必须保证hash为合法指针，并且it不等于::CstlHashIterEnd()

参数

hash	[IN] hash表的句柄。
it	[IN] 当前迭代器。

返回值

迭代器对应的value。it等于::CstlHashIterEnd()时则返回0。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashMatchInt()

bool CstlHashMatchInt	(	uintptr_t	key1,
		uintptr_t	key2
	)

默认整型匹配函数。

默认整型匹配函数。

注意

1.key为用户调用其他接口时的入参。
2.若key为整型，用户可在创建hash时将该函数作为matchFunc参数。

参数

key1	[IN] 待匹配的key。
key2	[IN] 待匹配的key。

返回值

true	key1和key2匹配。
false	key1和key2不匹配。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashMatchStr()

bool CstlHashMatchStr	(	uintptr_t	key1,
		uintptr_t	key2
	)

默认字符串匹配函数。

默认字符串匹配函数。

注意

1.key1为用户调用其他接口时的入参，用户必须保证传入的key1为合法的字符串首地址。
2.若key为字符串，用户可在创建hash时将该函数作为matchFunc参数。

参数

key1	[IN] 待匹配的key。
key2	[IN] 待匹配的key。

返回值

true	key1和key2匹配。
false	key1和key2不匹配。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashPut()

int32_t CstlHashPut	(	CstlHash *	hash,
		uintptr_t	key,
		size_t	keySize,
		uintptr_t	value,
		size_t	valueSize
	)

插入或更新hash数据

描述：该接口用于将不存在的key插入到哈希表或更新已存在的key对应的value。

注意

1.支持重复key。
2.当key不存在时，该接口的使用与::CstlHashInsert保持一致。
3.当key存在时，该接口会更新value。

参数

hash	[IN] hash表的句柄。
key	[IN] key或保存key的地址。
keySize	[IN] key拷贝长度，若用户未注册dupFunc，该参数将不被使用
value	[IN] value或保存value的地址。
valueSize	[IN] value拷贝长度，若用户未注册dupFunc，该参数将不被使用

返回值

CSTL_OK	插入或更新节点成功。
CSTL_ERROR	插入或更新节点失败。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.

CstlHashSize()

size_t CstlHashSize

(

const CstlHash *

hash

)

获取HASH表的节点数量。

描述: 用于获取HASH表的节点数量，返回节点个数。

参数

hash	[IN] hash表句柄。取值范围为有效指针。

返回值

hash节点数。

依赖：无

• cstl_hash.h：该接口声明所在的头文件.