1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
/* $Header: /pjproject-0.3/pjlib/include/pj/hash.h 6 10/14/05 12:26a Bennylp $ */
#ifndef __PJ_HASH_H__
#define __PJ_HASH_H__
/**
* @file hash.h
* @brief Hash Table.
*/
#include <pj/types.h>
PJ_BEGIN_DECL
/**
* @defgroup PJ_HASH Hash Table
* @ingroup PJ_DS
* @{
* A hash table is a dictionary in which keys are mapped to array positions by
* hash functions. Having the keys of more than one item map to the same
* position is called a collision. In this library, we will chain the nodes
* that have the same key in a list.
*/
/**
* If this constant is used as keylen, then the key is interpreted as
* NULL terminated string.
*/
#define PJ_HASH_KEY_STRING ((unsigned)-1)
/**
* This is the function that is used by the hash table to calculate hash value
* of the specified key.
*
* @param hval the initial hash value, or zero.
* @param key the key to calculate.
* @param keylen the length of the key, or PJ_HASH_KEY_STRING to treat
* the key as null terminated string.
*
* @return the hash value.
*/
PJ_DECL(pj_uint32_t) pj_hash_calc(pj_uint32_t hval,
const void *key, unsigned keylen);
/**
* Create a hash table with the specified 'bucket' size.
*
* @param pool the pool from which the hash table will be allocated from.
* @param size the bucket size, which will be round-up to the nearest 2^n+1
*
* @return the hash table.
*/
PJ_DECL(pj_hash_table_t*) pj_hash_create(pj_pool_t *pool, unsigned size);
/**
* Get the value associated with the specified key.
*
* @param ht the hash table.
* @param key the key to look for.
* @param keylen the length of the key, or PJ_HASH_KEY_STRING to use the
* string length of the key.
*
* @return the value associated with the key, or NULL if the key is not found.
*/
PJ_DECL(void *) pj_hash_get( pj_hash_table_t *ht,
const void *key, unsigned keylen );
/**
* Associate/disassociate a value with the specified key.
*
* @param pool the pool to allocate the new entry if a new entry has to be
* created.
* @param ht the hash table.
* @param key the key.
* @param keylen the length of the key, or PJ_HASH_KEY_STRING to use the
* string length of the key.
* @param value value to be associated, or NULL to delete the entry with
* the specified key.
*/
PJ_DECL(void) pj_hash_set( pj_pool_t *pool, pj_hash_table_t *ht,
const void *key, unsigned keylen,
void *value );
/**
* Get the total number of entries in the hash table.
*
* @param ht the hash table.
*
* @return the number of entries in the hash table.
*/
PJ_DECL(unsigned) pj_hash_count( pj_hash_table_t *ht );
/**
* Get the iterator to the first element in the hash table.
*
* @param ht the hash table.
* @param it the iterator for iterating hash elements.
*
* @return the iterator to the hash element, or NULL if no element presents.
*/
PJ_DECL(pj_hash_iterator_t*) pj_hash_first( pj_hash_table_t *ht,
pj_hash_iterator_t *it );
/**
* Get the next element from the iterator.
*
* @param ht the hash table.
* @param it the hash iterator.
*
* @return the next iterator, or NULL if there's no more element.
*/
PJ_DECL(pj_hash_iterator_t*) pj_hash_next( pj_hash_table_t *ht,
pj_hash_iterator_t *it );
/**
* Get the value associated with a hash iterator.
*
* @param ht the hash table.
* @param it the hash iterator.
*
* @return the value associated with the current element in iterator.
*/
PJ_DECL(void*) pj_hash_this( pj_hash_table_t *ht,
pj_hash_iterator_t *it );
/**
* @}
*/
PJ_END_DECL
#endif
|
