111
112
* number that is no larger than @entries; this should be set to a rough
112
113
* number of expected entries to ensure optimum distribution.
114
* Individual members of the hash table are #NihList members, so to
115
* Individual members of the hash table are NihList members, so to
115
116
* associate them with a string key @key_function must be provided; this
116
117
* would ordinarily just return a static string within the entry itself.
118
* The structure is allocated using #nih_alloc so it can be used as a
119
* The structure is allocated using nih_alloc() so it can be used as a
119
120
* context to other allocations.
121
* Returns: the new hash table or %NULL if the allocation failed.
122
* If @parent is not NULL, it should be a pointer to another allocated
123
* block which will be used as the parent for this block. When @parent
124
* is freed, the returned string will be freed too. If you have clean-up
125
* that would need to be run, you can assign a destructor function using
126
* the nih_alloc_set_destructor() function.
128
* Returns: the new hash table or NULL if the allocation failed.
124
nih_hash_new (size_t entries,
125
NihKeyFunction key_function)
131
nih_hash_new (const void *parent,
133
NihKeyFunction key_function)
130
138
nih_assert (key_function != NULL);
132
hash = nih_new (NULL, NihHash);
140
hash = nih_new (parent, NihHash);
160
168
* @hash: destination hash table,
161
169
* @entry: entry to be added.
163
* Adds @entry to @hash using the value returned by the hash #NihKeyFunction
171
* Adds @entry to @hash using the value returned by the hash NihKeyFunction
164
172
* to indicate which bin the entry should be placed into.
166
174
* For speed reasons, this function does not check whether an entry already
167
175
* exists with the key. If you need that constraint use either
168
* #nih_hash_add_unique or #nih_hash_replace.
176
* nih_hash_add_unique() or nih_hash_replace().
170
178
* If @entry is already in another list it is removed so there is no need
171
* to call #nih_list_remove before this function.
179
* to call nih_list_remove() before this function.
173
181
* Returns: @entry which is now a member of one of @hash's bins.
193
201
* @hash: destination hash table,
194
202
* @entry: entry to be added.
196
* Adds @entry to @hash using the value returned by the hash #NihKeyFunction
204
* Adds @entry to @hash using the value returned by the hash NihKeyFunction
197
205
* to indicate which bin the entry should be placed into, provided the key
200
208
* Because the hash table does not store the key of each entry, this requires
201
* that #NihKeyFunction be called for each entry in the destination bin, so
209
* that NihKeyFunction be called for each entry in the destination bin, so
202
210
* should only be used where the uniqueness constraint is required and not
203
211
* already enforced by other code.
205
213
* If @entry is already in another list it is removed so there is no need
206
* to call #nih_list_remove before this function.
214
* to call nih_list_remove() before this function.
208
* Returns: @entry which is now a member of one of @hash's bins or %NULL if
216
* Returns: @entry which is now a member of one of @hash's bins or NULL if
209
217
* an entry already existed with the same key.
234
242
* @hash: destination hash table,
235
243
* @entry: entry to be added.
237
* Adds @entry to @hash using the value returned by the hash #NihKeyFunction
245
* Adds @entry to @hash using the value returned by the hash NihKeyFunction
238
246
* to indicate which bin the entry should be placed into, replacing any
239
247
* existing entry with the same key.
241
249
* Because the hash table does not store the key of each entry, this requires
242
* that #NihKeyFunction be called for each entry in the destination bin, so
250
* that NihKeyFunction be called for each entry in the destination bin, so
243
251
* should only be used where the uniqueness constraint is required and not
244
252
* already enforced by other code.
247
255
* ensure this does not come as a surprise to other code.
249
257
* If @entry is already in another list it is removed so there is no need
250
* to call #nih_list_remove before this function.
258
* to call nih_list_remove() before this function.
252
* Returns: existing entry with the same key replaced in the table, or %NULL
260
* Returns: existing entry with the same key replaced in the table, or NULL
253
261
* if no such entry existed.
285
293
* @entry: previous entry found.
287
295
* Finds all entries in @hash with a key of @key by calling the hash's
288
* #NihKeyFunction on each entry in the appropriate bin, starting with @entry,
296
* NihKeyFunction on each entry in the appropriate bin, starting with @entry,
289
297
* until one is found.
291
* The initial @entry can be found by passing %NULL or using #nih_hash_lookup.
299
* The initial @entry can be found by passing NULL or using nih_hash_lookup().
293
* Returns: next entry in the hash or %NULL if there are no more entries.
301
* Returns: next entry in the hash or NULL if there are no more entries.
296
304
nih_hash_search (NihHash *hash,
323
331
* @key: key to look for.
325
333
* Finds the first entry in @hash with a key of @key by calling the hash's
326
* #NihKeyFunction on each entry in the appropriate bin until one is found.
328
* If multiple entries are expected, use #nih_hash_search instead.
330
* Returns: entry found or %NULL if no entry existed.
334
* NihKeyFunction on each entry in the appropriate bin until one is found.
336
* If multiple entries are expected, use nih_hash_search() instead.
338
* Returns: entry found or NULL if no entry existed.
333
341
nih_hash_lookup (NihHash *hash,