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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
#ifndef BHLIB_HASHMAP_H
#define BHLIB_HASHMAP_H
#include <bh/bh.h>
typedef struct bh_hashmap_s bh_hashmap_t;
/**
* @brief Create new hashmap object.
*
* @param equal Function used for comparing keys
* @param hash Function used to calculate hash value of the key
*
* @return If the function succeeds, the return value is a pointer to the new
* hashmap object.
* @return If the function fails, the return value is NULL.
*
* @warning The quality of the supplied hash function will affect performance
* of the hashmap.
*
* @sa bh_hashmap_free, bh_hashmap_reserve, bh_hashmap_insert
*/
bh_hashmap_t *bh_hashmap_new(bh_equal_cb_t equal,
bh_hash_cb_t hash);
/**
* @brief Free hashmap object.
*
* @param hashmap Valid pointer to the hashmap object.
*
* @sa bh_hashmap_clear
*/
void bh_hashmap_free(bh_hashmap_t *hashmap);
/**
* @brief Clear the hashmap.
*
* @param hashmap Valid pointer to the hashmap object.
*
* @warning Clearing the hashmap does invalidate iterators.
*
* @sa bh_hashmap_remove
*/
void bh_hashmap_clear(bh_hashmap_t *hashmap);
/**
* @brief Reserve space for the specified amount of elements.
*
* @param hashmap Valid pointer to the hashmap object.
* @param size The amount of elements.
*
* @return If the function succeeds, the return value is zero.
* @return If the function fails, the return value is non-zero.
*
* @warning Reserving hashmap space does invalidate iterators.
*
* @sa bh_hashmap_capacity, bh_hashmap_insert
*/
int bh_hashmap_reserve(bh_hashmap_t *hashmap,
size_t size);
/**
* @brief Insert key/value into the hashmap.
*
* @param hashmap Valid pointer to the hashmap object.
* @param key Key
* @param value Value
*
* @return If the function succeeds, the return value is zero.
* @return If the function fails, the return value is non-zero.
*
* @warning Inserted element is owned by the caller of the function.
* @warning Inserting elements into the hashmap does invalidate iterators.
*
* @sa bbh_hashmap_remove, bh_hashmap_at
*/
int bh_hashmap_insert(bh_hashmap_t *hashmap,
void *key,
void *value);
/**
* @brief Remove element from the hashmap.
*
* @param hashmap Valid pointer to the hashmap object.
* @param key Key.
*
* @warning Removing elements from the hashmap does invalidate iterators.
*
* @sa bh_hashmap_insert, bh_hashmap_at
*/
void bh_hashmap_remove(bh_hashmap_t *hashmap,
void *key);
/**
* @brief Return element value by the key from the hashmap.
*
* @param hashmap Valid pointer to the hashmap.
* @param key Key.
* @param exists Pointer to the exists flag (optional).
*
* @return If the function succeeds, the return value is a valid pointer to
* the element value.
* @return If the function fails, the return value is NULL.
*
* @note If the hashmap does not contain any element with the key, the
* function will fail.
*
* @sa bh_hashmap_empty, bh_hashmap_insert
*/
void *bh_hashmap_at(bh_hashmap_t *hashmap,
void *key,
int *exists);
/**
* @brief Check if the hashmap is empty.
*
* @param hashmap Valid pointer to the hashmap object.
*
* @return The return value is non-zero if the hashmap is empty, otherwise
* zero.
*
* @sa bh_hashmap_size
*/
int bh_hashmap_empty(bh_hashmap_t *hashmap);
/**
* @brief Return hashmap size.
*
* @param hashmap Valid pointer to the hashmap object.
*
* @return The return value is current hashmap size.
*
* @sa bh_hashmap_empty, bh_hashmap_capacity
*/
size_t bh_hashmap_size(bh_hashmap_t *hashmap);
/**
* @brief Return hashmap capacity.
*
* @param hashmap Valid pointer to the hashmap object.
*
* @return The return value is current hashmap capacity.
*
* @sa bh_hashmap_reserve, bh_hashmap_size
*/
size_t bh_hashmap_capacity(bh_hashmap_t *hashmap);
/**
* @brief Return hashmap load factor.
*
* @param hashmap Valid pointer to the hashmap object.
*
* @return The return value is current hashmap load factor.
*
* @sa bh_hashmap_set_factor, bh_hashmap_capacity
*/
float bh_hashmap_factor(bh_hashmap_t *hashmap);
/**
* @brief Set hashmap load factor.
*
* @param hashmap Valid pointer to the hashmap object.
* @param factor Load factor.
*
* @sa bh_hashmap_factor
*/
void bh_hashmap_set_factor(bh_hashmap_t *hashmap,
float factor);
/**
* @brief Return iterator for the element by the key.
*
* @param hashmap Valid pointer to the hashmap object.
* @param key Key
*
* @return The return value is the valid iterator for the element in the
* hashmap.
* @return The return value is the NULL iterator if there is no element with
* specified key.
*
* @sa bh_hashmap_iter_key, bh_hashmap_iter_value
*/
void *bh_hashmap_iter_at(bh_hashmap_t *hashmap,
void *key);
/**
* @brief Return iterator for the next element in the hashmap.
*
* @param hashmap Valid pointer to the hashmap object.
* @param iter Valid or NULL iterator.
*
* @return The return value is the valid iterator for the next element in the
* hashmap.
* @return The return value is the NULL iterator if there is no more elements
* in the hashmap.
*
* @sa bh_hashmap_iter_key, bh_hashmap_iter_value
*/
void *bh_hashmap_iter_next(bh_hashmap_t *hashmap,
void *iter);
/**
* @brief Remove element from the hashmap by the iterator.
*
* @param hashmap Valid pointer to the hashmap object.
* @param key Valid iterator.
*
* @warning Removing elements from the hashmap does invalidate iterators.
*
* @sa bh_hashmap_insert, bh_hashmap_at
*/
void bh_hashmap_iter_remove(bh_hashmap_t *hashmap,
void *iter);
/**
* @brief Return pointer to the element's key.
*
* @param iter Valid iterator.
*
* @return The return value is the stored element key.
*
* @sa bh_hashmap_iter_value, bh_hashmap_iter_next
*/
void *bh_hashmap_iter_key(void *iter);
/**
* @brief Return pointer to the element's value.
*
* @param iter Valid iterator.
*
* @return The return value is the stored element value.
*
* @sa bh_hashmap_iter_key, bh_hashmap_iter_next
*/
void *bh_hashmap_iter_value(void *iter);
#endif /* BHLIB_HASHMAP_H */
|
