prg_string_hash_table_item_insert()
摘要
向哈希表中插入一个新值。
语法
prg_string_hash_table_item_insert (hash_table_ptr, key_string, contents_ptr, old_contents_pptr)
| 参数 | 类型 | 说明 |
|---|---|---|
hash_table_ptr |
PrgT_Sting_Hash_Table * |
指向目标哈希表的指针。 |
key_string |
const char * |
与待插入表中的值相关联的键。 |
contents_ptr |
void * |
要插入表中的值。 |
old_contents_pptr |
void ** |
用于存放 key_string 先前值的指针的区域(如有);否则为 PRGC_NIL。 |
返回类型
void
无返回值。
头文件
prg_string_hash_funcs.h
详情
该函数利用键字符串确定插入 contents_ptr 的位置。如果哈希表中已经存在该 key_string 的值,则先前的指针会被放入 old_contents_pptr。
为防范重复键的情况,代码应检查 old_contents_pptr 是否为 PRGC_NIL。如果不是,说明该键此前已被使用,必须以某种方式保存先前的值。一种方法是使用链式方法,即重复键的哈希表条目是一个值列表。使用链式方法时:
- 将该单元格的先前值(来自
old_contents_pptr)与新值(contents_ptr)组合成一个列表。 - 再次调用
prg_string_hash_table_item_insert(),将这个新的值列表存储在该键的位置上。
通常,哈希表会复制一份 key_string,由调用者负责释放原始字符串。但如果哈希表创建时使用了 PRGC_STRING_HASH_OPT_STRING_MEM_CLIENT_OWNED 选项,则客户端必须维护键字符串并负责销毁它们。详见 prg_string_hash_table_create_options()。
**警告:**该函数 MT 不安全(线程不安全),相关说明见“Multi-Threading Safety“ 第 11 页。对共享哈希表的访问必须由外部串行化。