diff options
Diffstat (limited to 'libraries/eina/src/include/eina_hash.h')
-rw-r--r-- | libraries/eina/src/include/eina_hash.h | 1040 |
1 files changed, 1040 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_hash.h b/libraries/eina/src/include/eina_hash.h new file mode 100644 index 0000000..c8eb048 --- /dev/null +++ b/libraries/eina/src/include/eina_hash.h | |||
@@ -0,0 +1,1040 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2002-2008 Carsten Haitzler, Gustavo Sverzut Barbieri, | ||
3 | * Vincent Torri, Jorge Luis Zapata Muga, Cedric Bail | ||
4 | * | ||
5 | * This library is free software; you can redistribute it and/or | ||
6 | * modify it under the terms of the GNU Lesser General Public | ||
7 | * License as published by the Free Software Foundation; either | ||
8 | * version 2.1 of the License, or (at your option) any later version. | ||
9 | * | ||
10 | * This library is distributed in the hope that it will be useful, | ||
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | * Lesser General Public License for more details. | ||
14 | * | ||
15 | * You should have received a copy of the GNU Lesser General Public | ||
16 | * License along with this library; | ||
17 | * if not, see <http://www.gnu.org/licenses/>. | ||
18 | */ | ||
19 | |||
20 | #ifndef EINA_HASH_H_ | ||
21 | #define EINA_HASH_H_ | ||
22 | |||
23 | #include "eina_types.h" | ||
24 | #include "eina_iterator.h" | ||
25 | |||
26 | /** | ||
27 | * @page hash_01_example_page Eina_Hash in action | ||
28 | * @dontinclude eina_hash_01.c | ||
29 | * | ||
30 | * We are going to store some tuples into our table, that will map each @a name | ||
31 | * to a @a number. The cost to access a given number from the name should be | ||
32 | * very small, even with many entries in our table. This is the initial data: | ||
33 | * @skip _Phone_Entry | ||
34 | * @until // _start_entries | ||
35 | * | ||
36 | * Before starting to play with the hash, let's write a callback that will be | ||
37 | * used to free the elements from it. Since we are just storing strduped | ||
38 | * strings, we just need to free them: | ||
39 | * | ||
40 | * @skip static | ||
41 | * @until } | ||
42 | * | ||
43 | * We also need a callback to iterate over the elements of the list later, so | ||
44 | * we are defining it now: | ||
45 | * | ||
46 | * @skip Eina_Bool | ||
47 | * @until } | ||
48 | * | ||
49 | * Now let's create our @ref Eina_Hash using @ref | ||
50 | * eina_hash_string_superfast_new : | ||
51 | * | ||
52 | * @skip eina_init | ||
53 | * @until phone_book | ||
54 | * | ||
55 | * Now we add the keys and data to the hash using @ref eina_hash_add . This | ||
56 | * means that the key is copied inside the table, together with the pointer to | ||
57 | * the data (phone numbers). | ||
58 | * | ||
59 | * @skip for | ||
60 | * @until } | ||
61 | * | ||
62 | * Some basic manipulations with the hash, like finding a value given a key, | ||
63 | * deleting an entry, modifying an entry are exemplified in the following lines. | ||
64 | * Notice that the @ref eina_hash_modify function returns the old value stored | ||
65 | * in that entry, and it needs to be freed, while the @ref eina_hash_del | ||
66 | * function already calls our free callback: | ||
67 | * | ||
68 | * @skip Look for | ||
69 | * @until free( | ||
70 | * | ||
71 | * The @ref eina_hash_set function can be used to set a key-value entry to the | ||
72 | * table if it doesn't exist, or to modify an existent entry. It returns the old | ||
73 | * entry if it was already set, and NULL otherwise. But since it will | ||
74 | * return NULL on error too, we need to check if an error has occurred: | ||
75 | * | ||
76 | * @skip Modify | ||
77 | * @until printf("\n"); | ||
78 | * | ||
79 | * There are different ways of iterate over the entries of a hash. Here we show | ||
80 | * two of them: using @ref eina_hash_foreach and @ref Eina_Iterator . | ||
81 | * | ||
82 | * @skip List of phones | ||
83 | * @until eina_iterator_free(it); | ||
84 | * | ||
85 | * It's also possible to change the key for a specific entry, without having to | ||
86 | * remove the entry from the table and adding it again: | ||
87 | * | ||
88 | * @skipline eina_hash_move | ||
89 | * | ||
90 | * We can remove all the elements from the table without free the table itself: | ||
91 | * | ||
92 | * @skip Empty the phone book | ||
93 | * @until eina_hash_population | ||
94 | * | ||
95 | * Or free the the entire table with its content: | ||
96 | * | ||
97 | * @skipline eina_hash_free | ||
98 | * | ||
99 | * | ||
100 | * The full code for this example can be seen here: @ref eina_hash_01_c | ||
101 | */ | ||
102 | |||
103 | /** | ||
104 | * @page eina_hash_01_c Hash table in action | ||
105 | * | ||
106 | * @include eina_hash_01.c | ||
107 | * @example eina_hash_01.c | ||
108 | */ | ||
109 | |||
110 | /** | ||
111 | * @page hash_02_example_page Different types of tables | ||
112 | * | ||
113 | * This example shows two more types of hash tables that can be created using | ||
114 | * @ref Eina_Hash . For more types, consult the reference documentation of @ref | ||
115 | * eina_hash_new. | ||
116 | * @include eina_hash_02.c | ||
117 | * @example eina_hash_02.c | ||
118 | */ | ||
119 | |||
120 | /** | ||
121 | * @example eina_hash_03.c | ||
122 | * Same example as @ref hash_01_example_page but using a "string small" hash | ||
123 | * table instead of "string superfast". | ||
124 | */ | ||
125 | |||
126 | /** | ||
127 | * @example eina_hash_04.c | ||
128 | * Same example as @ref hash_01_example_page but using a "string djb2" hash | ||
129 | * table instead of "string superfast". | ||
130 | */ | ||
131 | |||
132 | /** | ||
133 | * @example eina_hash_05.c | ||
134 | * Same example as @ref hash_01_example_page but using a "int32" hash | ||
135 | * table instead of "string superfast". | ||
136 | */ | ||
137 | |||
138 | /** | ||
139 | * @example eina_hash_06.c | ||
140 | * Same example as @ref hash_01_example_page but using a "int64" hash | ||
141 | * table instead of "string superfast". | ||
142 | */ | ||
143 | |||
144 | /** | ||
145 | * @example eina_hash_07.c | ||
146 | * Same example as @ref hash_01_example_page but using a "pointer" hash | ||
147 | * table instead of "string superfast". | ||
148 | */ | ||
149 | |||
150 | /** | ||
151 | * @example eina_hash_08.c | ||
152 | * This example shows the the usage of eina_hash_add(), eina_hash_add_by_hash(), | ||
153 | * eina_hash_direct_add_by_hash(), eina_hash_del(), eina_hash_del_by_key_hash(), | ||
154 | * eina_hash_del_by_key(), eina_hash_del_by_data(), eina_hash_find_by_hash() and | ||
155 | * eina_hash_modify_by_hash(). | ||
156 | */ | ||
157 | |||
158 | /** | ||
159 | * @addtogroup Eina_Hash_Group Hash Table | ||
160 | * | ||
161 | * @brief Hash table management. Useful for mapping keys to values. | ||
162 | * | ||
163 | * The hash table is useful for when one wants to implement a table that maps | ||
164 | * keys (usually strings) to data, and have relatively fast access time. The | ||
165 | * performance is proportional to the load factor of the table (number of | ||
166 | * elements / number of buckets). See @ref hashtable_algo for implementation | ||
167 | * details. | ||
168 | * | ||
169 | * Different implementations exists depending on what kind of key will be used | ||
170 | * to access the data: strings, integers, pointers, stringshared or your own. | ||
171 | * | ||
172 | * Eina hash tables can copy the keys when using eina_hash_add() or not when | ||
173 | * using eina_hash_direct_add(). | ||
174 | * | ||
175 | * @section hashtable_algo Algorithm | ||
176 | * | ||
177 | * The Eina_Hash is implemented using an array of N "buckets", where each | ||
178 | * bucket is a pointer to a structure that is the head of a <a | ||
179 | * href="http://en.wikipedia.org/wiki/Red-black_tree">red-black tree</a>. The | ||
180 | * array can then be indexed by the [hash_of_element mod N]. The | ||
181 | * hash_of_element is calculated using the hashing function, passed as | ||
182 | * parameter to the @ref eina_hash_new function. N is the number of buckets | ||
183 | * (array positions), and is calculated based on the buckets_power_size | ||
184 | * (argument of @ref eina_hash_new too). The following picture ilustrates the | ||
185 | * basic idea: | ||
186 | * | ||
187 | * @htmlonly | ||
188 | * <img src="01_hash-table.png" width="500" /> | ||
189 | * @endhtmlonly | ||
190 | * @image latex 01_hash-table.eps | ||
191 | * | ||
192 | * Adding an element to the hash table is made of: | ||
193 | * @li calculating the hash for that key (using the specified hash function); | ||
194 | * @li calculate the array position [hash mod N]; | ||
195 | * @li add the element to the rbtree on that position. | ||
196 | * | ||
197 | * The two first steps have constant time, proportional to the hash function | ||
198 | * being used. Adding the key to the rbtree will be proportional on the number | ||
199 | * of keys on that bucket. | ||
200 | * | ||
201 | * The average cost of lookup depends on the number of keys per | ||
202 | * bucket (load factor) of the table, if the distribution of keys is | ||
203 | * sufficiently uniform. | ||
204 | * | ||
205 | * @section hashtable_perf Performance | ||
206 | * | ||
207 | * As said before, the performance depends on the load factor. So trying to keep | ||
208 | * the load factor as small as possible will improve the hash table performance. But | ||
209 | * increasing the buckets_power_size will also increase the memory consumption. | ||
210 | * The default hash table creation functions already have a good number of | ||
211 | * buckets, enough for most cases. Particularly for strings, if just a few keys | ||
212 | * (less than 30) will be added to the hash table, @ref | ||
213 | * eina_hash_string_small_new should be used, since it will reduce the memory | ||
214 | * consumption for the buckets, and you still won't have many collisions. | ||
215 | * However, @ref eina_hash_string_small_new still uses the same hash calculation | ||
216 | * function that @ref eina_hash_string_superfast_new, which is more complex than | ||
217 | * @ref eina_hash_string_djb2_new. The latter has a faster hash computation | ||
218 | * function, but that will imply on a not so good distribution. But if just a | ||
219 | * few keys are being added, this is not a problem, it will still have not many | ||
220 | * collisions and be faster to calculate the hash than in a hash created with | ||
221 | * @ref eina_hash_string_small_new and @ref eina_hash_string_superfast_new. | ||
222 | * | ||
223 | * A simple comparison between them would be: | ||
224 | * | ||
225 | * @li @c djb2 - faster hash function - 256 buckets (higher memory consumption) | ||
226 | * @li @c string_small - slower hash function but less collisions - 32 buckets | ||
227 | * (lower memory consumption) | ||
228 | * @li @c string_superfast - slower hash function but less collisions - 256 buckets | ||
229 | * (higher memory consumption) | ||
230 | * | ||
231 | * Basically for a very small number of keys (10 or less), @c djb2 should be | ||
232 | * used, or @c string_small if you have a restriction on memory usage. And for a | ||
233 | * higher number of keys, @c string_superfast should be always preferred. | ||
234 | * | ||
235 | * If just stringshared keys are being added, use @ref | ||
236 | * eina_hash_stringshared_new. If a lot of keys will be added to the hash table | ||
237 | * (e.g. more than 1000), then it's better to increase the buckets_power_size. | ||
238 | * See @ref eina_hash_new for more details. | ||
239 | * | ||
240 | * When adding a new key to a hash table, use @ref eina_hash_add or @ref | ||
241 | * eina_hash_direct_add (the latter if this key is already stored elsewhere). If | ||
242 | * the key may be already inside the hash table, instead of checking with | ||
243 | * @ref eina_hash_find and then doing @ref eina_hash_add, one can use just @ref | ||
244 | * eina_hash_set (this will change the data pointed by this key if it was | ||
245 | * already present in the table). | ||
246 | * | ||
247 | * @section hashtable_tutorial Tutorial | ||
248 | * | ||
249 | * These examples show many Eina_Hash functions in action: | ||
250 | * <ul> | ||
251 | * <li> @ref hash_01_example_page | ||
252 | * <li> @ref hash_02_example_page | ||
253 | * <li> Different types of hash in use: | ||
254 | * <ul> | ||
255 | * <li> @ref eina_hash_03.c "string small" | ||
256 | * <li> @ref eina_hash_04.c "string djb2" | ||
257 | * <li> @ref eina_hash_05.c "int32" | ||
258 | * <li> @ref eina_hash_06.c "int64" | ||
259 | * <li> @ref eina_hash_07.c "pointer" | ||
260 | * </ul> | ||
261 | * <li> @ref eina_hash_08.c "Different add and delete functions" | ||
262 | * </ul> | ||
263 | */ | ||
264 | |||
265 | /** | ||
266 | * @addtogroup Eina_Data_Types_Group Data Types | ||
267 | * | ||
268 | * @{ | ||
269 | */ | ||
270 | |||
271 | /** | ||
272 | * @addtogroup Eina_Containers_Group Containers | ||
273 | * | ||
274 | * @{ | ||
275 | */ | ||
276 | |||
277 | /** | ||
278 | * @defgroup Eina_Hash_Group Hash Table | ||
279 | * | ||
280 | * @{ | ||
281 | */ | ||
282 | |||
283 | /** | ||
284 | * @typedef Eina_Hash | ||
285 | * Type for a generic hash table. | ||
286 | */ | ||
287 | typedef struct _Eina_Hash Eina_Hash; | ||
288 | |||
289 | typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple; | ||
290 | |||
291 | struct _Eina_Hash_Tuple | ||
292 | { | ||
293 | const void *key; /**< The key */ | ||
294 | void *data; /**< The data associated to the key */ | ||
295 | unsigned int key_length; /**< The length of the key */ | ||
296 | }; | ||
297 | |||
298 | typedef unsigned int (*Eina_Key_Length)(const void *key); | ||
299 | #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function) | ||
300 | typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length); | ||
301 | #define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function) | ||
302 | typedef int (*Eina_Key_Hash)(const void *key, int key_length); | ||
303 | #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function) | ||
304 | typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata); | ||
305 | |||
306 | |||
307 | /** | ||
308 | * @brief Create a new hash table. | ||
309 | * | ||
310 | * @param key_length_cb The function called when getting the size of the key. | ||
311 | * @param key_cmp_cb The function called when comparing the keys. | ||
312 | * @param key_hash_cb The function called when getting the values. | ||
313 | * @param data_free_cb The function called on each value when the hash table is | ||
314 | * freed, or when an item is deleted from it. @c NULL can be passed as | ||
315 | * callback. | ||
316 | * @param buckets_power_size The size of the buckets. | ||
317 | * @return The new hash table. | ||
318 | * | ||
319 | * This function creates a new hash table using user-defined callbacks | ||
320 | * to manage the hash table. On failure, @c NULL is returned and | ||
321 | * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb | ||
322 | * are @c NULL, @c NULL is returned. If @p buckets_power_size is | ||
323 | * smaller or equal than 2, or if it is greater or equal than 17, | ||
324 | * @c NULL is returned. | ||
325 | * | ||
326 | * The number of buckets created will be 2 ^ @p buckets_power_size. This means | ||
327 | * that if @p buckets_power_size is 5, there will be created 32 buckets. for a | ||
328 | * @p buckets_power_size of 8, there will be 256 buckets. | ||
329 | * | ||
330 | * Pre-defined functions are available to create a hash table. See | ||
331 | * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(), | ||
332 | * eina_hash_string_small_new(), eina_hash_int32_new(), | ||
333 | * eina_hash_int64_new(), eina_hash_pointer_new() and | ||
334 | * eina_hash_stringshared_new(). | ||
335 | */ | ||
336 | EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb, | ||
337 | Eina_Key_Cmp key_cmp_cb, | ||
338 | Eina_Key_Hash key_hash_cb, | ||
339 | Eina_Free_Cb data_free_cb, | ||
340 | int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3); | ||
341 | |||
342 | /** | ||
343 | * @brief Redefine the callback that clean the data of a hash | ||
344 | * | ||
345 | * @param hash The given hash table | ||
346 | * @param data_free_cb The function called on each value when the hash | ||
347 | * table is freed, or when an item is deleted from it. @c NULL can be passed as | ||
348 | * callback. | ||
349 | * @since 1.1 | ||
350 | * See @ref eina_hash_new. | ||
351 | */ | ||
352 | EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1); | ||
353 | |||
354 | /** | ||
355 | * @brief Create a new hash table using the djb2 algorithm. | ||
356 | * | ||
357 | * @param data_free_cb The function called on each value when the hash table | ||
358 | * is freed, or when an item is deleted from it. @c NULL can be passed as | ||
359 | * callback. | ||
360 | * @return The new hash table. | ||
361 | * | ||
362 | * This function creates a new hash table using the djb2 algorithm for | ||
363 | * table management and strcmp() to compare the keys. Values can then | ||
364 | * be looked up with pointers other than the original key pointer that | ||
365 | * was used to add values. On failure, this function returns @c NULL. | ||
366 | */ | ||
367 | EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); | ||
368 | |||
369 | /** | ||
370 | * @brief Create a new hash table for use with strings. | ||
371 | * | ||
372 | * @param data_free_cb The function called on each value when the hash table | ||
373 | * is freed, or when an item is deleted from it. @c NULL can be passed as | ||
374 | * callback. | ||
375 | * @return The new hash table. | ||
376 | * | ||
377 | * This function creates a new hash table using the superfast algorithm | ||
378 | * for table management and strcmp() to compare the keys. Values can | ||
379 | * then be looked up with pointers other than the original key pointer | ||
380 | * that was used to add values. On failure, this function returns | ||
381 | * @c NULL. | ||
382 | */ | ||
383 | EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); | ||
384 | |||
385 | /** | ||
386 | * @brief Create a new hash table for use with strings with small bucket size. | ||
387 | * | ||
388 | * @param data_free_cb The function called on each value when the hash table | ||
389 | * is freed, or when an item is deleted from it. @c NULL can be passed as | ||
390 | * callback. | ||
391 | * @return The new hash table. | ||
392 | * | ||
393 | * This function creates a new hash table using the superfast algorithm | ||
394 | * for table management and strcmp() to compare the keys, but with a | ||
395 | * smaller bucket size (compared to eina_hash_string_superfast_new()) | ||
396 | * which will minimize the memory used by the returned hash | ||
397 | * table. Values can then be looked up with pointers other than the | ||
398 | * original key pointer that was used to add values. On failure, this | ||
399 | * function returns @c NULL. | ||
400 | */ | ||
401 | EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); | ||
402 | |||
403 | /** | ||
404 | * @brief Create a new hash table for use with 32bit integers. | ||
405 | * | ||
406 | * @param data_free_cb The function called on each value when the hash table | ||
407 | * is freed, or when an item is deleted from it. @c NULL can be passed as | ||
408 | * callback. | ||
409 | * @return The new hash table. | ||
410 | * | ||
411 | * This function creates a new hash table where keys are 32bit integers. | ||
412 | * When adding or looking up in the hash table, pointers to 32bit integers | ||
413 | * must be passed. They can be addresses on the stack if you let the | ||
414 | * eina_hash copy the key. Values can then | ||
415 | * be looked up with pointers other than the original key pointer that was | ||
416 | * used to add values. This method is not suitable to match string keys as | ||
417 | * it would only match the first character. | ||
418 | * On failure, this function returns @c NULL. | ||
419 | */ | ||
420 | EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); | ||
421 | |||
422 | /** | ||
423 | * @brief Create a new hash table for use with 64bit integers. | ||
424 | * | ||
425 | * @param data_free_cb The function called on each value when the hash table | ||
426 | * is freed, or when an item is deleted from it. @c NULL can be passed as | ||
427 | * callback. | ||
428 | * @return The new hash table. | ||
429 | * | ||
430 | * This function creates a new hash table where keys are 64bit integers. | ||
431 | * When adding or looking up in the hash table, pointers to 64bit integers | ||
432 | * must be passed. They can be addresses on the stack. Values can then | ||
433 | * be looked up with pointers other than the original key pointer that was | ||
434 | * used to add values. This method is not suitable to match string keys as | ||
435 | * it would only match the first character. | ||
436 | * On failure, this function returns @c NULL. | ||
437 | */ | ||
438 | EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); | ||
439 | |||
440 | /** | ||
441 | * @brief Create a new hash table for use with pointers. | ||
442 | * | ||
443 | * @param data_free_cb The function called on each value when the hash table | ||
444 | * is freed, or when an item is deleted from it. @c NULL can be passed as | ||
445 | * callback. | ||
446 | * @return The new hash table. | ||
447 | * | ||
448 | * This function creates a new hash table using the int64/int32 algorithm for | ||
449 | * table management and dereferenced pointers to compare the | ||
450 | * keys. Values can then be looked up with pointers other than the | ||
451 | * original key pointer that was used to add values. This method may | ||
452 | * appear to be able to match string keys, actually it only matches | ||
453 | * the first character. On failure, this function returns @c NULL. | ||
454 | */ | ||
455 | EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); | ||
456 | |||
457 | /** | ||
458 | * @brief Create a new hash table optimized for stringshared values. | ||
459 | * | ||
460 | * @param data_free_cb The function called on each value when the hash table | ||
461 | * is freed, or when an item is deleted from it. @c NULL can be passed as | ||
462 | * callback. | ||
463 | * @return The new hash table. | ||
464 | * | ||
465 | * This function creates a new hash table optimized for stringshared | ||
466 | * values. Values CAN NOT be looked up with pointers not | ||
467 | * equal to the original key pointer that was used to add a value. On failure, | ||
468 | * this function returns @c NULL. | ||
469 | * | ||
470 | * Excerpt of code that will NOT work with this type of hash: | ||
471 | * | ||
472 | * @code | ||
473 | * extern Eina_Hash *hash; | ||
474 | * extern const char *value; | ||
475 | * const char *a = eina_stringshare_add("key"); | ||
476 | * | ||
477 | * eina_hash_add(hash, a, value); | ||
478 | * eina_hash_find(hash, "key") | ||
479 | * @endcode | ||
480 | */ | ||
481 | EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb); | ||
482 | |||
483 | /** | ||
484 | * @brief Add an entry to the given hash table. | ||
485 | * | ||
486 | * @param hash The given hash table. Cannot be @c NULL. | ||
487 | * @param key A unique key. Cannot be @c NULL. | ||
488 | * @param data Data to associate with the string given by @p key. Cannot be @c | ||
489 | * NULL. | ||
490 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
491 | * | ||
492 | * This function adds @p key to @p hash. @p key is | ||
493 | * expected to be unique within the hash table. Key uniqueness varies | ||
494 | * depending on the type of @p hash: a stringshared @ref Eina_Hash | ||
495 | * need to have unique pointers (which implies unique strings). | ||
496 | * All other string hash types require the strings | ||
497 | * themselves to be unique. Pointer, int32 and int64 hashes need to have these | ||
498 | * values as unique. Failure to use sufficient uniqueness will | ||
499 | * result in unexpected results when inserting data pointers accessed | ||
500 | * with eina_hash_find(), and removed with eina_hash_del(). Key | ||
501 | * strings are case sensitive. If an error occurs, eina_error_get() | ||
502 | * should be used to determine if an allocation error occurred during | ||
503 | * this function. This function returns #EINA_FALSE if an error | ||
504 | * occurred, #EINA_TRUE otherwise. | ||
505 | */ | ||
506 | EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, | ||
507 | const void *key, | ||
508 | const void *data) EINA_ARG_NONNULL(1, 2, 3); | ||
509 | |||
510 | /** | ||
511 | * @brief Add an entry to the given hash table without duplicating the string | ||
512 | * key. | ||
513 | * | ||
514 | * @param hash The given hash table. Cannot be @c NULL. | ||
515 | * @param key A unique key. Cannot be @c NULL. | ||
516 | * @param data Data to associate with the string given by @p key. Cannot be @c | ||
517 | * NULL | ||
518 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
519 | * | ||
520 | * This function adds @p key to @p hash. @p key is | ||
521 | * expected to be unique within the hash table. Key uniqueness varies | ||
522 | * depending on the type of @p hash: a stringshared @ref Eina_Hash | ||
523 | * need have unique pointers (which implies unique strings). | ||
524 | * All other string hash types require the strings | ||
525 | * themselves to be unique. Pointer, int32 and int64 hashes need to have these | ||
526 | * values as unique. Failure to use sufficient uniqueness will | ||
527 | * result in unexpected results when inserting data pointers accessed | ||
528 | * with eina_hash_find(), and removed with eina_hash_del(). This | ||
529 | * function does not make a copy of @p key, so it must be a string | ||
530 | * constant or stored elsewhere ( in the object being added). Key | ||
531 | * strings are case sensitive. If an error occurs, eina_error_get() | ||
532 | * should be used to determine if an allocation error occurred during | ||
533 | * this function. This function returns #EINA_FALSE if an error | ||
534 | * occurred, #EINA_TRUE otherwise. | ||
535 | */ | ||
536 | EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, | ||
537 | const void *key, | ||
538 | const void *data) EINA_ARG_NONNULL(1, 2, 3); | ||
539 | |||
540 | /** | ||
541 | * @brief Remove the entry identified by a key or a data from the given | ||
542 | * hash table. | ||
543 | * | ||
544 | * @param hash The given hash table. | ||
545 | * @param key The key. | ||
546 | * @param data The data pointer to remove if the key is @c NULL. | ||
547 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
548 | * | ||
549 | * This function removes the entry identified by @p key or @p data | ||
550 | * from @p hash. If a free function was given to the | ||
551 | * callback on creation, it will be called for the data being | ||
552 | * deleted. If @p hash is @c NULL, the functions returns immediately | ||
553 | * #EINA_FALSE. If @p key is @c NULL, then @p data is used to find the a | ||
554 | * match to remove, otherwise @p key is used and @p data is not | ||
555 | * required and can be @c NULL. This function returns #EINA_FALSE if | ||
556 | * an error occurred, #EINA_TRUE otherwise. | ||
557 | * | ||
558 | * @note if you know you already have the key, use | ||
559 | * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you | ||
560 | * know you don't have the key, use eina_hash_del_by_data() | ||
561 | * directly. | ||
562 | */ | ||
563 | EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, | ||
564 | const void *key, | ||
565 | const void *data) EINA_ARG_NONNULL(1); | ||
566 | |||
567 | /** | ||
568 | * @brief Retrieve a specific entry in the given hash table. | ||
569 | * | ||
570 | * @param hash The given hash table. | ||
571 | * @param key The key of the entry to find. | ||
572 | * @return The data pointer for the stored entry on success, @c NULL | ||
573 | * otherwise. | ||
574 | * | ||
575 | * This function retrieves the entry associated to @p key in | ||
576 | * @p hash. If @p hash is @c NULL, this function returns immediately | ||
577 | * @c NULL. This function returns the data pointer on success, @c NULL | ||
578 | * otherwise. | ||
579 | */ | ||
580 | EAPI void *eina_hash_find(const Eina_Hash *hash, | ||
581 | const void *key) EINA_ARG_NONNULL(1, 2); | ||
582 | |||
583 | /** | ||
584 | * @brief Modify the entry pointer at the specified key and return the old | ||
585 | * entry. | ||
586 | * @param hash The given hash table. | ||
587 | * @param key The key of the entry to modify. | ||
588 | * @param data The data to replace the old entry. | ||
589 | * @return The data pointer for the old stored entry on success, or | ||
590 | * @c NULL otherwise. | ||
591 | * | ||
592 | * This function modifies the data of @p key with @p data in @p | ||
593 | * hash. If no entry is found, nothing is added to @p hash. On success | ||
594 | * this function returns the old entry, otherwise it returns @c NULL. | ||
595 | */ | ||
596 | EAPI void *eina_hash_modify(Eina_Hash *hash, | ||
597 | const void *key, | ||
598 | const void *data) EINA_ARG_NONNULL(1, 2, 3); | ||
599 | |||
600 | /** | ||
601 | * @brief Modify the entry pointer at the specified key and return the | ||
602 | * old entry or add the entry if not found. | ||
603 | * | ||
604 | * @param hash The given hash table. | ||
605 | * @param key The key of the entry to modify. | ||
606 | * @param data The data to replace the old entry | ||
607 | * @return The data pointer for the old stored entry, or @c NULL | ||
608 | * otherwise. | ||
609 | * | ||
610 | * This function modifies the data of @p key with @p data in @p | ||
611 | * hash. If no entry is found, @p data is added to @p hash with the | ||
612 | * key @p key. On success this function returns the old entry, | ||
613 | * otherwise it returns @c NULL. To check for errors, use | ||
614 | * eina_error_get(). | ||
615 | */ | ||
616 | EAPI void *eina_hash_set(Eina_Hash *hash, | ||
617 | const void *key, | ||
618 | const void *data) EINA_ARG_NONNULL(1, 2); | ||
619 | |||
620 | /** | ||
621 | * @brief Change the key associated with a data without triggering the | ||
622 | * free callback. | ||
623 | * | ||
624 | * @param hash The given hash table. | ||
625 | * @param old_key The current key associated with the data | ||
626 | * @param new_key The new key to associate data with | ||
627 | * @return EINA_FALSE in any case but success, EINA_TRUE on success. | ||
628 | * | ||
629 | * This function allows for the move of data from one key to another, | ||
630 | * but does not call the Eina_Free_Cb associated with the hash table | ||
631 | * when destroying the old key. | ||
632 | */ | ||
633 | EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, | ||
634 | const void *old_key, | ||
635 | const void *new_key) EINA_ARG_NONNULL(1, 2, 3); | ||
636 | |||
637 | /** | ||
638 | * Free the given hash table resources. | ||
639 | * | ||
640 | * @param hash The hash table to be freed. | ||
641 | * | ||
642 | * This function frees up all the memory allocated to storing @p hash, | ||
643 | * and call the free callback if it has been passed to the hash table | ||
644 | * at creation time. If no free callback has been passed, any entries | ||
645 | * in the table that the program has no more pointers for elsewhere | ||
646 | * may now be lost, so this should only be called if the program has | ||
647 | * already freed any allocated data in the hash table or has the | ||
648 | * pointers for data in the table stored elsewhere as well. If @p hash | ||
649 | * is @c NULL, the function returns immediately. | ||
650 | * | ||
651 | * Example: | ||
652 | * @code | ||
653 | * extern Eina_Hash *hash; | ||
654 | * | ||
655 | * eina_hash_free(hash); | ||
656 | * hash = NULL; | ||
657 | * @endcode | ||
658 | */ | ||
659 | EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1); | ||
660 | |||
661 | /** | ||
662 | * Free the given hash table buckets resources. | ||
663 | * | ||
664 | * @param hash The hash table whose buckets have to be freed. | ||
665 | * | ||
666 | * This function frees up all the memory allocated to storing the | ||
667 | * buckets of @p hash, and calls the free callback on all hash table | ||
668 | * buckets if it has been passed to the hash table at creation time, | ||
669 | * then frees the buckets. If no free callback has been passed, no | ||
670 | * buckets value will be freed. If @p hash is @c NULL, the function | ||
671 | * returns immediately. | ||
672 | */ | ||
673 | EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1); | ||
674 | |||
675 | /** | ||
676 | * @brief Returns the number of entries in the given hash table. | ||
677 | * | ||
678 | * @param hash The given hash table. | ||
679 | * @return The number of entries in the hash table. | ||
680 | * | ||
681 | * This function returns the number of entries in @p hash, or 0 on | ||
682 | * error. If @p hash is @c NULL, 0 is returned. | ||
683 | */ | ||
684 | EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1); | ||
685 | |||
686 | /** | ||
687 | * @brief Add an entry to the given hash table. | ||
688 | * | ||
689 | * @param hash The given hash table. Cannot be @c NULL. | ||
690 | * @param key A unique key. Cannot be @c NULL. | ||
691 | * @param key_length The length of the key. | ||
692 | * @param key_hash The hash that will always match key. | ||
693 | * @param data The data to associate with the string given by the key. Cannot be | ||
694 | * @c NULL. | ||
695 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
696 | * | ||
697 | * This function adds @p key to @p hash. @p hash, @p key and @p data | ||
698 | * cannot be @c NULL, in that case #EINA_FALSE is returned. @p key is | ||
699 | * expected to be a unique within the hash table. Otherwise, | ||
700 | * one cannot be sure which inserted data pointer will be accessed | ||
701 | * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do | ||
702 | * not forget to count '\\0' for string when setting the value of | ||
703 | * @p key_length. @p key_hash is expected to always match | ||
704 | * @p key. Otherwise, one cannot be sure to find it again with @ref | ||
705 | * eina_hash_find_by_hash. Key strings are case sensitive. If an error | ||
706 | * occurs, eina_error_get() should be used to determine if an | ||
707 | * allocation error occurred during this function. This function | ||
708 | * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
709 | * | ||
710 | * @see eina_hash_add() | ||
711 | */ | ||
712 | EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash, | ||
713 | const void *key, | ||
714 | int key_length, | ||
715 | int key_hash, | ||
716 | const void *data) EINA_ARG_NONNULL(1, 2, 5); | ||
717 | |||
718 | /** | ||
719 | * @brief Add an entry to the given hash table and do not duplicate the string | ||
720 | * key. | ||
721 | * | ||
722 | * @param hash The given hash table. Cannot be @c NULL. | ||
723 | * @param key A unique key. Cannot be @c NULL. | ||
724 | * @param key_length Should be the length of @p key (don't forget to count | ||
725 | * '\\0' for string). | ||
726 | * @param key_hash The hash that will always match key. | ||
727 | * @param data Data to associate with the string given by @p key. Cannot be @c | ||
728 | * NULL. | ||
729 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
730 | * | ||
731 | * This function adds @p key to @p hash. @p hash, @p key and @p data | ||
732 | * can be @c NULL, in that case #EINA_FALSE is returned. @p key is | ||
733 | * expected to be unique within the hash table. Otherwise, | ||
734 | * one cannot be sure which inserted data pointer will be accessed | ||
735 | * with @ref eina_hash_find, and removed with @ref eina_hash_del. This | ||
736 | * function does not make a copy of @p key so it must be a string | ||
737 | * constant or stored elsewhere (in the object being added). Do | ||
738 | * not forget to count '\\0' for string when setting the value of | ||
739 | * @p key_length. @p key_hash is expected to always match | ||
740 | * @p key. Otherwise, one cannot be sure to find it again with @ref | ||
741 | * eina_hash_find_by_hash. Key strings are case sensitive. If an error | ||
742 | * occurs, eina_error_get() should be used to determine if an | ||
743 | * allocation error occurred during this function. This function | ||
744 | * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
745 | * | ||
746 | * @see eina_hash_direct_add() | ||
747 | */ | ||
748 | EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash, | ||
749 | const void *key, | ||
750 | int key_length, | ||
751 | int key_hash, | ||
752 | const void *data) EINA_ARG_NONNULL(1, 2, 5); | ||
753 | |||
754 | /** | ||
755 | * @brief Remove the entry identified by a key and a key hash from the given | ||
756 | * hash table. | ||
757 | * | ||
758 | * @param hash The given hash table. Cannot be @c NULL. | ||
759 | * @param key The key. Cannot be @c NULL. | ||
760 | * @param key_length The length of the key. | ||
761 | * @param key_hash The hash that always match the key. | ||
762 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
763 | * | ||
764 | * This function removes the entry identified by @p key and | ||
765 | * @p key_hash from @p hash. If a free function was given to the | ||
766 | * callback on creation, it will be called for the data being | ||
767 | * deleted. Do not forget to count '\\0' for string when setting the | ||
768 | * value of @p key_length. If @p hash or @p key are @c NULL, the | ||
769 | * functions returns immediately #EINA_FALSE. This function returns | ||
770 | * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
771 | * | ||
772 | * @note if you don't have the key_hash, use eina_hash_del_by_key() instead. | ||
773 | * @note if you don't have the key, use eina_hash_del_by_data() instead. | ||
774 | */ | ||
775 | EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, | ||
776 | const void *key, | ||
777 | int key_length, | ||
778 | int key_hash) EINA_ARG_NONNULL(1, 2); | ||
779 | |||
780 | /** | ||
781 | * @brief Remove the entry identified by a key from the given hash table. | ||
782 | * | ||
783 | * This version will calculate key length and hash by using functions | ||
784 | * provided to hash creation function. | ||
785 | * | ||
786 | * @param hash The given hash table. Cannot be @c NULL. | ||
787 | * @param key The key. Cannot be @c NULL. | ||
788 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
789 | * | ||
790 | * This function removes the entry identified by @p key from @p | ||
791 | * hash. The key length and hash will be calculated automatically by | ||
792 | * using functiond provided to has creation function. If a free | ||
793 | * function was given to the callback on creation, it will be called | ||
794 | * for the data being deleted. If @p hash or @p key are @c NULL, the | ||
795 | * functions returns immediately #EINA_FALSE. This function returns | ||
796 | * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
797 | * | ||
798 | * @note if you already have the key_hash, use eina_hash_del_by_key_hash() | ||
799 | * instead. | ||
800 | * @note if you don't have the key, use eina_hash_del_by_data() instead. | ||
801 | */ | ||
802 | EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, | ||
803 | const void *key) EINA_ARG_NONNULL(1, 2); | ||
804 | |||
805 | /** | ||
806 | * @brief Remove the entry identified by a data from the given hash table. | ||
807 | * | ||
808 | * This version is slow since there is no quick access to nodes based on data. | ||
809 | * | ||
810 | * @param hash The given hash table. Cannot be @c NULL. | ||
811 | * @param data The data value to search and remove. Cannot be @c NULL. | ||
812 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
813 | * thing goes fine. | ||
814 | * | ||
815 | * This function removes the entry identified by @p data from @p | ||
816 | * hash. If a free function was given to the callback on creation, it | ||
817 | * will be called for the data being deleted. If @p hash or @p data | ||
818 | * are @c NULL, the functions returns immediately #EINA_FALSE. This | ||
819 | * function returns #EINA_FALSE if an error occurred, #EINA_TRUE | ||
820 | * otherwise. | ||
821 | * | ||
822 | * @note if you already have the key, use eina_hash_del_by_key() or | ||
823 | * eina_hash_del_by_key_hash() instead. | ||
824 | */ | ||
825 | EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, | ||
826 | const void *data) EINA_ARG_NONNULL(1, 2); | ||
827 | |||
828 | /** | ||
829 | * @brief Remove the entry identified by a key and a key hash or a | ||
830 | * data from the given hash table. | ||
831 | * | ||
832 | * If @p key is @c NULL, then @p data is used to find a match to | ||
833 | * remove. | ||
834 | * | ||
835 | * @param hash The given hash table. Cannot be @c NULL. | ||
836 | * @param key The key. | ||
837 | * @param key_length The length of the key. | ||
838 | * @param key_hash The hash that always match the key. | ||
839 | * @param data The data pointer to remove if the key is @c NULL. | ||
840 | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
841 | * | ||
842 | * This function removes the entry identified by @p key and | ||
843 | * @p key_hash, or @p data, from @p hash. If a free function was given to | ||
844 | * the callback on creation, it will be called for the data being | ||
845 | * deleted. If @p hash is @c NULL, the functions returns immediately | ||
846 | * #EINA_FALSE. If @p key is @c NULL, then @p key_length and @p key_hash | ||
847 | * are ignored and @p data is used to find a match to remove, | ||
848 | * otherwise @p key and @p key_hash are used and @p data is not | ||
849 | * required and can be @c NULL. Do not forget to count '\\0' for | ||
850 | * string when setting the value of @p key_length. This function | ||
851 | * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | ||
852 | * | ||
853 | * @note if you know you already have the key, use eina_hash_del_by_key_hash(), | ||
854 | * if you know you don't have the key, use eina_hash_del_by_data() | ||
855 | * directly. | ||
856 | */ | ||
857 | EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, | ||
858 | const void *key, | ||
859 | int key_length, | ||
860 | int key_hash, | ||
861 | const void *data) EINA_ARG_NONNULL(1); | ||
862 | |||
863 | /** | ||
864 | * @brief Retrieve a specific entry in the given hash table. | ||
865 | * | ||
866 | * @param hash The given hash table. Cannot be @c NULL. | ||
867 | * @param key The key of the entry to find. | ||
868 | * @param key_length The length of the key. | ||
869 | * @param key_hash The hash that always match the key | ||
870 | * @return The data pointer for the stored entry on success, @c NULL | ||
871 | * otherwise. | ||
872 | * | ||
873 | * This function retrieves the entry associated to @p key of length | ||
874 | * @p key_length in @p hash. @p key_hash is the hash that always match | ||
875 | * @p key. It is ignored if @p key is @c NULL. Do not forget to count | ||
876 | * '\\0' for string when setting the value of @p key_length. If | ||
877 | * @p hash is @c NULL, this function returns immediately @c NULL. This | ||
878 | * function returns the data pointer on success, @c NULL otherwise. | ||
879 | */ | ||
880 | EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, | ||
881 | const void *key, | ||
882 | int key_length, | ||
883 | int key_hash) EINA_ARG_NONNULL(1, 2); | ||
884 | |||
885 | /** | ||
886 | * @brief Modify the entry pointer at the specified key and returns | ||
887 | * the old entry. | ||
888 | * | ||
889 | * @param hash The given hash table. | ||
890 | * @param key The key of the entry to modify. | ||
891 | * @param key_length Should be the length of @p key (don't forget to count | ||
892 | * '\\0' for string). | ||
893 | * @param key_hash The hash that always match the key. Ignored if @p key is | ||
894 | * @c NULL. | ||
895 | * @param data The data to replace the old entry, if it exists. | ||
896 | * @return The data pointer for the old stored entry, or @c NULL if not | ||
897 | * found. If an existing entry is not found, nothing is added to the | ||
898 | * hash. | ||
899 | */ | ||
900 | EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, | ||
901 | const void *key, | ||
902 | int key_length, | ||
903 | int key_hash, | ||
904 | const void *data) EINA_ARG_NONNULL(1, 2, 5); | ||
905 | |||
906 | /** | ||
907 | * @brief Returned a new iterator associated to hash keys. | ||
908 | * | ||
909 | * @param hash The hash. | ||
910 | * @return A new iterator. | ||
911 | * | ||
912 | * This function returns a newly allocated iterator associated to @p | ||
913 | * hash. If @p hash is not populated, this function still returns a | ||
914 | * valid iterator that will always return false on | ||
915 | * eina_iterator_next(), thus keeping API sane. | ||
916 | * | ||
917 | * If the memory can not be allocated, NULL is returned and | ||
918 | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | ||
919 | * returned. | ||
920 | * | ||
921 | * @warning if the hash structure changes then the iterator becomes | ||
922 | * invalid! That is, if you add or remove items this iterator | ||
923 | * behavior is undefined and your program may crash! | ||
924 | */ | ||
925 | EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
926 | |||
927 | /** | ||
928 | * @brief Returned a new iterator associated to hash data. | ||
929 | * | ||
930 | * @param hash The hash. | ||
931 | * @return A new iterator. | ||
932 | * | ||
933 | * This function returns a newly allocated iterator associated to | ||
934 | * @p hash. If @p hash is not populated, this function still returns a | ||
935 | * valid iterator that will always return false on | ||
936 | * eina_iterator_next(), thus keeping API sane. | ||
937 | * | ||
938 | * If the memory can not be allocated, @c NULL is returned and | ||
939 | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | ||
940 | * returned. | ||
941 | * | ||
942 | * @warning if the hash structure changes then the iterator becomes | ||
943 | * invalid. That is, if you add or remove items this iterator behavior | ||
944 | * is undefined and your program may crash. | ||
945 | */ | ||
946 | EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
947 | |||
948 | /** | ||
949 | * @brief Returned a new iterator associated to hash keys and data. | ||
950 | * | ||
951 | * @param hash The hash. | ||
952 | * @return A new iterator. | ||
953 | * | ||
954 | * This function returns a newly allocated iterator associated to @p | ||
955 | * hash. If @p hash is not populated, this function still returns a | ||
956 | * valid iterator that will always return false on | ||
957 | * eina_iterator_next(), thus keeping API sane. | ||
958 | * | ||
959 | * If the memory can not be allocated, NULL is returned and | ||
960 | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | ||
961 | * returned. | ||
962 | * | ||
963 | * @note iterator data will provide values as Eina_Hash_Tuple that should not | ||
964 | * be modified! | ||
965 | * | ||
966 | * @warning if the hash structure changes then the iterator becomes | ||
967 | * invalid! That is, if you add or remove items this iterator | ||
968 | * behavior is undefined and your program may crash! | ||
969 | */ | ||
970 | EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
971 | |||
972 | /** | ||
973 | * @brief Call a function on every member stored in the hash table | ||
974 | * | ||
975 | * @param hash The hash table whose members will be walked | ||
976 | * @param func The function to call on each parameter | ||
977 | * @param fdata The data pointer to pass to the function being called | ||
978 | * | ||
979 | * This function goes through every entry in the hash table @p hash and calls | ||
980 | * the function @p func on each member. The function should @b not modify the | ||
981 | * hash table contents if it returns 1. @b If the hash table contents are | ||
982 | * modified by this function or the function wishes to stop processing it must | ||
983 | * return 0, otherwise return 1 to keep processing. | ||
984 | * | ||
985 | * Example: | ||
986 | * @code | ||
987 | * extern Eina_Hash *hash; | ||
988 | * | ||
989 | * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key, | ||
990 | * void *data, void *fdata) | ||
991 | * { | ||
992 | * printf("Func data: %s, Hash entry: %s / %p\n", | ||
993 | * fdata, (const char *)key, data); | ||
994 | * return 1; | ||
995 | * } | ||
996 | * | ||
997 | * int main(int argc, char **argv) | ||
998 | * { | ||
999 | * char *hash_fn_data; | ||
1000 | * | ||
1001 | * hash_fn_data = strdup("Hello World"); | ||
1002 | * eina_hash_foreach(hash, hash_fn, hash_fn_data); | ||
1003 | * free(hash_fn_data); | ||
1004 | * } | ||
1005 | * @endcode | ||
1006 | */ | ||
1007 | EAPI void eina_hash_foreach(const Eina_Hash *hash, | ||
1008 | Eina_Hash_Foreach cb, | ||
1009 | const void *fdata) EINA_ARG_NONNULL(1, 2); | ||
1010 | /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */ | ||
1011 | EAPI int eina_hash_superfast(const char *key, | ||
1012 | int len) EINA_ARG_NONNULL(1); | ||
1013 | /* Hash function first reported by dan bernstein many years ago in comp.lang.c */ | ||
1014 | static inline int eina_hash_djb2(const char *key, | ||
1015 | int len) EINA_ARG_NONNULL(1); | ||
1016 | static inline int eina_hash_djb2_len(const char *key, | ||
1017 | int *plen) EINA_ARG_NONNULL(1, 2); | ||
1018 | /* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */ | ||
1019 | static inline int eina_hash_int32(const unsigned int *pkey, | ||
1020 | int len) EINA_ARG_NONNULL(1); | ||
1021 | static inline int eina_hash_int64(const unsigned long int *pkey, | ||
1022 | int len) EINA_ARG_NONNULL(1); | ||
1023 | /* http://sites.google.com/site/murmurhash/ */ | ||
1024 | static inline int eina_hash_murmur3(const char *key, | ||
1025 | int len) EINA_ARG_NONNULL(1); | ||
1026 | #include "eina_inline_hash.x" | ||
1027 | |||
1028 | /** | ||
1029 | * @} | ||
1030 | */ | ||
1031 | |||
1032 | /** | ||
1033 | * @} | ||
1034 | */ | ||
1035 | |||
1036 | /** | ||
1037 | * @} | ||
1038 | */ | ||
1039 | |||
1040 | #endif /*EINA_HASH_H_*/ | ||