diff options
Diffstat (limited to 'src/lib/eina/eina_hash.h')
| -rw-r--r-- | src/lib/eina/eina_hash.h | 535 |
1 files changed, 251 insertions, 284 deletions
diff --git a/src/lib/eina/eina_hash.h b/src/lib/eina/eina_hash.h index 40b0c227f6..6efdfce34b 100644 --- a/src/lib/eina/eina_hash.h +++ b/src/lib/eina/eina_hash.h @@ -158,19 +158,19 @@ /** * @addtogroup Eina_Hash_Group Hash Table * - * @brief Hash table management. Useful for mapping keys to values. + * @brief Hash table management. Maps keys to values. * - * The hash table is useful for when one wants to implement a table that maps - * keys (usually strings) to data, and have relatively fast access time. The - * performance is proportional to the load factor of the table (number of - * elements / number of buckets). See @ref hashtable_algo for implementation - * details. + * The hash table associates keys (e.g. strings) to data, with + * relatively fast access time. The performance is proportional to the + * load factor of the table (number of elements / number of + * buckets). See @ref hashtable_algo for implementation details. * - * Different implementations exists depending on what kind of key will be used - * to access the data: strings, integers, pointers, stringshared or your own. + * There are optimized implementations for some common key types, such + * as strings, integers, pointers, and stringshared; custom optimizations + * are also permitted. * - * Eina hash tables can copy the keys when using eina_hash_add() or not when - * using eina_hash_direct_add(). + * The hash table keys can be either copied or non-copied, using + * eina_hash_add() or eina_hash_direct_add(), respectively. * * @section hashtable_algo Algorithm * @@ -178,7 +178,7 @@ * bucket is a pointer to a structure that is the head of a <a * href="http://en.wikipedia.org/wiki/Red-black_tree">red-black tree</a>. The * array can then be indexed by the [hash_of_element mod N]. The - * hash_of_element is calculated using the hashing function, passed as + * hash_of_element is calculated using the hashing function, passed as a * parameter to the @ref eina_hash_new function. N is the number of buckets * (array positions), and is calculated based on the buckets_power_size * (argument of @ref eina_hash_new too). The following picture illustrates the @@ -189,29 +189,28 @@ * @endhtmlonly * @image latex 01_hash-table.eps * - * Adding an element to the hash table is made of: - * @li calculating the hash for that key (using the specified hash function); + * Adding an element to the hash table involves the following steps: + * @li calculate the hash for that key (using the specified hash function); * @li calculate the array position [hash mod N]; * @li add the element to the rbtree on that position. * - * The two first steps have constant time, proportional to the hash function - * being used. Adding the key to the rbtree will be proportional on the number - * of keys on that bucket. + * The first two steps have constant time, proportional to the hash function + * being used. Adding the key to the rbtree will be proportional to the number + * of keys in that bucket. * - * The average cost of lookup depends on the number of keys per - * bucket (load factor) of the table, if the distribution of keys is + * The average lookup cost depends on the number of keys per bucket + * (load factor) of the table, assuming the distribution of keys is * sufficiently uniform. * * @section hashtable_perf Performance * - * As said before, the performance depends on the load factor. So trying to keep - * the load factor as small as possible will improve the hash table performance. But + * Keeping the load factor small will improve the hash table performance. But * increasing the buckets_power_size will also increase the memory consumption. - * The default hash table creation functions already have a good number of - * buckets, enough for most cases. Particularly for strings, if just a few keys + * The default hash table creation functions provides enough + * buckets for most cases. If just a few string keys * (less than 30) will be added to the hash table, @ref - * eina_hash_string_small_new should be used, since it will reduce the memory - * consumption for the buckets, and you still won't have many collisions. + * eina_hash_string_small_new should be used, since it reduces the memory + * consumption for the buckets without causing too many collisions. * However, @ref eina_hash_string_small_new still uses the same hash calculation * function that @ref eina_hash_string_superfast_new, which is more complex than * @ref eina_hash_string_djb2_new. The latter has a faster hash computation @@ -240,8 +239,8 @@ * * When adding a new key to a hash table, use @ref eina_hash_add or @ref * eina_hash_direct_add (the latter if this key is already stored elsewhere). If - * the key may be already inside the hash table, instead of checking with - * @ref eina_hash_find and then doing @ref eina_hash_add, one can use just @ref + * the key may be already inside the hash table, rather than checking with + * @ref eina_hash_find followed by @ref eina_hash_add, one can use just @ref * eina_hash_set (this will change the data pointed by this key if it was * already present in the table). * @@ -352,20 +351,20 @@ typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key * @param key_cmp_cb The function called when comparing the keys. * @param key_hash_cb The function called when getting the values. * @param data_free_cb The function called on each value when the hash table is - * freed, or when an item is deleted from it. @c NULL can be passed as + * freed, or when an item is deleted from it. @c NULL can be passed as a * callback. * @param buckets_power_size The size of the buckets. - * @return The new hash table. + * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table using user-defined callbacks - * to manage the hash table. On failure, @c NULL is returned. + * to manage the hash table. * If @p key_cmp_cb or @p key_hash_cb * are @c NULL, @c NULL is returned. If @p buckets_power_size is * smaller or equal than 2, or if it is greater or equal than 17, * @c NULL is returned. * * The number of buckets created will be 2 ^ @p buckets_power_size. This means - * that if @p buckets_power_size is 5, there will be created 32 buckets. for a + * that if @p buckets_power_size is 5, there will be created 32 buckets, whereas for a * @p buckets_power_size of 8, there will be 256 buckets. * * Pre-defined functions are available to create a hash table. See @@ -381,14 +380,14 @@ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb, int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3); /** - * @brief Redefines the callback that cleans the data of a hash. + * @brief Sets the data cleanup callback for a hash. * - * @param hash The given hash table + * @param hash The given hash table. * @param data_free_cb The function called on each value when the hash * table is freed, or when an item is deleted from it. @c NULL can be passed as * callback to remove an existing callback. * - * The argument received by @p data_free_cb will be that data of the item being + * The argument received by @p data_free_cb will be the data of the item being * removed. * * @since 1.1 @@ -402,12 +401,12 @@ EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA * @param data_free_cb The function called on each value when the hash table * is freed, or when an item is deleted from it. @c NULL can be passed as * callback. - * @return The new hash table. + * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table using the djb2 algorithm for * table management and strcmp() to compare the keys. Values can then * be looked up with pointers other than the original key pointer that - * was used to add values. On failure, this function returns @c NULL. + * was used to add values. */ EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); @@ -417,16 +416,16 @@ EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); * @param data_free_cb The function called on each value when the hash table * is freed, or when an item is deleted from it. @c NULL can be passed as * callback. - * @return The new hash table. + * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table using the superfast algorithm * for table management and strcmp() to compare the keys. Values can * then be looked up with pointers other than the original key pointer - * that was used to add values. On failure, this function returns - * @c NULL. + * that was used to add values. * - * NOTE: don't use this kind of hash when their is a possibility to remotely - * request and push data in it. This hash is subject to denial of service. + * @warning Don't use this kind of hash when there is a possibility to + * remotely request and push data in it. This hash is subject to denial + * of service. */ EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); @@ -436,15 +435,14 @@ EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); * @param data_free_cb The function called on each value when the hash table * is freed, or when an item is deleted from it. @c NULL can be passed as * callback. - * @return The new hash table. + * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table using the superfast algorithm * for table management and strcmp() to compare the keys, but with a * smaller bucket size (compared to eina_hash_string_superfast_new()) * which will minimize the memory used by the returned hash * table. Values can then be looked up with pointers other than the - * original key pointer that was used to add values. On failure, this - * function returns @c NULL. + * original key pointer that was used to add values. */ EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); @@ -454,7 +452,7 @@ EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); * @param data_free_cb The function called on each value when the hash table * is freed, or when an item is deleted from it. @c NULL can be passed as * callback. - * @return The new hash table. + * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table where keys are 32bit integers. * When adding or looking up in the hash table, pointers to 32bit integers @@ -463,7 +461,6 @@ EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); * be looked up with pointers other than the original key pointer that was * used to add values. This method is not suitable to match string keys as * it would only match the first character. - * On failure, this function returns @c NULL. */ EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); @@ -473,7 +470,7 @@ EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); * @param data_free_cb The function called on each value when the hash table * is freed, or when an item is deleted from it. @c NULL can be passed as * callback. - * @return The new hash table. + * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table where keys are 64bit integers. * When adding or looking up in the hash table, pointers to 64bit integers @@ -481,7 +478,6 @@ EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); * be looked up with pointers other than the original key pointer that was * used to add values. This method is not suitable to match string keys as * it would only match the first character. - * On failure, this function returns @c NULL. */ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); @@ -491,14 +487,14 @@ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); * @param data_free_cb The function called on each value when the hash table * is freed, or when an item is deleted from it. @c NULL can be passed as * callback. - * @return The new hash table. + * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table using the int64/int32 algorithm for * table management and dereferenced pointers to compare the * keys. Values can then be looked up with pointers other than the * original key pointer that was used to add values. This method may - * appear to be able to match string keys, actually it only matches - * the first character. On failure, this function returns @c NULL. + * appear to be able to match string keys, but actually it only matches + * the first character. * * @code * // For a hash that will have only one pointer to each structure @@ -517,12 +513,11 @@ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); * @param data_free_cb The function called on each value when the hash table * is freed, or when an item is deleted from it. @c NULL can be passed as * callback. - * @return The new hash table. + * @return The new hash table, or @c NULL on failure. * * This function creates a new hash table optimized for stringshared * values. Values CANNOT be looked up with pointers not - * equal to the original key pointer that was used to add a value. On failure, - * this function returns @c NULL. + * equal to the original key pointer that was used to add a value. * * Excerpt of code that will NOT work with this type of hash: * @@ -542,21 +537,23 @@ EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb); * * @param hash The given hash table. Cannot be @c NULL. * @param key A unique key. Cannot be @c NULL. - * @param data Data to associate with the string given by @p key. Cannot be @c + * @param data The data to associate with the string given by @p key. Cannot be @c * NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * - * This function adds @p key to @p hash. @p key is - * expected to be unique within the hash table. Key uniqueness varies - * depending on the type of @p hash: a stringshared @ref Eina_Hash - * need to have unique pointers (which implies unique strings). - * All other string hash types require the strings - * themselves to be unique. Pointer, int32 and int64 hashes need to have these - * values as unique. Failure to use sufficient uniqueness will + * This function adds @p key to @p hash. @p key must be unique within + * the hash table so that @ref eina_hash_find() and @ref eina_hash_del() + * operate on the correct data item. + * + * Key uniqueness varies depending on the type of @p hash: a + * stringshared @ref Eina_Hash needs unique pointers (which implies + * unique strings). All other string hash types require that the + * strings themselves are unique. Pointer, int32 and int64 hashes need + * to have unique values. Failure to use sufficient uniqueness will * result in unexpected results when inserting data pointers accessed - * with eina_hash_find(), and removed with eina_hash_del(). Key - * strings are case sensitive. This function returns #EINA_FALSE if an error - * occurred, #EINA_TRUE otherwise. + * with @ref eina_hash_find(), and removed with @ref eina_hash_del(). + * + * Key strings are case sensitive. */ EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, const void *key, @@ -567,23 +564,25 @@ EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, * * @param hash The given hash table. Cannot be @c NULL. * @param key A unique key. Cannot be @c NULL. - * @param data Data to associate with the string given by @p key. Cannot be @c - * NULL + * @param data The data to associate with the string given by @p + * key. Cannot be @c NULL * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * - * This function adds @p key to @p hash. @p key is - * expected to be unique within the hash table. Key uniqueness varies - * depending on the type of @p hash: a stringshared @ref Eina_Hash - * need have unique pointers (which implies unique strings). - * All other string hash types require the strings - * themselves to be unique. Pointer, int32 and int64 hashes need to have these - * values as unique. Failure to use sufficient uniqueness will + * This function adds @p key to @p hash. @p key must be unique within + * the hash table so that @ref eina_hash_find() and @ref eina_hash_del() + * operate on the correct data item. + * + * Key uniqueness varies depending on the type of @p hash: a + * stringshared @ref Eina_Hash needs unique pointers (which implies + * unique strings). All other string hash types require that the + * strings themselves are unique. Pointer, int32 and int64 hashes need + * to have unique values. Failure to use sufficient uniqueness will * result in unexpected results when inserting data pointers accessed - * with eina_hash_find(), and removed with eina_hash_del(). This - * function does not make a copy of @p key, so it must be a string - * constant or stored elsewhere ( in the object being added). Key - * strings are case sensitive. This function returns #EINA_FALSE if an error - * occurred, #EINA_TRUE otherwise. + * with @ref eina_hash_find(), and removed with @ref eina_hash_del(). + * + * Unlike @ref eina_hash_add(), this function does not make a copy of + * @p key, so it must be a string constant or stored elsewhere (such as + * in the object being added). Key strings are case sensitive. */ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, const void *key, @@ -604,13 +603,11 @@ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, * deleted. If @p hash is @c NULL, the function returns immediately #EINA_FALSE. * If @p key is @c NULL, then @p data is used to find the a * match to remove, otherwise @p key is used and @p data is not - * required and can be @c NULL. This function returns #EINA_FALSE if - * an error occurred, #EINA_TRUE otherwise. + * required and can be @c NULL. * - * @note if you know you already have the key, use - * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you - * know you don't have the key, use eina_hash_del_by_data() - * directly. + * @note If you already have the key, use eina_hash_del_by_key() or + * eina_hash_del_by_key_hash(). If you don't have the key, use + * eina_hash_del_by_data() directly. */ EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, const void *key, @@ -621,63 +618,59 @@ EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, * * @param hash The given hash table. * @param key The key of the entry to find. - * @return The data pointer for the stored entry on success, @c NULL + * @return The data pointer for the stored entry on success, or @c NULL * otherwise. * - * This function retrieves the entry associated to @p key in - * @p hash. If @p hash is @c NULL, this function returns immediately - * @c NULL. This function returns the data pointer on success, @c NULL - * otherwise. + * This function retrieves the entry associated with @p key in + * @p hash. If @p hash is @c NULL, this function returns @c NULL. */ EAPI void *eina_hash_find(const Eina_Hash *hash, const void *key) EINA_ARG_NONNULL(2); /** - * @brief Modifies the entry pointer at the specified key and return the old - * entry. + * @brief Modifies the entry pointer at the specified key and returns + * the previous entry. * @param hash The given hash table. * @param key The key of the entry to modify. - * @param data The data to replace the old entry. - * @return The data pointer for the old stored entry on success, or - * @c NULL otherwise. + * @param data The new data. + * @return The data pointer for the previously stored entry on success, + * or @c NULL otherwise. * * This function modifies the data of @p key with @p data in @p - * hash. If no entry is found, nothing is added to @p hash. On success - * this function returns the old entry, otherwise it returns @c NULL. + * hash. If no entry is found, nothing is added to @p hash. */ EAPI void *eina_hash_modify(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Modifies the entry pointer at the specified key and return the - * old entry or add the entry if not found. + * @brief Modifies the entry pointer at the specified key and returns the + * previous entry or adds the entry if not found. * * @param hash The given hash table. * @param key The key of the entry to modify. - * @param data The data to replace the old entry - * @return The data pointer for the old stored entry, or @c NULL + * @param data The data to replace the previous entry. + * @return The data pointer for the previous stored entry, or @c NULL * otherwise. * - * This function modifies the data of @p key with @p data in @p + * This function modifies the value of @p key to @p data in @p * hash. If no entry is found, @p data is added to @p hash with the - * key @p key. On success this function returns the old entry, - * otherwise it returns @c NULL. + * key @p key. */ EAPI void *eina_hash_set(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2); /** - * @brief Changes the key associated with a data without triggering the + * @brief Changes the key of an entry in a hash without triggering the * free callback. * * @param hash The given hash table. - * @param old_key The current key associated with the data - * @param new_key The new key to associate data with + * @param old_key The current key associated with the data. + * @param new_key The new key to associate data with. * @return #EINA_FALSE in any case but success, #EINA_TRUE on success. * - * This function allows for the move of data from one key to another, + * This function moves data from one key to another, * but does not call the Eina_Free_Cb associated with the hash table * when destroying the old key. */ @@ -686,18 +679,19 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, const void *new_key) EINA_ARG_NONNULL(1, 2, 3); /** - * @brief Frees the given hash table resources. + * @brief Frees the given hash table's resources. * * @param hash The hash table to be freed. * - * This function frees up all the memory allocated to storing @p hash, - * and calls the free callback if it has been passed to the hash table - * at creation time. If no free callback has been passed, any entries - * in the table that the program has no more pointers for elsewhere - * may now be lost, so this should only be called if the program has - * already freed any allocated data in the hash table or has the - * pointers for data in the table stored elsewhere as well. If @p hash - * is @c NULL, the function returns immediately. + * This function frees memory allocated for the @p hash and to its + * internal buckets. + * + * If @p data_free_cb was specified at creation time in + * @ref eina_hash_new, it will be called for each element as it gets + * freed. If the callback was not specified, then any data in these + * elements may now be lost, if not stored or freed elsewhere. + * + * If @p hash is @c NULL, the function returns immediately. * * Example: * @code @@ -714,12 +708,14 @@ EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1); * * @param hash The hash table whose buckets have to be freed. * - * This function frees up all the memory allocated to storing the - * buckets of @p hash, and calls the free callback on all hash table - * buckets if it has been passed to the hash table at creation time, - * then frees the buckets. If no free callback has been passed, no - * buckets value will be freed. If @p hash is @c NULL, the function - * returns immediately. + * This function frees memory allocated to internal buckets for @p hash. + * + * If @p data_free_cb was specified at creation time in + * @ref eina_hash_new(), it will be called for each element as it gets + * freed. If the callback was not specified, then any data in these + * elements may now be lost, if not stored or freed elsewhere. + * + * If @p hash is @c NULL, the function returns immediately. */ EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1); @@ -727,34 +723,29 @@ EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1); * @brief Returns the number of entries in the given hash table. * * @param hash The given hash table. - * @return The number of entries in the hash table. - * - * This function returns the number of entries in @p hash, or 0 on - * error. If @p hash is @c NULL, @c 0 is returned. + * @return The number of entries in the hash table, or @c 0 on error or + * if @p hash is @c NULL. */ EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1); /** - * @brief Adds an entry to the given hash table. + * @brief Adds an entry to the given hash table by its key hash. * * @param hash The given hash table. Cannot be @c NULL. * @param key A unique key. Cannot be @c NULL. - * @param key_length The length of the key. - * @param key_hash The hash that will always match key. + * @param key_length The length of @p key (including terminating '\\0'). + * @param key_hash The hash of @p key. * @param data The data to associate with the string given by the key. Cannot be * @c NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * - * This function adds @p key to @p hash. @p hash, @p key and @p data - * cannot be @c NULL, in that case #EINA_FALSE is returned. @p key is - * expected to be a unique within the hash table. Otherwise, - * one cannot be sure which inserted data pointer will be accessed - * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do - * not forget to count '\\0' for string when setting the value of - * @p key_length. @p key_hash is expected to always match - * @p key. Otherwise, one cannot be sure to find it again with @ref - * eina_hash_find_by_hash. Key strings are case sensitive. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * This function adds @p key to @p hash. + * + * @p key must be unique within the hash table so that + * @ref eina_hash_find() and @ref eina_hash_del() operate on the correct + * data item. @p key_hash must match @p key so that the correct item can + * be found by @ref eina_hash_find_by_hash(). Key strings are case + * sensitive. * * @see eina_hash_add() */ @@ -765,30 +756,27 @@ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1, 2, 5); /** - * @brief Adds an entry to the given hash table and do not duplicate the string - * key. + * @brief Adds an entry to a hash table by its key hash without duplicating the string key. * * @param hash The given hash table. Cannot be @c NULL. * @param key A unique key. Cannot be @c NULL. - * @param key_length Should be the length of @p key (don't forget to count - * '\\0' for string). - * @param key_hash The hash that will always match key. - * @param data Data to associate with the string given by @p key. Cannot be @c + * @param key_length The length of @p key (including terminating '\\0'). + * @param key_hash The hash of @p key. + * @param data The data to associate with the string given by @p key. Cannot be @c * NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * - * This function adds @p key to @p hash. @p hash, @p key and @p data - * can be @c NULL, in that case #EINA_FALSE is returned. @p key is - * expected to be unique within the hash table. Otherwise, - * one cannot be sure which inserted data pointer will be accessed - * with @ref eina_hash_find, and removed with @ref eina_hash_del. This - * function does not make a copy of @p key so it must be a string - * constant or stored elsewhere (in the object being added). Do - * not forget to count '\\0' for string when setting the value of - * @p key_length. @p key_hash is expected to always match - * @p key. Otherwise, one cannot be sure to find it again with @ref - * eina_hash_find_by_hash. Key strings are case sensitive. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * This function adds @p key to @p hash. + * + * @p key must be unique within the hash table so that + * @ref eina_hash_find() and @ref eina_hash_del() operate on the correct + * data item. @p key_hash must match @p key so that the correct item can + * be found by @ref eina_hash_find_by_hash(). Key strings are case + * sensitive. + * + * Unlike @ref eina_hash_add_by_hash(), this function does not make a + * copy of @p key, so it must be a string constant or stored elsewhere + * (such as inside the object being added). * * @see eina_hash_direct_add() */ @@ -804,20 +792,18 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash, * * @param hash The given hash table. Cannot be @c NULL. * @param key The key. Cannot be @c NULL. - * @param key_length The length of the key. + * @param key_length The length of the key (including terminating '\\0'). * @param key_hash The hash that always matches the key. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * * This function removes the entry identified by @p key and * @p key_hash from @p hash. If a free function was given to the * callback on creation, it will be called for the data being - * deleted. Do not forget to count '\\0' for string when setting the - * value of @p key_length. If @p hash or @p key are @c NULL, the - * function returns immediately #EINA_FALSE. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * deleted. If @p hash or @p key are @c NULL, the + * function returns #EINA_FALSE immediately. * - * @note If you don't have the key_hash, use eina_hash_del_by_key() instead. - * @note If you don't have the key, use eina_hash_del_by_data() instead. + * @note If you don't have the key_hash, use eina_hash_del_by_key() + * instead. If you don't have the key, use eina_hash_del_by_data(). */ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, const void *key, @@ -828,53 +814,50 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, * @brief Removes the entry identified by a key from the given hash table. * * This version will calculate key length and hash by using functions - * provided to hash creation function. + * provided to the hash creation function. * * @param hash The given hash table. Cannot be @c NULL. * @param key The key. Cannot be @c NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * * This function removes the entry identified by @p key from @p - * hash. The key length and hash will be calculated automatically by - * using function provided to hash creation function. If a free + * hash. The key length and hash will be calculated automatically via + * a function provided to the hash creation function. If a free * function was given to the callback on creation, it will be called * for the data being deleted. If @p hash or @p key are @c NULL, the - * function returns immediately #EINA_FALSE. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * function returns #EINA_FALSE immediately. * - * @note If you already have the key_hash, use eina_hash_del_by_key_hash() - * instead. - * @note If you don't have the key, use eina_hash_del_by_data() instead. + * @note If you already have the key_hash, use eina_hash_del_by_key_hash(). + * If you don't have the key, use eina_hash_del_by_data() instead. */ EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, const void *key) EINA_ARG_NONNULL(1, 2); /** - * @brief Removes the entry identified by a data from the given hash table. - * - * This version is slow since there is no quick access to nodes based on data. + * @brief Removes an entry from a hash table identified by its data value. * * @param hash The given hash table. Cannot be @c NULL. * @param data The data value to search and remove. Cannot be @c NULL. - * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * @return #EINA_FALSE if an error occurred or if @p hash or @p data are + * @c NULL, #EINA_TRUE otherwise. * thing goes fine. * * This function removes the entry identified by @p data from @p * hash. If a free function was given to the callback on creation, it - * will be called for the data being deleted. If @p hash or @p data - * are @c NULL, the function returns immediately #EINA_FALSE. This - * function returns #EINA_FALSE if an error occurred, #EINA_TRUE - * otherwise. + * will be called for the data being deleted. * - * @note If you already have the key, use eina_hash_del_by_key() or - * eina_hash_del_by_key_hash() instead. + * @note This version is slow since there is no quick access to nodes + * based on data. + * + * @note If you already have the key, use eina_hash_del_by_key() + * or eina_hash_del_by_key_hash() instead. */ EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1, 2); /** - * @brief Removes the entry identified by a key and a key hash or a - * data from the given hash table. + * @brief Removes the entry identified by a key and a key hash, or a + * data value from the given hash table. * * If @p key is @c NULL, then @p data is used to find a match to * remove. @@ -886,20 +869,18 @@ EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, * @param data The data pointer to remove if the key is @c NULL. * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * - * This function removes the entry identified by @p key and - * @p key_hash, or @p data, from @p hash. If a free function was given to - * the callback on creation, it will be called for the data being - * deleted. If @p hash is @c NULL, the function returns immediately #EINA_FALSE. - * If @p key is @c NULL, then @p key_length and @p key_hash - * are ignored and @p data is used to find a match to remove, - * otherwise @p key and @p key_hash are used and @p data is not - * required and can be @c NULL. Do not forget to count '\\0' for - * string when setting the value of @p key_length. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * This function removes the entry identified by @p key and @p key_hash, + * or @p data, from @p hash. If a free function was given to the + * callback on creation, it will be called for the data being + * deleted. If @p hash is @c NULL, the function returns #EINA_FALSE + * immediately. If @p key is @c NULL, then @p key_length and @p + * key_hash are ignored and @p data is used to find a match to remove, + * otherwise @p key and @p key_hash are used and @p data is not required + * and can be @c NULL. Do not forget to count '\\0' for string when + * setting the value of @p key_length. * - * @note If you know you already have the key, use eina_hash_del_by_key_hash(), - * If you know you don't have the key, use eina_hash_del_by_data() - * directly. + * @note If you already have the key, use eina_hash_del_by_key_hash(). + * If you don't have the key, use eina_hash_del_by_data() directly. */ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, const void *key, @@ -908,21 +889,19 @@ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1); /** - * @brief Retrieves a specific entry in the given hash table. + * @brief Retrieves a specific entry from the given hash table. * * @param hash The given hash table. Cannot be @c NULL. * @param key The key of the entry to find. * @param key_length The length of the key. - * @param key_hash The hash that always match the key - * @return The data pointer for the stored entry on success, @c NULL - * otherwise. + * @param key_hash The hash that always matches the key + * @return The data pointer for the stored entry on success, or @c NULL + * if @p hash is @c NULL or if the data pointer could not be retrieved. * - * This function retrieves the entry associated to @p key of length - * @p key_length in @p hash. @p key_hash is the hash that always match + * This function retrieves the entry associated with @p key of length + * @p key_length in @p hash. @p key_hash is the hash that always matches * @p key. It is ignored if @p key is @c NULL. Do not forget to count - * '\\0' for string when setting the value of @p key_length. If - * @p hash is @c NULL, this function returns immediately @c NULL. This - * function returns the data pointer on success, @c NULL otherwise. + * '\\0' for string when setting the value of @p key_length. */ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, const void *key, @@ -931,18 +910,18 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, /** * @brief Modifies the entry pointer at the specified key and returns - * the old entry. + * the previous entry. * * @param hash The given hash table. * @param key The key of the entry to modify. * @param key_length Should be the length of @p key (don't forget to count * '\\0' for string). - * @param key_hash The hash that always match the key. Ignored if @p key is - * @c NULL. - * @param data The data to replace the old entry, if it exists. - * @return The data pointer for the old stored entry, or @c NULL if not - * found. If an existing entry is not found, nothing is added to the - * hash. + * @param key_hash The hash that always matches the key. Ignored if @p + * key is @c NULL. + * @param data The data to replace the current entry, if it exists. + * @return The data pointer for the previously stored entry, or @c NULL + * if not found. If an existing entry is not found, nothing is added to + * the hash. */ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, const void *key, @@ -951,80 +930,68 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, const void *data) EINA_ARG_NONNULL(1, 2, 5); /** - * @brief Returns a new iterator associated to hash keys. + * @brief Returns a new iterator associated with hash keys. * * @param hash The hash. - * @return A new iterator. + * @return A new iterator, or @c NULL if memory could not be allocated. * - * This function returns a newly allocated iterator associated to @p + * This function returns a newly allocated iterator associated with @p * hash. If @p hash is not populated, this function still returns a * valid iterator that will always return false on - * eina_iterator_next(), thus keeping API sane. - * - * If the memory can not be allocated, NULL is returned. - * Otherwise, a valid iterator is returned. + * eina_iterator_next(). * - * @warning if the hash structure changes then the iterator becomes - * invalid! That is, if you add or remove items this iterator - * behavior is undefined and your program may crash! + * @warning If the hash structure changes then the iterator becomes + * invalid; adding or removing items may lead to program crash. */ EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Returns a new iterator associated to hash data. + * @brief Returns a new iterator associated with a hash. * * @param hash The hash. - * @return A new iterator. + * @return A new iterator, or @c NULL if memory could not be allocated. * - * This function returns a newly allocated iterator associated to + * This function returns a newly allocated iterator associated with * @p hash. If @p hash is not populated, this function still returns a * valid iterator that will always return false on - * eina_iterator_next(), thus keeping API sane. + * eina_iterator_next(). * - * If the memory cannot be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. - * - * @warning if the hash structure changes then the iterator becomes - * invalid. That is, if you add or remove items this iterator behavior - * is undefined and your program may crash. + * @warning If the hash structure changes then the iterator becomes + * invalid; adding or removing items may lead to program crash. */ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** - * @brief Returned a new iterator associated to hash keys and data. + * @brief Returned a new iterator associated with hash keys and data. * * @param hash The hash. - * @return A new iterator. + * @return A new iterator, or @c NULL if memory could not be allocated. * - * This function returns a newly allocated iterator associated to @p + * This function returns a newly allocated iterator associated with @p * hash. If @p hash is not populated, this function still returns a * valid iterator that will always return false on - * eina_iterator_next(), thus keeping API sane. - * - * If the memory can not be allocated, @c NULL is returned. - * Otherwise, a valid iterator is returned. + * eina_iterator_next(). * - * @note Iterator data will provide values as Eina_Hash_Tuple that should not - * be modified! + * @note Iterator data will provide values as Eina_Hash_Tuple that + * should not be modified! * - * @warning if the hash structure changes then the iterator becomes - * invalid! That is, if you add or remove items this iterator - * behavior is undefined and your program may crash! + * @warning If the hash structure changes then the iterator becomes + * invalid; adding or removing items may lead to program crash. */ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** * @brief Calls a function on every member stored in the hash table. * - * @param hash The hash table whose members will be walked - * @param func The function to call on each parameter - * @param fdata The data pointer to pass to the function being called + * @param hash The hash table whose members will be walked. + * @param func The function to call on each parameter. + * @param fdata The data pointer to pass to the function being called. * - * This function goes through every entry in the hash table @p hash and calls - * the function @p func on each member. The function should @b not modify the - * hash table contents if it returns @c 1. @b If the hash table contents are - * modified by this function or the function wishes to stop processing it must - * return @c 0, otherwise return @c 1 to keep processing. + * This function iterates over the hash table @p hash, calling the + * function @p func on each member. If @p func modifies the contents + * of the hash table, or wishes to stop processing it should return + * #EINA_FALSE. If @p func returns #EINA_TRUE the foreach loop will + * keep processing. * * Example: * @code @@ -1035,7 +1002,7 @@ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MAL * { * printf("Func data: %s, Hash entry: %s / %p\n", * fdata, (const char *)key, data); - * return 1; + * return EINA_TRUE; * } * * int main(int argc, char **argv) @@ -1059,9 +1026,9 @@ EAPI void eina_hash_foreach(const Eina_Hash *hash, * This function is identical to the sequence of calling * eina_hash_find(), eina_list_append(), eina_hash_set(), * but with one fewer required hash lookup. - * @param hash The hash table - * @param key The key associated with the data - * @param data The data to append to the list + * @param hash The hash table. + * @param key The key associated with the data. + * @param data The data to append to the list. * @since 1.10 */ EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); @@ -1071,9 +1038,9 @@ EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *da * This function is identical to the sequence of calling * eina_hash_find(), eina_list_prepend(), eina_hash_set(), * but with one fewer required hash lookup. - * @param hash The hash table - * @param key The key associated with the data - * @param data The data to prepend to the list + * @param hash The hash table. + * @param key The key associated with the data. + * @param data The data to prepend to the list. * @since 1.10 */ EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); @@ -1083,9 +1050,9 @@ EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *d * This function is identical to the sequence of calling * eina_hash_find(), eina_list_remove(), eina_hash_set(), * but with one fewer required hash lookup. - * @param hash The hash table - * @param key The key associated with the data - * @param data The data to remove from the list + * @param hash The hash table. + * @param key The key associated with the data. + * @param data The data to remove from the list. * @since 1.10 */ EAPI void eina_hash_list_remove(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); @@ -1094,9 +1061,9 @@ EAPI void eina_hash_list_remove(Eina_Hash *hash, const void *key, const void *da * @brief * Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) * - * @param key The key to hash - * @param len The length of the key - * @return The hash value + * @param key The key to hash. + * @param len The length of the key. + * @return The hash value. */ EAPI int eina_hash_superfast(const char *key, int len) EINA_ARG_NONNULL(1); @@ -1105,9 +1072,9 @@ EAPI int eina_hash_superfast(const char *key, * @brief * Hash function first reported by Dan Bernstein many years ago in comp.lang.c * - * @param key The key to hash - * @param len The length of the key - * @return The hash value + * @param key The key to hash. + * @param len The length of the key. + * @return The hash value. */ static inline int eina_hash_djb2(const char *key, int len) EINA_ARG_NONNULL(1); @@ -1116,9 +1083,9 @@ static inline int eina_hash_djb2(const char *key, * @brief * Hash function first reported by Dan Bernstein many years ago in comp.lang.c * - * @param key The key to hash - * @param plen The length of the key - * @return The hash value + * @param key The key to hash. + * @param plen The length of the key. + * @return The hash value. */ static inline int eina_hash_djb2_len(const char *key, int *plen) EINA_ARG_NONNULL(1, 2); @@ -1127,9 +1094,9 @@ static inline int eina_hash_djb2_len(const char *key, * @brief * Hash function from http://web.archive.org/web/20071223173210/http://www.concentric.net/~Ttwang/tech/inthash.htm * - * @param pkey The key to hash - * @param len The length of the key - * @return The hash value + * @param pkey The key to hash. + * @param len The length of the key. + * @return The hash value. */ static inline int eina_hash_int32(const unsigned int *pkey, int len) EINA_ARG_NONNULL(1); @@ -1138,9 +1105,9 @@ static inline int eina_hash_int32(const unsigned int *pkey, * @brief * Hash function from http://web.archive.org/web/20071223173210/http://www.concentric.net/~Ttwang/tech/inthash.htm * - * @param pkey The key to hash - * @param len The length of the key - * @return The hash value + * @param pkey The key to hash. + * @param len The length of the key. + * @return The hash value. */ static inline int eina_hash_int64(const unsigned long long int *pkey, int len) EINA_ARG_NONNULL(1); @@ -1149,9 +1116,9 @@ static inline int eina_hash_int64(const unsigned long long int *pkey, * @brief * Hash function from http://sites.google.com/site/murmurhash/ * - * @param key The key to hash - * @param len The length of the key - * @return The hash value + * @param key The key to hash. + * @param len The length of the key. + * @return The hash value. */ static inline int eina_hash_murmur3(const char *key, int len) EINA_ARG_NONNULL(1); @@ -1160,9 +1127,9 @@ static inline int eina_hash_murmur3(const char *key, * @brief * Hash function using crc-32 algorithm and and 0xEDB88320 polynomial * - * @param key The key to hash - * @param len The length of the key - * @return The hash value + * @param key The key to hash. + * @param len The length of the key. + * @return The hash value. */ static inline int eina_hash_crc(const char *key, int len) EINA_ARG_NONNULL(1); |