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 * @page hash_01_example_page Eina_Hash in action
28 * @dontinclude eina_hash_01.c
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:
34 * @until // _start_entries
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:
43 * We also need a callback to iterate over the elements of the list later, so
44 * we are defining it now:
49 * Now let's create our @ref Eina_Hash using @ref
50 * eina_hash_string_superfast_new :
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).
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:
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:
77 * @until printf("\n");
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 .
82 * @skip List of phones
83 * @until eina_iterator_free(it);
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:
88 * @skipline eina_hash_move
90 * We can remove all the elements from the table without free the table itself:
92 * @skip Empty the phone book
93 * @until eina_hash_population
95 * Or free the the entire table with its content:
97 * @skipline eina_hash_free
100 * The full code for this example can be seen here: @ref eina_hash_01_c
104 * @page eina_hash_01_c Hash table in action
106 * @include eina_hash_01.c
107 * @example eina_hash_01.c
111 * @page hash_02_example_page Different types of tables
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
116 * @include eina_hash_02.c
117 * @example eina_hash_02.c
121 * @addtogroup Eina_Hash_Group Hash Table
123 * @brief Hash table management. Useful for mapping keys to values.
125 * The hash table is useful for when one wants to implement a table that maps
126 * keys (usually strings) to data, and have relatively fast access time. The
127 * performance is proportional to the load factor of the table (number of
128 * elements / number of buckets). See @ref hashtable_algo for implementation
131 * Different implementations exists depending on what kind of key will be used
132 * to access the data: strings, integers, pointers, stringshared or your own.
134 * Eina hash tables can copy the keys when using eina_hash_add() or not when
135 * using eina_hash_direct_add().
137 * @section hashtable_algo Algorithm
139 * The Eina_Hash is implemented using an array of N "buckets", where each
140 * bucket is a pointer to a structure that is the head of a <a
141 * href="http://en.wikipedia.org/wiki/Red-black_tree">red-black tree</a>. The
142 * array can then be indexed by the [hash_of_element mod N]. The
143 * hash_of_element is calculated using the hashing function, passed as
144 * parameter to the @ref eina_hash_new function. N is the number of buckets
145 * (array positions), and is calculated based on the buckets_power_size
146 * (argument of @ref eina_hash_new too). The following picture ilustrates the
149 * @image html 01_hash-table.png
150 * @image latex 01_hash-table.eps
152 * Adding an element to the hash table is made of:
153 * @li calculating the hash for that key (using the specified hash function);
154 * @li calculate the array position [hash mod N];
155 * @li add the element to the rbtree on that position.
157 * The two first steps have constant time, proportional to the hash function
158 * being used. Adding the key to the rbtree will be proportional on the number
159 * of keys on that bucket.
161 * The average cost of lookup depends on the number of keys per
162 * bucket (load factor) of the table, if the distribution of keys is
163 * sufficiently uniform.
165 * @section hashtable_perf Performance
167 * As said before, the performance depends on the load factor. So trying to keep
168 * it as small as possible will improve the hash table performance. But
169 * increasing the buckets_power_size will also increase the memory consumption.
170 * The default hash table creation functions already have a good number of
171 * buckets, enough for most cases. Particularly for strings, if just a few keys
172 * (less than 30) will be added to the hash table, @ref
173 * eina_hash_string_small_new should be used. If just stringshared keys are
174 * being added, use @ref eina_hash_stringshared_new. If a lot of keys will be
175 * added to the hash table (e.g. more than 1000), then it's better to increase
176 * the buckets_power_size. See @ref eina_hash_new for more details.
178 * When adding a new key to a hash table, use @ref eina_hash_add or @ref
179 * eina_hash_direct_add (the latter if this key is already stored elsewhere). If
180 * the key may be already inside the hash table, instead of checking with
181 * @ref eina_hash_find and then doing @ref eina_hash_add, one can use just @ref
182 * eina_hash_set (this will change the data pointed by this key if it was
183 * already present in the table).
185 * @section hashtable_tutorial Tutorial
187 * These examples show many Eina_Hash functions in action:
188 * @li @ref hash_01_example_page
189 * @li @ref hash_02_example_page
195 * @addtogroup Eina_Data_Types_Group Data Types
201 * @addtogroup Eina_Containers_Group Containers
207 * @defgroup Eina_Hash_Group Hash Table
214 * Type for a generic hash table.
216 typedef struct _Eina_Hash Eina_Hash;
218 typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple;
220 struct _Eina_Hash_Tuple
222 const void *key; /**< The key */
223 void *data; /**< The data associated to the key */
224 unsigned int key_length; /**< The length of the key */
227 typedef unsigned int (*Eina_Key_Length)(const void *key);
228 #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
229 typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
230 #define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function)
231 typedef int (*Eina_Key_Hash)(const void *key, int key_length);
232 #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function)
233 typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata);
237 * @brief Create a new hash table.
239 * @param key_length_cb The function called when getting the size of the key.
240 * @param key_cmp_cb The function called when comparing the keys.
241 * @param key_hash_cb The function called when getting the values.
242 * @param data_free_cb The function called on each value when the hash
243 * table is freed. @c NULL can be passed as callback.
244 * @param buckets_power_size The size of the buckets.
245 * @return The new hash table.
247 * This function creates a new hash table using user-defined callbacks
248 * to manage the hash table. On failure, @c NULL is returned and
249 * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb
250 * are @c NULL, @c NULL is returned. If @p buckets_power_size is
251 * smaller or equal than 2, or if it is greater or equal than 17,
252 * @c NULL is returned.
254 * Pre-defined functions are available to create a hash table. See
255 * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(),
256 * eina_hash_string_small_new(), eina_hash_int32_new(),
257 * eina_hash_int64_new(), eina_hash_pointer_new() and
258 * eina_hash_stringshared_new().
260 EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
261 Eina_Key_Cmp key_cmp_cb,
262 Eina_Key_Hash key_hash_cb,
263 Eina_Free_Cb data_free_cb,
264 int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
267 * @brief Redefine the callback that clean the data of a hash
269 * @param hash The given hash table
270 * @param data_free_cb The function called on each value when the hash
271 * table is freed. @c NULL can be passed as callback.
273 EAPI void eina_hash_free_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1);
276 * @brief Create a new hash table using the djb2 algorithm.
278 * @param data_free_cb The function called on each value when the hash table
279 * is freed. @c NULL can be passed as callback.
280 * @return The new hash table.
282 * This function creates a new hash table using the djb2 algorithm for
283 * table management and strcmp() to compare the keys. Values can then
284 * be looked up with pointers other than the original key pointer that
285 * was used to add values. On failure, this function returns @c NULL.
287 EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
290 * @brief Create a new hash table for use with strings.
292 * @param data_free_cb The function called on each value when the hash table
293 * is freed. @c NULL can be passed as callback.
294 * @return The new hash table.
296 * This function creates a new hash table using the superfast algorithm
297 * for table management and strcmp() to compare the keys. Values can
298 * then be looked up with pointers other than the original key pointer
299 * that was used to add values. On failure, this function returns
302 EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
305 * @brief Create a new hash table for use with strings with small bucket size.
307 * @param data_free_cb The function called on each value when the hash table
308 * is freed. @c NULL can be passed as callback.
309 * @return The new hash table.
311 * This function creates a new hash table using the superfast algorithm
312 * for table management and strcmp() to compare the keys, but with a
313 * smaller bucket size (compared to eina_hash_string_superfast_new())
314 * which will minimize the memory used by the returned hash
315 * table. Values can then be looked up with pointers other than the
316 * original key pointer that was used to add values. On failure, this
317 * function returns @c NULL.
319 EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
322 * @brief Create a new hash table for use with 32bit integers.
324 * @param data_free_cb The function called on each value when the hash table
325 * is freed. @c NULL can be passed as callback.
326 * @return The new hash table.
328 * This function creates a new hash table where keys are 32bit integers.
329 * When adding or looking up in the hash table, pointers to 32bit integers
330 * must be passed. They can be addresses on the stack if you let the
331 * eina_hash copy the key. Values can then
332 * be looked up with pointers other than the original key pointer that was
333 * used to add values. This method is not suitable to match string keys as
334 * it would only match the first character.
335 * On failure, this function returns @c NULL.
337 EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
340 * @brief Create a new hash table for use with 64bit integers.
342 * @param data_free_cb The function called on each value when the hash table
343 * is freed. @c NULL can be passed as callback.
344 * @return The new hash table.
346 * This function creates a new hash table where keys are 64bit integers.
347 * When adding or looking up in the hash table, pointers to 64bit integers
348 * must be passed. They can be addresses on the stack. Values can then
349 * be looked up with pointers other than the original key pointer that was
350 * used to add values. This method is not suitable to match string keys as
351 * it would only match the first character.
352 * On failure, this function returns @c NULL.
354 EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
357 * @brief Create a new hash table for use with pointers.
359 * @param data_free_cb The function called on each value when the hash table
360 * is freed. @c NULL can be passed as callback.
361 * @return The new hash table.
363 * This function creates a new hash table using the int64/int32 algorithm for
364 * table management and dereferenced pointers to compare the
365 * keys. Values can then be looked up with pointers other than the
366 * original key pointer that was used to add values. This method may
367 * appear to be able to match string keys, actually it only matches
368 * the first character. On failure, this function returns @c NULL.
370 EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
373 * @brief Create a new hash table optimized for stringshared values.
375 * @param data_free_cb The function called on each value when the hash table
376 * is freed. @c NULL can be passed as callback.
377 * @return The new hash table.
379 * This function creates a new hash table optimized for stringshared
380 * values. Values CAN NOT be looked up with pointers not
381 * equal to the original key pointer that was used to add a value. On failure,
382 * this function returns @c NULL.
384 * Excerpt of code that will NOT work with this type of hash:
387 * extern Eina_Hash *hash;
388 * extern const char *value;
389 * const char *a = eina_stringshare_add("key");
391 * eina_hash_add(hash, a, value);
392 * eina_hash_find(hash, "key")
395 EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
398 * @brief Add an entry to the given hash table.
400 * @param hash The given hash table.
401 * @param key A unique key.
402 * @param data Data to associate with the string given by @p key.
403 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
405 * This function adds @p key to @p hash. @p hash, @p key and @p data
406 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
407 * expected to be unique within the hash table. Key uniqueness varies
408 * depending on the type of @p hash: a stringshared @ref Eina_Hash
409 * need only have unique pointers for keys, but the strings in the
410 * pointers may be identical. All other hash types require the strings
411 * themselves to be unique. Failure to use sufficient uniqueness will
412 * result in unexpected results when inserting data pointers accessed
413 * with eina_hash_find(), and removed with eina_hash_del(). Key
414 * strings are case sensitive. If an error occurs, eina_error_get()
415 * should be used to determine if an allocation error occurred during
416 * this function. This function returns #EINA_FALSE if an error
417 * occurred, #EINA_TRUE otherwise.
419 EAPI Eina_Bool eina_hash_add(Eina_Hash *hash,
421 const void *data) EINA_ARG_NONNULL(1, 2, 3);
424 * @brief Add an entry to the given hash table without duplicating the string
427 * @param hash The given hash table. Can be @c NULL.
428 * @param key A unique key. Can be @c NULL.
429 * @param data Data to associate with the string given by @p key.
430 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
432 * This function adds @p key to @p hash. @p hash, @p key and @p data
433 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
434 * expected to be unique within the hash table. Key uniqueness varies
435 * depending on the type of @p hash: a stringshared @ref Eina_Hash
436 * need only have unique pointers for keys, but the strings in the
437 * pointers may be identical. All other hash types require the strings
438 * themselves to be unique. Failure to use sufficient uniqueness will
439 * result in unexpected results when inserting data pointers accessed
440 * with eina_hash_find(), and removed with eina_hash_del(). This
441 * function does not make a copy of @p key, so it must be a string
442 * constant or stored elsewhere ( in the object being added). Key
443 * strings are case sensitive. If an error occurs, eina_error_get()
444 * should be used to determine if an allocation error occurred during
445 * this function. This function returns #EINA_FALSE if an error
446 * occurred, #EINA_TRUE otherwise.
448 EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash,
450 const void *data) EINA_ARG_NONNULL(1, 2, 3);
453 * @brief Remove the entry identified by a key or a data from the given
456 * @param hash The given hash table.
457 * @param key The key.
458 * @param data The data pointer to remove if the key is @c NULL.
459 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
461 * This function removes the entry identified by @p key or @p data
462 * from @p hash. If a free function was given to the
463 * callback on creation, it will be called for the data being
464 * deleted. If @p hash is @c NULL, the functions returns immediately
465 * #EINA_FALSE. If @p key is @c NULL, then @p data is used to find the a
466 * match to remove, otherwise @p key is used and @p data is not
467 * required and can be @c NULL. This function returns #EINA_FALSE if
468 * an error occurred, #EINA_TRUE otherwise.
470 * @note if you know you already have the key, use
471 * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
472 * know you don't have the key, use eina_hash_del_by_data()
475 EAPI Eina_Bool eina_hash_del(Eina_Hash *hash,
477 const void *data) EINA_ARG_NONNULL(1);
480 * @brief Retrieve a specific entry in the given hash table.
482 * @param hash The given hash table.
483 * @param key The key of the entry to find.
484 * @return The data pointer for the stored entry on success, @c NULL
487 * This function retrieves the entry associated to @p key in
488 * @p hash. If @p hash is @c NULL, this function returns immediately
489 * @c NULL. This function returns the data pointer on success, @c NULL
492 EAPI void *eina_hash_find(const Eina_Hash *hash,
493 const void *key) EINA_ARG_NONNULL(1, 2);
496 * @brief Modify the entry pointer at the specified key and return the old
498 * @param hash The given hash table.
499 * @param key The key of the entry to modify.
500 * @param data The data to replace the old entry.
501 * @return The data pointer for the old stored entry on success, or
504 * This function modifies the data of @p key with @p data in @p
505 * hash. If no entry is found, nothing is added to @p hash. On success
506 * this function returns the old entry, otherwise it returns @c NULL.
508 EAPI void *eina_hash_modify(Eina_Hash *hash,
510 const void *data) EINA_ARG_NONNULL(1, 2, 3);
513 * @brief Modify the entry pointer at the specified key and return the
514 * old entry or add the entry if not found.
516 * @param hash The given hash table.
517 * @param key The key of the entry to modify.
518 * @param data The data to replace the old entry
519 * @return The data pointer for the old stored entry, or @c NULL
522 * This function modifies the data of @p key with @p data in @p
523 * hash. If no entry is found, @p data is added to @p hash with the
524 * key @p key. On success this function returns the old entry,
525 * otherwise it returns @c NULL. To check for errors, use
528 EAPI void *eina_hash_set(Eina_Hash *hash,
530 const void *data) EINA_ARG_NONNULL(1, 2);
533 * @brief Change the key associated with a data without triggering the
536 * @param hash The given hash table.
537 * @param old_key The current key associated with the data
538 * @param new_key The new key to associate data with
539 * @return EINA_FALSE in any case but success, EINA_TRUE on success.
541 * This function allows for the move of data from one key to another,
542 * but does not call the Eina_Free_Cb associated with the hash table
543 * when destroying the old key.
545 EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
547 const void *new_key) EINA_ARG_NONNULL(1, 2, 3);
550 * Free the given hash table resources.
552 * @param hash The hash table to be freed.
554 * This function frees up all the memory allocated to storing @p hash,
555 * and call the free callback if it has been passed to the hash table
556 * at creation time. If no free callback has been passed, any entries
557 * in the table that the program has no more pointers for elsewhere
558 * may now be lost, so this should only be called if the program has
559 * already freed any allocated data in the hash table or has the
560 * pointers for data in the table stored elsewhere as well. If @p hash
561 * is @c NULL, the function returns immediately.
565 * extern Eina_Hash *hash;
567 * eina_hash_free(hash);
571 EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
574 * Free the given hash table buckets resources.
576 * @param hash The hash table whose buckets have to be freed.
578 * This function frees up all the memory allocated to storing the
579 * buckets of @p hash, and calls the free callback on all hash table
580 * buckets if it has been passed to the hash table at creation time,
581 * then frees the buckets. If no free callback has been passed, no
582 * buckets value will be freed. If @p hash is @c NULL, the function
583 * returns immediately.
585 EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
588 * @brief Returns the number of entries in the given hash table.
590 * @param hash The given hash table.
591 * @return The number of entries in the hash table.
593 * This function returns the number of entries in @p hash, or 0 on
594 * error. If @p hash is @c NULL, 0 is returned.
596 EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
599 * @brief Add an entry to the given hash table.
601 * @param hash The given hash table.
602 * @param key A unique key.
603 * @param key_length The length of the key.
604 * @param key_hash The hash that will always match key.
605 * @param data The data to associate with the string given by the key.
606 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
608 * This function adds @p key to @p hash. @p hash, @p key and @p data
609 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
610 * expected to be a unique string within the hash table. Otherwise,
611 * one cannot be sure which inserted data pointer will be accessed
612 * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do
613 * not forget to count '\\0' for string when setting the value of
614 * @p key_length. @p key_hash is expected to always match
615 * @p key. Otherwise, one cannot be sure to find it again with @ref
616 * eina_hash_find_by_hash. Key strings are case sensitive. If an error
617 * occurs, eina_error_get() should be used to determine if an
618 * allocation error occurred during this function. This function
619 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
621 EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash,
625 const void *data) EINA_ARG_NONNULL(1, 2, 5);
628 * @brief Add an entry to the given hash table and do not duplicate the string
631 * @param hash The given hash table. Can be @c NULL.
632 * @param key A unique key. Can be @c NULL.
633 * @param key_length Should be the length of @p key (don't forget to count
635 * @param key_hash The hash that will always match key.
636 * @param data Data to associate with the string given by @p key.
637 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
639 * This function adds @p key to @p hash. @p hash, @p key and @p data
640 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
641 * expected to be a unique string within the hash table. Otherwise,
642 * one cannot be sure which inserted data pointer will be accessed
643 * with @ref eina_hash_find, and removed with @ref eina_hash_del. This
644 * function does not make a copy of @p key so it must be a string
645 * constant or stored elsewhere (in the object being added). Do
646 * not forget to count '\\0' for string when setting the value of
647 * @p key_length. @p key_hash is expected to always match
648 * @p key. Otherwise, one cannot be sure to find it again with @ref
649 * eina_hash_find_by_hash. Key strings are case sensitive. If an error
650 * occurs, eina_error_get() should be used to determine if an
651 * allocation error occurred during this function. This function
652 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
654 EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
658 const void *data) EINA_ARG_NONNULL(1, 2, 5);
661 * @brief Remove the entry identified by a key and a key hash from the given
664 * @param hash The given hash table.
665 * @param key The key.
666 * @param key_length The length of the key.
667 * @param key_hash The hash that always match the key.
668 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
670 * This function removes the entry identified by @p key and
671 * @p key_hash from @p hash. If a free function was given to the
672 * callback on creation, it will be called for the data being
673 * deleted. Do not forget to count '\\0' for string when setting the
674 * value of @p key_length. If @p hash or @p key are @c NULL, the
675 * functions returns immediately #EINA_FALSE. This function returns
676 * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
678 * @note if you don't have the key_hash, use eina_hash_del_by_key() instead.
679 * @note if you don't have the key, use eina_hash_del_by_data() instead.
681 EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
684 int key_hash) EINA_ARG_NONNULL(1, 2);
687 * @brief Remove the entry identified by a key from the given hash table.
689 * This version will calculate key length and hash by using functions
690 * provided to hash creation function.
692 * @param hash The given hash table.
693 * @param key The key.
694 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
696 * This function removes the entry identified by @p key from @p
697 * hash. The key length and hash will be calculated automatically by
698 * using functiond provided to has creation function. If a free
699 * function was given to the callback on creation, it will be called
700 * for the data being deleted. If @p hash or @p key are @c NULL, the
701 * functions returns immediately #EINA_FALSE. This function returns
702 * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
704 * @note if you already have the key_hash, use eina_hash_del_by_key_hash()
706 * @note if you don't have the key, use eina_hash_del_by_data() instead.
708 EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
709 const void *key) EINA_ARG_NONNULL(1, 2);
712 * @brief Remove the entry identified by a data from the given hash table.
714 * This version is slow since there is no quick access to nodes based on data.
716 * @param hash The given hash table.
717 * @param data The data value to search and remove.
718 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
721 * This function removes the entry identified by @p data from @p
722 * hash. If a free function was given to the callback on creation, it
723 * will be called for the data being deleted. If @p hash or @p data
724 * are @c NULL, the functions returns immediately #EINA_FALSE. This
725 * function returns #EINA_FALSE if an error occurred, #EINA_TRUE
728 * @note if you already have the key, use eina_hash_del_by_key() or
729 * eina_hash_del_by_key_hash() instead.
731 EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
732 const void *data) EINA_ARG_NONNULL(1, 2);
735 * @brief Remove the entry identified by a key and a key hash or a
736 * data from the given hash table.
738 * If @p key is @c NULL, then @p data is used to find a match to
741 * @param hash The given hash table.
742 * @param key The key.
743 * @param key_length The length of the key.
744 * @param key_hash The hash that always match the key.
745 * @param data The data pointer to remove if the key is @c NULL.
746 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
748 * This function removes the entry identified by @p key and
749 * @p key_hash, or @p data, from @p hash. If a free function was given to
750 * the callback on creation, it will be called for the data being
751 * deleted. If @p hash is @c NULL, the functions returns immediately
752 * #EINA_FALSE. If @p key is @c NULL, then @p key_hash and @p key_hash
753 * are ignored and @p data is used to find a match to remove,
754 * otherwise @p key and @p key_hash are used and @p data is not
755 * required and can be @c NULL. Do not forget to count '\\0' for
756 * string when setting the value of @p key_length. This function
757 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
759 * @note if you know you already have the key, use eina_hash_del_by_key_hash(),
760 * if you know you don't have the key, use eina_hash_del_by_data()
763 EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
767 const void *data) EINA_ARG_NONNULL(1);
770 * @brief Retrieve a specific entry in the given hash table.
772 * @param hash The given hash table.
773 * @param key The key of the entry to find.
774 * @param key_length The length of the key.
775 * @param key_hash The hash that always match the key
776 * @return The data pointer for the stored entry on success, @c NULL
779 * This function retrieves the entry associated to @p key of length
780 * @p key_length in @p hash. @p key_hash is the hash that always match
781 * @p key. It is ignored if @p key is @c NULL. Do not forget to count
782 * '\\0' for string when setting the value of @p key_length. If
783 * @p hash is @c NULL, this function returns immediately @c NULL. This
784 * function returns the data pointer on success, @c NULL otherwise.
786 EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
789 int key_hash) EINA_ARG_NONNULL(1, 2);
792 * @brief Modify the entry pointer at the specified key and returns
795 * @param hash The given hash table.
796 * @param key The key of the entry to modify.
797 * @param key_length Should be the length of @p key (don't forget to count
799 * @param key_hash The hash that always match the key. Ignored if @p key is
801 * @param data The data to replace the old entry, if it exists.
802 * @return The data pointer for the old stored entry, or @c NULL if not
803 * found. If an existing entry is not found, nothing is added to the
806 EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
810 const void *data) EINA_ARG_NONNULL(1, 2, 5);
813 * @brief Returned a new iterator associated to hash keys.
815 * @param hash The hash.
816 * @return A new iterator.
818 * This function returns a newly allocated iterator associated to @p
819 * hash. If @p hash is not populated, this function still returns a
820 * valid iterator that will always return false on
821 * eina_iterator_next(), thus keeping API sane.
823 * If the memory can not be allocated, NULL is returned and
824 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
827 * @warning if the hash structure changes then the iterator becomes
828 * invalid! That is, if you add or remove items this iterator
829 * behavior is undefined and your program may crash!
831 EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
834 * @brief Returned a new iterator associated to hash data.
836 * @param hash The hash.
837 * @return A new iterator.
839 * This function returns a newly allocated iterator associated to
840 * @p hash. If @p hash is not populated, this function still returns a
841 * valid iterator that will always return false on
842 * eina_iterator_next(), thus keeping API sane.
844 * If the memory can not be allocated, @c NULL is returned and
845 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
848 * @warning if the hash structure changes then the iterator becomes
849 * invalid. That is, if you add or remove items this iterator behavior
850 * is undefined and your program may crash.
852 EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
855 * @brief Returned a new iterator associated to hash keys and data.
857 * @param hash The hash.
858 * @return A new iterator.
860 * This function returns a newly allocated iterator associated to @p
861 * hash. If @p hash is not populated, this function still returns a
862 * valid iterator that will always return false on
863 * eina_iterator_next(), thus keeping API sane.
865 * If the memory can not be allocated, NULL is returned and
866 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
869 * @note iterator data will provide values as Eina_Hash_Tuple that should not
872 * @warning if the hash structure changes then the iterator becomes
873 * invalid! That is, if you add or remove items this iterator
874 * behavior is undefined and your program may crash!
876 EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
879 * @brief Call a function on every member stored in the hash table
881 * @param hash The hash table whose members will be walked
882 * @param func The function to call on each parameter
883 * @param fdata The data pointer to pass to the function being called
885 * This function goes through every entry in the hash table @p hash and calls
886 * the function @p func on each member. The function should @b not modify the
887 * hash table contents if it returns 1. @b If the hash table contents are
888 * modified by this function or the function wishes to stop processing it must
889 * return 0, otherwise return 1 to keep processing.
893 * extern Eina_Hash *hash;
895 * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key,
896 * void *data, void *fdata)
898 * printf("Func data: %s, Hash entry: %s / %p\n",
899 * fdata, (const char *)key, data);
903 * int main(int argc, char **argv)
905 * char *hash_fn_data;
907 * hash_fn_data = strdup("Hello World");
908 * eina_hash_foreach(hash, hash_fn, hash_fn_data);
909 * free(hash_fn_data);
913 EAPI void eina_hash_foreach(const Eina_Hash *hash,
914 Eina_Hash_Foreach cb,
915 const void *fdata) EINA_ARG_NONNULL(1, 2);
916 /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */
917 EAPI int eina_hash_superfast(const char *key,
918 int len) EINA_ARG_NONNULL(1);
919 /* Hash function first reported by dan bernstein many years ago in comp.lang.c */
920 static inline int eina_hash_djb2(const char *key,
921 int len) EINA_ARG_NONNULL(1);
922 static inline int eina_hash_djb2_len(const char *key,
923 int *plen) EINA_ARG_NONNULL(1, 2);
924 /* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */
925 static inline int eina_hash_int32(const unsigned int *pkey,
926 int len) EINA_ARG_NONNULL(1);
927 static inline int eina_hash_int64(const unsigned long int *pkey,
928 int len) EINA_ARG_NONNULL(1);
930 #include "eina_inline_hash.x"
948 #endif /*EINA_HASH_H_*/