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
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.
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.
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/>.
23 #include "eina_types.h"
24 #include "eina_iterator.h"
27 * @addtogroup Eina_Hash_Group Hash Table
29 * @brief give a small description here : what it is for, what it does
31 * Different implementations exists depending on what to store: strings,
32 * integers, pointers, stringshared or your own...
33 * Eina hash tables can copy the keys when using eina_hash_add() or not when
34 * using eina_hash_direct_add().
36 * Hash API. Give some hints about the use (functions that must be
37 * used like init / shutdown), general use, etc... Give also a link to
40 * @section hashtable_algo Algorithm
42 * Give here the algorithm used in the implementation
44 * @section hashtable_perf Performance
46 * Give some hints about performance if it is possible, and an image !
48 * @section hashtable_tutorial Tutorial
50 * Here is a fantastic tutorial about our hash table
56 * @addtogroup Eina_Data_Types_Group Data Types
62 * @addtogroup Eina_Containers_Group Containers
68 * @defgroup Eina_Hash_Group Hash Table
75 * Type for a generic hash table.
77 typedef struct _Eina_Hash Eina_Hash;
79 typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple;
81 struct _Eina_Hash_Tuple
83 const void *key; /**< The key */
84 void *data; /**< The data associated to the key */
85 unsigned int key_length; /**< The length of the key */
88 typedef unsigned int (*Eina_Key_Length)(const void *key);
89 #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
90 typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
91 #define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function)
92 typedef int (*Eina_Key_Hash)(const void *key, int key_length);
93 #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function)
94 typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata);
98 * @brief Create a new hash table.
100 * @param key_length_cb The function called when getting the size of the key.
101 * @param key_cmp_cb The function called when comparing the keys.
102 * @param key_hash_cb The function called when getting the values.
103 * @param data_free_cb The function called when the hash table is freed.
104 * @param buckets_power_size The size of the buckets.
105 * @return The new hash table.
107 * This function creates a new hash table using user-defined callbacks
108 * to manage the hash table. On failure, @c NULL is returned and
109 * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb
110 * are @c NULL, @c NULL is returned. If @p buckets_power_size is
111 * smaller or equal than 2, or if it is greater or equal than 17,
112 * @c NULL is returned.
114 * Pre-defined functions are available to create a hash table. See
115 * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(),
116 * eina_hash_string_small_new(), eina_hash_int32_new(),
117 * eina_hash_int64_new(), eina_hash_pointer_new() and
118 * eina_hash_stringshared_new().
120 EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
121 Eina_Key_Cmp key_cmp_cb,
122 Eina_Key_Hash key_hash_cb,
123 Eina_Free_Cb data_free_cb,
124 int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
127 * @brief Create a new hash table using the djb2 algorithm.
129 * @param data_free_cb The function called when the hash table is freed.
130 * @return The new hash table.
132 * This function creates a new hash table using the djb2 algorithm for
133 * table management and strcmp() to compare the keys. Values can then
134 * be looked up with pointers other than the original key pointer that
135 * was used to add values. On failure, this function returns @c NULL.
136 * @p data_free_cb is a callback called when the hash table is
137 * freed. @c NULL can be passed as callback.
139 EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
142 * @brief Create a new hash table for use with strings.
144 * @param data_free_cb The function called when the hash table is freed.
145 * @return The new hash table.
147 * This function creates a new hash table using the superfast algorithm
148 * for table management and strcmp() to compare the keys. Values can
149 * then be looked up with pointers other than the original key pointer
150 * that was used to add values. On failure, this function returns
151 * @c NULL. @p data_free_cb is a callback called when the hash table is
152 * freed. @c NULL can be passed as callback.
154 EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
157 * @brief Create a new hash table for use with strings with small bucket size.
159 * @param data_free_cb The function called when the hash table is freed.
160 * @return The new hash table.
162 * This function creates a new hash table using the superfast algorithm
163 * for table management and strcmp() to compare the keys, but with a
164 * smaller bucket size (compared to eina_hash_string_superfast_new())
165 * which will minimize the memory used by the returned hash
166 * table. Values can then be looked up with pointers other than the
167 * original key pointer that was used to add values. On failure, this
168 * function returns @c NULL. @p data_free_cb is a callback called when
169 * the hash table is freed. @c NULL can be passed as callback.
171 EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
174 * @brief Create a new hash table for use with 32bit integers.
176 * @param data_free_cb The function called when the hash table is freed.
177 * @return The new hash table.
179 * This function creates a new hash table where keys are 32bit integers.
180 * When adding or looking up in the hash table, pointers to 32bit integers
181 * must be passed. They can be addresses on the stack if you let the
182 * eina_hash copy the key. Values can then
183 * be looked up with pointers other than the original key pointer that was
184 * used to add values. This method is not suitable to match string keys as
185 * it would only match the first character.
186 * On failure, this function returns @c NULL.
187 * @p data_free_cb is a callback called when the hash table is freed.
188 * @c NULL can be passed as callback.
190 EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
193 * @brief Create a new hash table for use with 64bit integers.
195 * @param data_free_cb The function called when the hash table is freed.
196 * @return The new hash table.
198 * This function creates a new hash table where keys are 64bit integers.
199 * When adding or looking up in the hash table, pointers to 64bit integers
200 * must be passed. They can be addresses on the stack. Values can then
201 * be looked up with pointers other than the original key pointer that was
202 * used to add values. This method is not suitable to match string keys as
203 * it would only match the first character.
204 * On failure, this function returns @c NULL.
205 * @p data_free_cb is a callback called when the hash table is freed.
206 * @c NULL can be passed as callback.
208 EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
211 * @brief Create a new hash table for use with pointers.
213 * @param data_free_cb The function called when the hash table is freed.
214 * @return The new hash table.
216 * This function creates a new hash table using the int64/int32 algorithm for
217 * table management and dereferenced pointers to compare the
218 * keys. Values can then be looked up with pointers other than the
219 * original key pointer that was used to add values. This method may
220 * appear to be able to match string keys, actually it only matches
221 * the first character. On failure, this function returns @c NULL.
222 * @p data_free_cb is a callback called when the hash table is freed.
223 * @c NULL can be passed as callback.
225 EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
228 * @brief Create a new hash table optimized for stringshared values.
230 * @param data_free_cb The function called when the hash table is freed.
231 * @return The new hash table.
233 * This function creates a new hash table optimized for stringshared
234 * values. Values CAN NOT be looked up with pointers not
235 * equal to the original key pointer that was used to add a value. On failure,
236 * this function returns @c NULL.
237 * @p data_free_cb is a callback called when the hash table is freed.
238 * @c NULL can be passed as callback.
240 * Excerpt of code that will NOT work with this type of hash:
243 * extern Eina_Hash *hash;
244 * extern const char *value;
245 * const char *a = eina_stringshare_add("key");
247 * eina_hash_add(hash, a, value);
248 * eina_hash_find(hash, "key")
251 EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
254 * @brief Add an entry to the given hash table.
256 * @param hash The given hash table.
257 * @param key A unique key.
258 * @param data Data to associate with the string given by @p key.
259 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
261 * This function adds @p key to @p hash. @p hash, @p key and @p data
262 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
263 * expected to be unique within the hash table. Key uniqueness varies
264 * depending on the type of @p hash: a stringshared @ref Eina_Hash
265 * need only have unique pointers for keys, but the strings in the
266 * pointers may be identical. All other hash types require the strings
267 * themselves to be unique. Failure to use sufficient uniqueness will
268 * result in unexpected results when inserting data pointers accessed
269 * with eina_hash_find(), and removed with eina_hash_del(). Key
270 * strings are case sensitive. If an error occurs, eina_error_get()
271 * should be used to determine if an allocation error occurred during
272 * this function. This function returns #EINA_FALSE if an error
273 * occurred, #EINA_TRUE otherwise.
275 EAPI Eina_Bool eina_hash_add(Eina_Hash *hash,
277 const void *data) EINA_ARG_NONNULL(1, 2, 3);
280 * @brief Add an entry to the given hash table without duplicating the string
283 * @param hash The given hash table. Can be @c NULL.
284 * @param key A unique key. Can be @c NULL.
285 * @param data Data to associate with the string given by @p key.
286 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
288 * This function adds @p key to @p hash. @p hash, @p key and @p data
289 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
290 * expected to be unique within the hash table. Key uniqueness varies
291 * depending on the type of @p hash: a stringshared @ref Eina_Hash
292 * need only have unique pointers for keys, but the strings in the
293 * pointers may be identical. All other hash types require the strings
294 * themselves to be unique. Failure to use sufficient uniqueness will
295 * result in unexpected results when inserting data pointers accessed
296 * with eina_hash_find(), and removed with eina_hash_del(). This
297 * function does not make a copy of @p key, so it must be a string
298 * constant or stored elsewhere ( in the object being added). Key
299 * strings are case sensitive. If an error occurs, eina_error_get()
300 * should be used to determine if an allocation error occurred during
301 * this function. This function returns #EINA_FALSE if an error
302 * occurred, #EINA_TRUE otherwise.
304 EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash,
306 const void *data) EINA_ARG_NONNULL(1, 2, 3);
309 * @brief Remove the entry identified by a key or a data from the given
312 * @param hash The given hash table.
313 * @param key The key.
314 * @param data The data pointer to remove if the key is @c NULL.
315 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
317 * This function removes the entry identified by @p key or @p data
318 * from @p hash. If a free function was given to the
319 * callback on creation, it will be called for the data being
320 * deleted. If @p hash is @c NULL, the functions returns immediately
321 * #EINA_FALSE. If @p key is @c NULL, then @p data is used to find the a
322 * match to remove, otherwise @p key is used and @p data is not
323 * required and can be @c NULL. This function returns #EINA_FALSE if
324 * an error occurred, #EINA_TRUE otherwise.
326 * @note if you know you already have the key, use
327 * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
328 * know you don't have the key, use eina_hash_del_by_data()
331 EAPI Eina_Bool eina_hash_del(Eina_Hash *hash,
333 const void *data) EINA_ARG_NONNULL(1);
336 * @brief Retrieve a specific entry in the given hash table.
338 * @param hash The given hash table.
339 * @param key The key of the entry to find.
340 * @return The data pointer for the stored entry on success, @c NULL
343 * This function retrieves the entry associated to @p key in
344 * @p hash. If @p hash is @c NULL, this function returns immediately
345 * @c NULL. This function returns the data pointer on success, @c NULL
348 EAPI void *eina_hash_find(const Eina_Hash *hash,
349 const void *key) EINA_ARG_NONNULL(1, 2);
352 * @brief Modify the entry pointer at the specified key and return the old
354 * @param hash The given hash table.
355 * @param key The key of the entry to modify.
356 * @param data The data to replace the old entry.
357 * @return The data pointer for the old stored entry on success, or
360 * This function modifies the data of @p key with @p data in @p
361 * hash. If no entry is found, nothing is added to @p hash. On success
362 * this function returns the old entry, otherwise it returns @c NULL.
364 EAPI void *eina_hash_modify(Eina_Hash *hash,
366 const void *data) EINA_ARG_NONNULL(1, 2, 3);
369 * @brief Modify the entry pointer at the specified key and return the
370 * old entry or add the entry if not found.
372 * @param hash The given hash table.
373 * @param key The key of the entry to modify.
374 * @param data The data to replace the old entry
375 * @return The data pointer for the old stored entry, or @c NULL
378 * This function modifies the data of @p key with @p data in @p
379 * hash. If no entry is found, @p data is added to @p hash with the
380 * key @p key. On success this function returns the old entry,
381 * otherwise it returns @c NULL. To check for errors, use
384 EAPI void *eina_hash_set(Eina_Hash *hash,
386 const void *data) EINA_ARG_NONNULL(1, 2, 3);
389 * @brief Change the key associated with a data without triggering the
392 * @param hash The given hash table.
393 * @param old_key The current key associated with the data
394 * @param new_key The new key to associate data with
395 * @return EINA_FALSE in any case but success, EINA_TRUE on success.
397 * This function allows for the move of data from one key to another,
398 * but does not call the Eina_Free_Cb associated with the hash table
399 * when destroying the old key.
401 EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
403 const void *new_key) EINA_ARG_NONNULL(1, 2, 3);
406 * Free the given hash table resources.
408 * @param hash The hash table to be freed.
410 * This function frees up all the memory allocated to storing @p hash,
411 * and call the free callback if it has been passed to the hash table
412 * at creation time. If no free callback has been passed, any entries
413 * in the table that the program has no more pointers for elsewhere
414 * may now be lost, so this should only be called if the program has
415 * already freed any allocated data in the hash table or has the
416 * pointers for data in the table stored elsewhere as well. If @p hash
417 * is @c NULL, the function returns immediately.
421 * extern Eina_Hash *hash;
423 * eina_hash_free(hash);
427 EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
430 * Free the given hash table buckets resources.
432 * @param hash The hash table whose buckets have to be freed.
434 * This function frees up all the memory allocated to storing the
435 * buckets of @p hash, and calls the free callback on all hash table
436 * buckets if it has been passed to the hash table at creation time,
437 * then frees the buckets. If no free callback has been passed, no
438 * buckets value will be freed. If @p hash is @c NULL, the function
439 * returns immediately.
441 EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
444 * @brief Returns the number of entries in the given hash table.
446 * @param hash The given hash table.
447 * @return The number of entries in the hash table.
449 * This function returns the number of entries in @p hash, or 0 on
450 * error. If @p hash is @c NULL, 0 is returned.
452 EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
455 * @brief Add an entry to the given hash table.
457 * @param hash The given hash table.
458 * @param key A unique key.
459 * @param key_length The length of the key.
460 * @param key_hash The hash that will always match key.
461 * @param data The data to associate with the string given by the key.
462 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
464 * This function adds @p key to @p hash. @p hash, @p key and @p data
465 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
466 * expected to be a unique string within the hash table. Otherwise,
467 * one cannot be sure which inserted data pointer will be accessed
468 * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do
469 * not forget to count '\\0' for string when setting the value of
470 * @p key_length. @p key_hash is expected to always match
471 * @p key. Otherwise, one cannot be sure to find it again with @ref
472 * eina_hash_find_by_hash. Key strings are case sensitive. If an error
473 * occurs, eina_error_get() should be used to determine if an
474 * allocation error occurred during this function. This function
475 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
477 EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash,
481 const void *data) EINA_ARG_NONNULL(1, 2, 5);
484 * @brief Add an entry to the given hash table and do not duplicate the string
487 * @param hash The given hash table. Can be @c NULL.
488 * @param key A unique key. Can be @c NULL.
489 * @param key_length Should be the length of @p key (don't forget to count
491 * @param key_hash The hash that will always match key.
492 * @param data Data to associate with the string given by @p key.
493 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
495 * This function adds @p key to @p hash. @p hash, @p key and @p data
496 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
497 * expected to be a unique string within the hash table. Otherwise,
498 * one cannot be sure which inserted data pointer will be accessed
499 * with @ref eina_hash_find, and removed with @ref eina_hash_del. This
500 * function does not make a copy of @p key so it must be a string
501 * constant or stored elsewhere (in the object being added). Do
502 * not forget to count '\\0' for string when setting the value of
503 * @p key_length. @p key_hash is expected to always match
504 * @p key. Otherwise, one cannot be sure to find it again with @ref
505 * eina_hash_find_by_hash. Key strings are case sensitive. If an error
506 * occurs, eina_error_get() should be used to determine if an
507 * allocation error occurred during this function. This function
508 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
510 EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
514 const void *data) EINA_ARG_NONNULL(1, 2, 5);
517 * @brief Remove the entry identified by a key and a key hash from the given
520 * @param hash The given hash table.
521 * @param key The key.
522 * @param key_length The length of the key.
523 * @param key_hash The hash that always match the key.
524 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
526 * This function removes the entry identified by @p key and
527 * @p key_hash from @p hash. If a free function was given to the
528 * callback on creation, it will be called for the data being
529 * deleted. Do not forget to count '\\0' for string when setting the
530 * value of @p key_length. If @p hash or @p key are @c NULL, the
531 * functions returns immediately #EINA_FALSE. This function returns
532 * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
534 * @note if you don't have the key_hash, use eina_hash_del_by_key() instead.
535 * @note if you don't have the key, use eina_hash_del_by_data() instead.
537 EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
540 int key_hash) EINA_ARG_NONNULL(1, 2);
543 * @brief Remove the entry identified by a key from the given hash table.
545 * This version will calculate key length and hash by using functions
546 * provided to hash creation function.
548 * @param hash The given hash table.
549 * @param key The key.
550 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
552 * This function removes the entry identified by @p key from @p
553 * hash. The key length and hash will be calculated automatically by
554 * using functiond provided to has creation function. If a free
555 * function was given to the callback on creation, it will be called
556 * for the data being deleted. If @p hash or @p key are @c NULL, the
557 * functions returns immediately #EINA_FALSE. This function returns
558 * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
560 * @note if you already have the key_hash, use eina_hash_del_by_key_hash()
562 * @note if you don't have the key, use eina_hash_del_by_data() instead.
564 EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
565 const void *key) EINA_ARG_NONNULL(1, 2);
568 * @brief Remove the entry identified by a data from the given hash table.
570 * This version is slow since there is no quick access to nodes based on data.
572 * @param hash The given hash table.
573 * @param data The data value to search and remove.
574 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
577 * This function removes the entry identified by @p data from @p
578 * hash. If a free function was given to the callback on creation, it
579 * will be called for the data being deleted. If @p hash or @p data
580 * are @c NULL, the functions returns immediately #EINA_FALSE. This
581 * function returns #EINA_FALSE if an error occurred, #EINA_TRUE
584 * @note if you already have the key, use eina_hash_del_by_key() or
585 * eina_hash_del_by_key_hash() instead.
587 EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
588 const void *data) EINA_ARG_NONNULL(1, 2);
591 * @brief Remove the entry identified by a key and a key hash or a
592 * data from the given hash table.
594 * If @p key is @c NULL, then @p data is used to find a match to
597 * @param hash The given hash table.
598 * @param key The key.
599 * @param key_length The length of the key.
600 * @param key_hash The hash that always match the key.
601 * @param data The data pointer to remove if the key is @c NULL.
602 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
604 * This function removes the entry identified by @p key and
605 * @p key_hash, or @p data, from @p hash. If a free function was given to
606 * the callback on creation, it will be called for the data being
607 * deleted. If @p hash is @c NULL, the functions returns immediately
608 * #EINA_FALSE. If @p key is @c NULL, then @p key_hash and @p key_hash
609 * are ignored and @p data is used to find a match to remove,
610 * otherwise @p key and @p key_hash are used and @p data is not
611 * required and can be @c NULL. Do not forget to count '\\0' for
612 * string when setting the value of @p key_length. This function
613 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
615 * @note if you know you already have the key, use eina_hash_del_by_key_hash(),
616 * if you know you don't have the key, use eina_hash_del_by_data()
619 EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
623 const void *data) EINA_ARG_NONNULL(1);
626 * @brief Retrieve a specific entry in the given hash table.
628 * @param hash The given hash table.
629 * @param key The key of the entry to find.
630 * @param key_length The length of the key.
631 * @param key_hash The hash that always match the key
632 * @return The data pointer for the stored entry on success, @c NULL
635 * This function retrieves the entry associated to @p key of length
636 * @p key_length in @p hash. @p key_hash is the hash that always match
637 * @p key. It is ignored if @p key is @c NULL. Do not forget to count
638 * '\\0' for string when setting the value of @p key_length. If
639 * @p hash is @c NULL, this function returns immediately @c NULL. This
640 * function returns the data pointer on success, @c NULL otherwise.
642 EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
645 int key_hash) EINA_ARG_NONNULL(1, 2);
648 * @brief Modify the entry pointer at the specified key and returns
651 * @param hash The given hash table.
652 * @param key The key of the entry to modify.
653 * @param key_length Should be the length of @p key (don't forget to count
655 * @param key_hash The hash that always match the key. Ignored if @p key is
657 * @param data The data to replace the old entry, if it exists.
658 * @return The data pointer for the old stored entry, or @c NULL if not
659 * found. If an existing entry is not found, nothing is added to the
662 EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
666 const void *data) EINA_ARG_NONNULL(1, 2, 5);
669 * @brief Returned a new iterator associated to hash keys.
671 * @param hash The hash.
672 * @return A new iterator.
674 * This function returns a newly allocated iterator associated to @p
675 * hash. If @p hash is not populated, this function still returns a
676 * valid iterator that will always return false on
677 * eina_iterator_next(), thus keeping API sane.
679 * If the memory can not be allocated, NULL is returned and
680 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
683 * @warning if the hash structure changes then the iterator becomes
684 * invalid! That is, if you add or remove items this iterator
685 * behavior is undefined and your program may crash!
687 EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
690 * @brief Returned a new iterator associated to hash data.
692 * @param hash The hash.
693 * @return A new iterator.
695 * This function returns a newly allocated iterator associated to
696 * @p hash. If @p hash is not populated, this function still returns a
697 * valid iterator that will always return false on
698 * eina_iterator_next(), thus keeping API sane.
700 * If the memory can not be allocated, @c NULL is returned and
701 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
704 * @warning if the hash structure changes then the iterator becomes
705 * invalid. That is, if you add or remove items this iterator behavior
706 * is undefined and your program may crash.
708 EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
711 * @brief Returned a new iterator associated to hash keys and data.
713 * @param hash The hash.
714 * @return A new iterator.
716 * This function returns a newly allocated iterator associated to @p
717 * hash. If @p hash is not populated, this function still returns a
718 * valid iterator that will always return false on
719 * eina_iterator_next(), thus keeping API sane.
721 * If the memory can not be allocated, NULL is returned and
722 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
725 * @note iterator data will provide values as Eina_Hash_Tuple that should not
728 * @warning if the hash structure changes then the iterator becomes
729 * invalid! That is, if you add or remove items this iterator
730 * behavior is undefined and your program may crash!
732 EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
735 * @brief Call a function on every member stored in the hash table
737 * @param hash The hash table whose members will be walked
738 * @param func The function to call on each parameter
739 * @param fdata The data pointer to pass to the function being called
741 * This function goes through every entry in the hash table @p hash and calls
742 * the function @p func on each member. The function should @b not modify the
743 * hash table contents if it returns 1. @b If the hash table contents are
744 * modified by this function or the function wishes to stop processing it must
745 * return 0, otherwise return 1 to keep processing.
749 * extern Eina_Hash *hash;
751 * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key,
752 * void *data, void *fdata)
754 * printf("Func data: %s, Hash entry: %s / %p\n",
755 * fdata, (const char *)key, data);
759 * int main(int argc, char **argv)
761 * char *hash_fn_data;
763 * hash_fn_data = strdup("Hello World");
764 * eina_hash_foreach(hash, hash_fn, hash_fn_data);
765 * free(hash_fn_data);
769 EAPI void eina_hash_foreach(const Eina_Hash *hash,
770 Eina_Hash_Foreach cb,
771 const void *fdata) EINA_ARG_NONNULL(1, 2);
772 /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */
773 EAPI int eina_hash_superfast(const char *key,
774 int len) EINA_ARG_NONNULL(1);
775 /* Hash function first reported by dan bernstein many years ago in comp.lang.c */
776 static inline int eina_hash_djb2(const char *key,
777 int len) EINA_ARG_NONNULL(1);
778 static inline int eina_hash_djb2_len(const char *key,
779 int *plen) EINA_ARG_NONNULL(1, 2);
780 /* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */
781 static inline int eina_hash_int32(const unsigned int *pkey,
782 int len) EINA_ARG_NONNULL(1);
783 static inline int eina_hash_int64(const unsigned long int *pkey,
784 int len) EINA_ARG_NONNULL(1);
786 #include "eina_inline_hash.x"
804 #endif /*EINA_HASH_H_*/