diff --git a/legacy/eina/src/include/eina_hash.h b/legacy/eina/src/include/eina_hash.h index 5a27bbfcb0..9f3be0ca8f 100644 --- a/legacy/eina/src/include/eina_hash.h +++ b/legacy/eina/src/include/eina_hash.h @@ -23,6 +23,35 @@ #include "eina_types.h" #include "eina_iterator.h" +/** + * @addtogroup Eina_Hash_Group Hash Table + * + * @brief give a small description here : what it is for, what it does + * , etc... + * Different implementations exists depending on what to store: strings, + * integers, pointers, stringshared or your own... + * Eina hash tables can copy the keys when using eina_hash_add() or not when + * using eina_hash_direct_add(). + * + * Hash API. Give some hints about the use (functions that must be + * used like init / shutdown), general use, etc... Give also a link to + * tutorial below. + * + * @section hashtable_algo Algorithm + * + * Give here the algorithm used in the implementation + * + * @section hashtable_perf Performance + * + * Give some hints about performance if it is possible, and an image ! + * + * @section hashtable_tutorial Tutorial + * + * Here is a fantastic tutorial about our hash table + * + * @{ + */ + /** * @addtogroup Eina_Data_Types_Group Data Types * @@ -64,76 +93,679 @@ typedef int (*Eina_Key_Hash)(const void *key, int key_length); #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function) typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata); + +/** + * @brief Create a new hash table. + * + * @param key_length_cb The function called when getting the size of the 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 when the hash table is freed. + * @param buckets_power_size The size of the buckets. + * @return The new hash table. + * + * This function creates a new hash table using user-defined callbacks + * to manage the hash table. On failure, @c NULL is returned and + * #EINA_ERROR_OUT_OF_MEMORY is set. 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. + * + * Pre-defined functions are available to create a hash table. See + * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(), + * eina_hash_string_small_new(), eina_hash_int32_new(), + * eina_hash_int64_new(), eina_hash_pointer_new() and + * eina_hash_stringshared_new(). + */ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb, Eina_Key_Cmp key_cmp_cb, Eina_Key_Hash key_hash_cb, Eina_Free_Cb data_free_cb, int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3); + +/** + * @brief Create a new hash table using the djb2 algorithm. + * + * @param data_free_cb The function called when the hash table is freed. + * @return The new hash table. + * + * 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. + * @p data_free_cb is a callback called when the hash table is + * freed. @c NULL can be passed as callback. + */ EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); + +/** + * @brief Create a new hash table for use with strings. + * + * @param data_free_cb The function called when the hash table is freed. + * @return The new hash table. + * + * 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. @p data_free_cb is a callback called when the hash table is + * freed. @c NULL can be passed as callback. + */ EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); + +/** + * @brief Create a new hash table for use with strings with small bucket size. + * + * @param data_free_cb The function called when the hash table is freed. + * @return The new hash table. + * + * 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. @p data_free_cb is a callback called when + * the hash table is freed. @c NULL can be passed as callback. + */ EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); + +/** + * @brief Create a new hash table for use with 32bit integers. + * + * @param data_free_cb The function called when the hash table is freed. + * @return The new hash table. + * + * 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 + * must be passed. They can be addresses on the stack if you let the + * eina_hash copy the key. Values can then + * 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. + * @p data_free_cb is a callback called when the hash table is freed. + * @c NULL can be passed as callback. + */ EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); + +/** + * @brief Create a new hash table for use with 64bit integers. + * + * @param data_free_cb The function called when the hash table is freed. + * @return The new hash table. + * + * 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 + * must be passed. They can be addresses on the stack. Values can then + * 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. + * @p data_free_cb is a callback called when the hash table is freed. + * @c NULL can be passed as callback. + */ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); + +/** + * @brief Create a new hash table for use with pointers. + * + * @param data_free_cb The function called when the hash table is freed. + * @return The new hash table. + * + * 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. + * @p data_free_cb is a callback called when the hash table is freed. + * @c NULL can be passed as callback. + */ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); + +/** + * @brief Create a new hash table optimized for stringshared values. + * + * @param data_free_cb The function called when the hash table is freed. + * @return The new hash table. + * + * This function creates a new hash table optimized for stringshared + * values. Values CAN NOT 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. + * @p data_free_cb is a callback called when the hash table is freed. + * @c NULL can be passed as callback. + * + * Excerpt of code that will NOT work with this type of hash: + * + * @code + * extern Eina_Hash *hash; + * extern const char *value; + * const char *a = eina_stringshare_add("key"); + * + * eina_hash_add(hash, a, value); + * eina_hash_find(hash, "key") + * @endcode + */ EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb); + +/** + * @brief Add an entry to the given hash table. + * + * @param hash The given hash table. + * @param key A unique key. + * @param data Data to associate with the string given by @p key. + * @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. Key uniqueness varies + * depending on the type of @p hash: a stringshared @ref Eina_Hash + * need only have unique pointers for keys, but the strings in the + * pointers may be identical. All other hash types require the strings + * themselves to be unique. 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. If an error occurs, eina_error_get() + * should be used to determine if an allocation error occurred during + * this function. This function returns #EINA_FALSE if an error + * occurred, #EINA_TRUE otherwise. + */ EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Add an entry to the given hash table without duplicating the string + * key. + * + * @param hash The given hash table. Can be @c NULL. + * @param key A unique key. Can be @c NULL. + * @param data Data to associate with the string given by @p key. + * @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. Key uniqueness varies + * depending on the type of @p hash: a stringshared @ref Eina_Hash + * need only have unique pointers for keys, but the strings in the + * pointers may be identical. All other hash types require the strings + * themselves to be unique. 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. If an error occurs, eina_error_get() + * should be used to determine if an allocation error occurred during + * this function. This function returns #EINA_FALSE if an error + * occurred, #EINA_TRUE otherwise. + */ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Remove the entry identified by a key or a data from the given + * hash table. + * + * @param hash The given hash table. + * @param key The key. + * @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 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 functions 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. + * + * @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. + */ EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1); + +/** + * @brief Retrieve a specific entry in the given hash table. + * + * @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 + * 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. + */ EAPI void *eina_hash_find(const Eina_Hash *hash, const void *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Modify the entry pointer at the specified key and return the old + * 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. + * + * 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. + */ EAPI void *eina_hash_modify(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Modify the entry pointer at the specified key and return the + * old entry or add 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 + * otherwise. + * + * This function modifies the data of @p key with @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. To check for errors, use + * eina_error_get(). + */ EAPI void *eina_hash_set(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Change the key associated with a data 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 + * @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, + * but does not call the Eina_Free_Cb associated with the hash table + * when destroying the old key. + */ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, const void *old_key, const void *new_key) EINA_ARG_NONNULL(1, 2, 3); + +/** + * Free the given hash table resources. + * + * @param hash The hash table to be freed. + * + * This function frees up all the memory allocated to storing @p hash, + * and call 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. + * + * Example: + * @code + * extern Eina_Hash *hash; + * + * eina_hash_free(hash); + * hash = NULL; + * @endcode + */ EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1); + +/** + * Free the given hash table buckets resources. + * + * @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. + */ 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, 0 is returned. + */ EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1); + +/** + * @brief Add an entry to the given hash table. + * + * @param hash The given hash table. + * @param key A unique key. + * @param key_length The length of the key. + * @param key_hash The hash that will always match key. + * @param data The data to associate with the string given by the key. + * @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 a unique string 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. If an error + * occurs, eina_error_get() should be used to determine if an + * allocation error occurred during this function. This function + * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + */ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash, const void *key, int key_length, int key_hash, const void *data) EINA_ARG_NONNULL(1, 2, 5); + +/** + * @brief Add an entry to the given hash table and do not duplicate the string + * key. + * + * @param hash The given hash table. Can be @c NULL. + * @param key A unique key. Can 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. + * @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 a unique string 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. If an error + * occurs, eina_error_get() should be used to determine if an + * allocation error occurred during this function. This function + * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + */ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash, const void *key, int key_length, int key_hash, const void *data) EINA_ARG_NONNULL(1, 2, 5); + +/** + * @brief Remove the entry identified by a key and a key hash from the given + * hash table. + * + * @param hash The given hash table. + * @param key The key. + * @param key_length The length of the key. + * @param key_hash The hash that always match 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 + * functions returns immediately #EINA_FALSE. This function returns + * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * + * @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. + */ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, const void *key, int key_length, int key_hash) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Remove 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. + * + * @param hash The given hash table. + * @param key The key. + * @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 functiond provided to has 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 + * functions returns immediately #EINA_FALSE. This function returns + * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. + * + * @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. + */ EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, const void *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Remove 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. + * + * @param hash The given hash table. + * @param data The data value to search and remove. + * @return #EINA_FALSE if an error occurred, #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 functions returns immediately #EINA_FALSE. This + * function returns #EINA_FALSE if an error occurred, #EINA_TRUE + * otherwise. + * + * @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 Remove the entry identified by a key and a key hash or a + * data from the given hash table. + * + * If @p key is @c NULL, then @p data is used to find a match to + * remove. + * + * @param hash The given hash table. + * @param key The key. + * @param key_length The length of the key. + * @param key_hash The hash that always match the key. + * @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 functions returns immediately + * #EINA_FALSE. If @p key is @c NULL, then @p key_hash 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. + * + * @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. + */ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, const void *key, int key_length, int key_hash, const void *data) EINA_ARG_NONNULL(1); + +/** + * @brief Retrieve a specific entry in the given hash table. + * + * @param hash The given hash table. + * @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. + * + * 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 + * @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. + */ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, const void *key, int key_length, int key_hash) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Modify the entry pointer at the specified key and returns + * the old 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. + */ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, const void *key, int key_length, int key_hash, const void *data) EINA_ARG_NONNULL(1, 2, 5); + +/** + * @brief Returned a new iterator associated to hash keys. + * + * @param hash The hash. + * @return A new iterator. + * + * This function returns a newly allocated iterator associated to @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 and + * #EINA_ERROR_OUT_OF_MEMORY is set. 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! + */ EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Returned a new iterator associated to hash data. + * + * @param hash The hash. + * @return A new iterator. + * + * This function returns a newly allocated iterator associated to + * @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 and + * #EINA_ERROR_OUT_OF_MEMORY is set. 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. + */ 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. + * + * @param hash The hash. + * @return A new iterator. + * + * This function returns a newly allocated iterator associated to @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 and + * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. + * + * @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! + */ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Call 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 + * + * 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 1. @b If the hash table contents are + * modified by this function or the function wishes to stop processing it must + * return 0, otherwise return 1 to keep processing. + * + * Example: + * @code + * extern Eina_Hash *hash; + * + * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key, + * void *data, void *fdata) + * { + * printf("Func data: %s, Hash entry: %s / %p\n", + * fdata, (const char *)key, data); + * return 1; + * } + * + * int main(int argc, char **argv) + * { + * char *hash_fn_data; + * + * hash_fn_data = strdup("Hello World"); + * eina_hash_foreach(hash, hash_fn, hash_fn_data); + * free(hash_fn_data); + * } + * @endcode + */ EAPI void eina_hash_foreach(const Eina_Hash *hash, Eina_Hash_Foreach cb, const void *fdata) EINA_ARG_NONNULL(1, 2); @@ -165,4 +797,8 @@ static inline int eina_hash_int64(const unsigned long int *pkey, * @} */ +/** + * @} + */ + #endif /*EINA_HASH_H_*/ diff --git a/legacy/eina/src/lib/eina_hash.c b/legacy/eina/src/lib/eina_hash.c index 06502be6fa..2e9040a00c 100644 --- a/legacy/eina/src/lib/eina_hash.c +++ b/legacy/eina/src/lib/eina_hash.c @@ -713,58 +713,6 @@ _eina_hash_iterator_free(Eina_Iterator_Hash *it) * API * *============================================================================*/ -/** - * @addtogroup Eina_Hash_Group Hash Table - * - * @brief give a small description here : what it is for, what it does - * , etc... - * Different implementations exists depending on what to store: strings, - * integers, pointers, stringshared or your own... - * Eina hash tables can copy the keys when using eina_hash_add() or not when - * using eina_hash_direct_add(). - * - * Hash API. Give some hints about the use (functions that must be - * used like init / shutdown), general use, etc... Give also a link to - * tutorial below. - * - * @section hashtable_algo Algorithm - * - * Give here the algorithm used in the implementation - * - * @section hashtable_perf Performance - * - * Give some hints about performance if it is possible, and an image ! - * - * @section hashtable_tutorial Tutorial - * - * Here is a fantastic tutorial about our hash table - * - * @{ - */ - -/** - * @brief Create a new hash table. - * - * @param key_length_cb The function called when getting the size of the 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 when the hash table is freed. - * @param buckets_power_size The size of the buckets. - * @return The new hash table. - * - * This function creates a new hash table using user-defined callbacks - * to manage the hash table. On failure, @c NULL is returned and - * #EINA_ERROR_OUT_OF_MEMORY is set. 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. - * - * Pre-defined functions are available to create a hash table. See - * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(), - * eina_hash_string_small_new(), eina_hash_int32_new(), - * eina_hash_int64_new(), eina_hash_pointer_new() and - * eina_hash_stringshared_new(). - */ EAPI Eina_Hash * eina_hash_new(Eina_Key_Length key_length_cb, Eina_Key_Cmp key_cmp_cb, @@ -804,19 +752,6 @@ on_error: return NULL; } -/** - * @brief Create a new hash table using the djb2 algorithm. - * - * @param data_free_cb The function called when the hash table is freed. - * @return The new hash table. - * - * 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. - * @p data_free_cb is a callback called when the hash table is - * freed. @c NULL can be passed as callback. - */ EAPI Eina_Hash * eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb) { @@ -827,19 +762,6 @@ eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb) EINA_HASH_BUCKET_SIZE); } -/** - * @brief Create a new hash table for use with strings. - * - * @param data_free_cb The function called when the hash table is freed. - * @return The new hash table. - * - * 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. @p data_free_cb is a callback called when the hash table is - * freed. @c NULL can be passed as callback. - */ EAPI Eina_Hash * eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb) { @@ -850,21 +772,6 @@ eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb) EINA_HASH_BUCKET_SIZE); } -/** - * @brief Create a new hash table for use with strings with small bucket size. - * - * @param data_free_cb The function called when the hash table is freed. - * @return The new hash table. - * - * 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. @p data_free_cb is a callback called when - * the hash table is freed. @c NULL can be passed as callback. - */ EAPI Eina_Hash * eina_hash_string_small_new(Eina_Free_Cb data_free_cb) { @@ -875,23 +782,6 @@ eina_hash_string_small_new(Eina_Free_Cb data_free_cb) EINA_HASH_SMALL_BUCKET_SIZE); } -/** - * @brief Create a new hash table for use with 32bit integers. - * - * @param data_free_cb The function called when the hash table is freed. - * @return The new hash table. - * - * 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 - * must be passed. They can be addresses on the stack if you let the - * eina_hash copy the key. Values can then - * 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. - * @p data_free_cb is a callback called when the hash table is freed. - * @c NULL can be passed as callback. - */ EAPI Eina_Hash * eina_hash_int32_new(Eina_Free_Cb data_free_cb) { @@ -902,22 +792,6 @@ eina_hash_int32_new(Eina_Free_Cb data_free_cb) EINA_HASH_BUCKET_SIZE); } -/** - * @brief Create a new hash table for use with 64bit integers. - * - * @param data_free_cb The function called when the hash table is freed. - * @return The new hash table. - * - * 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 - * must be passed. They can be addresses on the stack. Values can then - * 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. - * @p data_free_cb is a callback called when the hash table is freed. - * @c NULL can be passed as callback. - */ EAPI Eina_Hash * eina_hash_int64_new(Eina_Free_Cb data_free_cb) { @@ -928,21 +802,6 @@ eina_hash_int64_new(Eina_Free_Cb data_free_cb) EINA_HASH_BUCKET_SIZE); } -/** - * @brief Create a new hash table for use with pointers. - * - * @param data_free_cb The function called when the hash table is freed. - * @return The new hash table. - * - * 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. - * @p data_free_cb is a callback called when the hash table is freed. - * @c NULL can be passed as callback. - */ EAPI Eina_Hash * eina_hash_pointer_new(Eina_Free_Cb data_free_cb) { @@ -961,30 +820,6 @@ eina_hash_pointer_new(Eina_Free_Cb data_free_cb) #endif } -/** - * @brief Create a new hash table optimized for stringshared values. - * - * @param data_free_cb The function called when the hash table is freed. - * @return The new hash table. - * - * This function creates a new hash table optimized for stringshared - * values. Values CAN NOT 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. - * @p data_free_cb is a callback called when the hash table is freed. - * @c NULL can be passed as callback. - * - * Excerpt of code that will NOT work with this type of hash: - * - * @code - * extern Eina_Hash *hash; - * extern const char *value; - * const char *a = eina_stringshare_add("key"); - * - * eina_hash_add(hash, a, value); - * eina_hash_find(hash, "key") - * @endcode - */ EAPI Eina_Hash * eina_hash_stringshared_new(Eina_Free_Cb data_free_cb) { @@ -995,15 +830,6 @@ eina_hash_stringshared_new(Eina_Free_Cb data_free_cb) EINA_HASH_BUCKET_SIZE); } -/** - * @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, 0 is returned. - */ EAPI int eina_hash_population(const Eina_Hash *hash) { @@ -1014,28 +840,6 @@ eina_hash_population(const Eina_Hash *hash) return hash->population; } -/** - * Free the given hash table resources. - * - * @param hash The hash table to be freed. - * - * This function frees up all the memory allocated to storing @p hash, - * and call 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. - * - * Example: - * @code - * extern Eina_Hash *hash; - * - * eina_hash_free(hash); - * hash = NULL; - * @endcode - */ EAPI void eina_hash_free(Eina_Hash *hash) { @@ -1053,18 +857,6 @@ eina_hash_free(Eina_Hash *hash) free(hash); } -/** - * Free the given hash table buckets resources. - * - * @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. - */ EAPI void eina_hash_free_buckets(Eina_Hash *hash) { @@ -1084,29 +876,6 @@ eina_hash_free_buckets(Eina_Hash *hash) } } -/** - * @brief Add an entry to the given hash table. - * - * @param hash The given hash table. - * @param key A unique key. - * @param key_length The length of the key. - * @param key_hash The hash that will always match key. - * @param data The data to associate with the string given by the key. - * @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 a unique string 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. If an error - * occurs, eina_error_get() should be used to determine if an - * allocation error occurred during this function. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - */ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash, const void *key, @@ -1122,33 +891,6 @@ eina_hash_add_by_hash(Eina_Hash *hash, data); } -/** - * @brief Add an entry to the given hash table and do not duplicate the string - * key. - * - * @param hash The given hash table. Can be @c NULL. - * @param key A unique key. Can 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. - * @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 a unique string 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. If an error - * occurs, eina_error_get() should be used to determine if an - * allocation error occurred during this function. This function - * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - */ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash, const void *key, @@ -1159,28 +901,6 @@ eina_hash_direct_add_by_hash(Eina_Hash *hash, return eina_hash_add_alloc_by_hash(hash, key, key_length, 0, key_hash, data); } -/** - * @brief Add an entry to the given hash table. - * - * @param hash The given hash table. - * @param key A unique key. - * @param data Data to associate with the string given by @p key. - * @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. Key uniqueness varies - * depending on the type of @p hash: a stringshared @ref Eina_Hash - * need only have unique pointers for keys, but the strings in the - * pointers may be identical. All other hash types require the strings - * themselves to be unique. 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. If an error occurs, eina_error_get() - * should be used to determine if an allocation error occurred during - * this function. This function returns #EINA_FALSE if an error - * occurred, #EINA_TRUE otherwise. - */ EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, const void *key, const void *data) { @@ -1199,31 +919,6 @@ eina_hash_add(Eina_Hash *hash, const void *key, const void *data) return eina_hash_add_alloc_by_hash(hash, key, key_length, key_length, key_hash, data); } -/** - * @brief Add an entry to the given hash table without duplicating the string - * key. - * - * @param hash The given hash table. Can be @c NULL. - * @param key A unique key. Can be @c NULL. - * @param data Data to associate with the string given by @p key. - * @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. Key uniqueness varies - * depending on the type of @p hash: a stringshared @ref Eina_Hash - * need only have unique pointers for keys, but the strings in the - * pointers may be identical. All other hash types require the strings - * themselves to be unique. 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. If an error occurs, eina_error_get() - * should be used to determine if an allocation error occurred during - * this function. This function returns #EINA_FALSE if an error - * occurred, #EINA_TRUE otherwise. - */ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, const void *key, const void *data) { @@ -1242,27 +937,6 @@ eina_hash_direct_add(Eina_Hash *hash, const void *key, const void *data) return eina_hash_add_alloc_by_hash(hash, key, key_length, 0, key_hash, data); } -/** - * @brief Remove the entry identified by a key and a key hash from the given - * hash table. - * - * @param hash The given hash table. - * @param key The key. - * @param key_length The length of the key. - * @param key_hash The hash that always match 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 - * functions returns immediately #EINA_FALSE. This function returns - * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * @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. - */ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, const void *key, @@ -1275,28 +949,6 @@ eina_hash_del_by_key_hash(Eina_Hash *hash, return _eina_hash_del_by_key_hash(hash, key, key_length, key_hash, NULL); } -/** - * @brief Remove 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. - * - * @param hash The given hash table. - * @param key The key. - * @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 functiond provided to has 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 - * functions returns immediately #EINA_FALSE. This function returns - * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. - * - * @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. - */ EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, const void *key) { @@ -1306,26 +958,6 @@ eina_hash_del_by_key(Eina_Hash *hash, const void *key) return _eina_hash_del_by_key(hash, key, NULL); } -/** - * @brief Remove 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. - * - * @param hash The given hash table. - * @param data The data value to search and remove. - * @return #EINA_FALSE if an error occurred, #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 functions returns immediately #EINA_FALSE. This - * function returns #EINA_FALSE if an error occurred, #EINA_TRUE - * otherwise. - * - * @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) { @@ -1350,35 +982,6 @@ error: return EINA_FALSE; } -/** - * @brief Remove the entry identified by a key and a key hash or a - * data from the given hash table. - * - * If @p key is @c NULL, then @p data is used to find a match to - * remove. - * - * @param hash The given hash table. - * @param key The key. - * @param key_length The length of the key. - * @param key_hash The hash that always match the key. - * @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 functions returns immediately - * #EINA_FALSE. If @p key is @c NULL, then @p key_hash 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. - * - * @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. - */ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, const void *key, @@ -1399,29 +1002,6 @@ eina_hash_del_by_hash(Eina_Hash *hash, return ret; } -/** - * @brief Remove the entry identified by a key or a data from the given - * hash table. - * - * @param hash The given hash table. - * @param key The key. - * @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 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 functions 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. - * - * @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. - */ EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, const void *key, const void *data) { @@ -1434,23 +1014,6 @@ eina_hash_del(Eina_Hash *hash, const void *key, const void *data) return _eina_hash_del_by_key(hash, key, data); } -/** - * @brief Retrieve a specific entry in the given hash table. - * - * @param hash The given hash table. - * @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. - * - * 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 - * @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. - */ EAPI void * eina_hash_find_by_hash(const Eina_Hash *hash, const void *key, @@ -1478,19 +1041,6 @@ eina_hash_find_by_hash(const Eina_Hash *hash, return NULL; } -/** - * @brief Retrieve a specific entry in the given hash table. - * - * @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 - * 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. - */ EAPI void * eina_hash_find(const Eina_Hash *hash, const void *key) { @@ -1510,21 +1060,6 @@ eina_hash_find(const Eina_Hash *hash, const void *key) return eina_hash_find_by_hash(hash, key, key_length, hash_num); } -/** - * @brief Modify the entry pointer at the specified key and returns - * the old 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. - */ EAPI void * eina_hash_modify_by_hash(Eina_Hash *hash, const void *key, @@ -1556,22 +1091,6 @@ eina_hash_modify_by_hash(Eina_Hash *hash, return old_data; } -/** - * @brief Modify the entry pointer at the specified key and return the - * old entry or add 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 - * otherwise. - * - * This function modifies the data of @p key with @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. To check for errors, use - * eina_error_get(). - */ EAPI void * eina_hash_set(Eina_Hash *hash, const void *key, const void *data) { @@ -1612,19 +1131,6 @@ eina_hash_set(Eina_Hash *hash, const void *key, const void *data) data); return NULL; } -/** - * @brief Modify the entry pointer at the specified key and return the old - * 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. - * - * 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. - */ EAPI void * eina_hash_modify(Eina_Hash *hash, const void *key, const void *data) { @@ -1643,19 +1149,6 @@ eina_hash_modify(Eina_Hash *hash, const void *key, const void *data) return eina_hash_modify_by_hash(hash, key, key_length, hash_num, data); } -/** - * @brief Change the key associated with a data 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 - * @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, - * but does not call the Eina_Free_Cb associated with the hash table - * when destroying the old key. - */ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, const void *old_key, const void *new_key) { @@ -1688,41 +1181,6 @@ error: * Iterator * *============================================================================*/ -/** - * @brief Call 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 - * - * 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 1. @b If the hash table contents are - * modified by this function or the function wishes to stop processing it must - * return 0, otherwise return 1 to keep processing. - * - * Example: - * @code - * extern Eina_Hash *hash; - * - * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key, - * void *data, void *fdata) - * { - * printf("Func data: %s, Hash entry: %s / %p\n", - * fdata, (const char *)key, data); - * return 1; - * } - * - * int main(int argc, char **argv) - * { - * char *hash_fn_data; - * - * hash_fn_data = strdup("Hello World"); - * eina_hash_foreach(hash, hash_fn, hash_fn_data); - * free(hash_fn_data); - * } - * @endcode - */ EAPI void eina_hash_foreach(const Eina_Hash *hash, Eina_Hash_Foreach func, @@ -1746,25 +1204,6 @@ eina_hash_foreach(const Eina_Hash *hash, eina_iterator_free(it); } -/** - * @brief Returned a new iterator associated to hash data. - * - * @param hash The hash. - * @return A new iterator. - * - * This function returns a newly allocated iterator associated to - * @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 and - * #EINA_ERROR_OUT_OF_MEMORY is set. 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. - */ EAPI Eina_Iterator * eina_hash_iterator_data_new(const Eina_Hash *hash) { @@ -1796,25 +1235,6 @@ eina_hash_iterator_data_new(const Eina_Hash *hash) return &it->iterator; } -/** - * @brief Returned a new iterator associated to hash keys. - * - * @param hash The hash. - * @return A new iterator. - * - * This function returns a newly allocated iterator associated to @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 and - * #EINA_ERROR_OUT_OF_MEMORY is set. 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! - */ EAPI Eina_Iterator * eina_hash_iterator_key_new(const Eina_Hash *hash) { @@ -1847,28 +1267,6 @@ eina_hash_iterator_key_new(const Eina_Hash *hash) return &it->iterator; } -/** - * @brief Returned a new iterator associated to hash keys and data. - * - * @param hash The hash. - * @return A new iterator. - * - * This function returns a newly allocated iterator associated to @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 and - * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is - * returned. - * - * @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! - */ EAPI Eina_Iterator * eina_hash_iterator_tuple_new(const Eina_Hash *hash) { @@ -1956,8 +1354,3 @@ eina_hash_superfast(const char *key, int len) return hash; } - -/** - * @} - * @} - */