aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eina/eina_hash.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/eina/eina_hash.h')
-rw-r--r--src/lib/eina/eina_hash.h1390
1 files changed, 654 insertions, 736 deletions
diff --git a/src/lib/eina/eina_hash.h b/src/lib/eina/eina_hash.h
index 4681a47164..3e256a5b64 100644
--- a/src/lib/eina/eina_hash.h
+++ b/src/lib/eina/eina_hash.h
@@ -2,14 +2,14 @@
* Copyright (C) 2002-2008 Carsten Haitzler, Gustavo Sverzut Barbieri,
* Vincent Torri, Jorge Luis Zapata Muga, Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -24,152 +24,21 @@
#include "eina_iterator.h"
/**
- * @page hash_01_example_page Eina_Hash in action
- * @dontinclude eina_hash_01.c
- *
- * We are going to store some tuples into our table, that will map each @a name
- * to a @a number. The cost to access a given number from the name should be
- * very small, even with many entries in our table. This is the initial data:
- * @skip _Phone_Entry
- * @until // _start_entries
- *
- * Before starting to play with the hash, let's write a callback that will be
- * used to free the elements from it. Since we are just storing strduped
- * strings, we just need to free them:
- *
- * @skip static
- * @until }
- *
- * We also need a callback to iterate over the elements of the list later, so
- * we are defining it now:
- *
- * @skip Eina_Bool
- * @until }
- *
- * Now let's create our @ref Eina_Hash using @ref
- * eina_hash_string_superfast_new :
- *
- * @skip eina_init
- * @until phone_book
- *
- * Now we add the keys and data to the hash using @ref eina_hash_add . This
- * means that the key is copied inside the table, together with the pointer to
- * the data (phone numbers).
- *
- * @skip for
- * @until }
- *
- * Some basic manipulations with the hash, like finding a value given a key,
- * deleting an entry, modifying an entry are exemplified in the following lines.
- * Notice that the @ref eina_hash_modify function returns the old value stored
- * in that entry, and it needs to be freed, while the @ref eina_hash_del
- * function already calls our free callback:
- *
- * @skip Look for
- * @until free(
- *
- * The @ref eina_hash_set function can be used to set a key-value entry to the
- * table if it doesn't exist, or to modify an existent entry. It returns the old
- * entry if it was already set, and NULL otherwise. But since it will
- * return NULL on error too, we need to check if an error has occurred:
- *
- * @skip Modify
- * @until printf("\n");
- *
- * There are different ways of iterate over the entries of a hash. Here we show
- * two of them: using @ref eina_hash_foreach and @ref Eina_Iterator .
- *
- * @skip List of phones
- * @until eina_iterator_free(it);
- *
- * It's also possible to change the key for a specific entry, without having to
- * remove the entry from the table and adding it again:
- *
- * @skipline eina_hash_move
- *
- * We can remove all the elements from the table without free the table itself:
- *
- * @skip Empty the phone book
- * @until eina_hash_population
- *
- * Or free the the entire table with its content:
- *
- * @skipline eina_hash_free
- *
- *
- * The full code for this example can be seen here: @ref eina_hash_01_c
- */
-
-/**
- * @page eina_hash_01_c Hash table in action
- *
- * @include eina_hash_01.c
- * @example eina_hash_01.c
- */
-
-/**
- * @page hash_02_example_page Different types of tables
- *
- * This example shows two more types of hash tables that can be created using
- * @ref Eina_Hash . For more types, consult the reference documentation of @ref
- * eina_hash_new.
- * @include eina_hash_02.c
- * @example eina_hash_02.c
- */
-
-/**
- * @example eina_hash_03.c
- * Same example as @ref hash_01_example_page but using a "string small" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_04.c
- * Same example as @ref hash_01_example_page but using a "string djb2" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_05.c
- * Same example as @ref hash_01_example_page but using a "int32" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_06.c
- * Same example as @ref hash_01_example_page but using a "int64" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_07.c
- * Same example as @ref hash_01_example_page but using a "pointer" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_08.c
- * This example shows the the usage of eina_hash_add(), eina_hash_add_by_hash(),
- * eina_hash_direct_add_by_hash(), eina_hash_del(), eina_hash_del_by_key_hash(),
- * eina_hash_del_by_key(), eina_hash_del_by_data(), eina_hash_find_by_hash() and
- * eina_hash_modify_by_hash().
- */
-
-/**
- * @addtogroup Eina_Hash_Group Hash Table
+ * @defgroup Eina_Hash_Group Hash Table
+ * @ingroup Eina_Containers_Group
*
- * @brief Hash table management. Useful for mapping keys to values.
+ * @brief Performs hash table management. It is useful for mapping keys to values.
*
- * The hash table is useful for when one wants to implement a table that maps
+ * The hash table is useful 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.
*
- * Different implementations exists depending on what kind of key will be used
- * to access the data: strings, integers, pointers, stringshared or your own.
+ * Different implementations exist depending on what kind of key is used
+ * to access the data: strings, integers, pointers, stringshared, or your own key.
*
- * Eina hash tables can copy the keys when using eina_hash_add() or not when
+ * Eina hash tables can copy keys by using eina_hash_add() or not copy by
* using eina_hash_direct_add().
*
* @section hashtable_algo Algorithm
@@ -178,46 +47,44 @@
* 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
+ * (argument of @ref eina_hash_new too). The following picture ilustrates the
* basic idea:
*
- * @htmlonly
- * <img src="01_hash-table.png" width="500" />
- * @endhtmlonly
+ * @image html 01_hash-table.png
* @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);
- * @li calculate the array position [hash mod N];
- * @li add the element to the rbtree on that position.
+ * Adding an element to the hash table consists of:
+ * @li Calculating the hash for that key (using the specified hash function);
+ * @li Calculating the array position [hash mod N];
+ * @li Adding the element to the rbtree at 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
+ * The first two steps have constant time, proportional to the hash function
+ * being used. Adding the key to the rbtree is proportional to the number
* of keys on 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
+ * bucket (load factor) of the table, if the distribution of the 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
- * increasing the buckets_power_size will also increase the memory consumption.
+ * the load factor as small as possible improves the hash table performance. But
+ * increasing the buckets_power_size also increases 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
- * (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
+ * (less than 30) are added to the hash table, @ref
+ * eina_hash_string_small_new should be used, since it reduces the memory
* consumption for the buckets, and you still won't have 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
+ * function that @ref eina_hash_string_superfast_new uses, which is more complex than
* @ref eina_hash_string_djb2_new. The latter has a faster hash computation
- * function, but that will imply on a not so good distribution. But if just a
- * few keys are being added, this is not a problem, it will still have not many
- * collisions and be faster to calculate the hash than in a hash created with
+ * function, but that implies to a not so good distribution. But if just a
+ * few keys are being added, this is not a problem, it still does not have many
+ * collisions and is faster in calculating the hash than when a hash is created with
* @ref eina_hash_string_small_new and @ref eina_hash_string_superfast_new.
*
* A simple comparison between them would be:
@@ -226,64 +93,30 @@
* @li @c string_small - slower hash function but less collisions - 32 buckets
* (lower memory consumption)
* @li @c string_superfast - slower hash function but less collisions - 256 buckets
- * (higher memory consumption) - not randomized, avoid it on public remote interface.
+ * (higher memory consumption)
*
* Basically for a very small number of keys (10 or less), @c djb2 should be
* used, or @c string_small if you have a restriction on memory usage. And for a
- * higher number of keys, @c string_superfast should be preferred if not used on a
- * public remote interface.
+ * higher number of keys, @c string_superfast should always be preferred.
*
* If just stringshared keys are being added, use @ref
- * eina_hash_stringshared_new. If a lot of keys will be added to the hash table
+ * eina_hash_stringshared_new. If a lot of keys are added to the hash table
* (e.g. more than 1000), then it's better to increase the buckets_power_size.
* See @ref eina_hash_new for more details.
*
* 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
+ * eina_hash_direct_add (the latter is 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
- * eina_hash_set (this will change the data pointed by this key if it was
+ * eina_hash_set (this changes the data pointed by this key if it is
* already present in the table).
*
- * @section hashtable_tutorial Tutorial
- *
- * These examples show many Eina_Hash functions in action:
- * <ul>
- * <li> @ref hash_01_example_page
- * <li> @ref hash_02_example_page
- * <li> Different types of hash in use:
- * <ul>
- * <li> @ref eina_hash_03.c "string small"
- * <li> @ref eina_hash_04.c "string djb2"
- * <li> @ref eina_hash_05.c "int32"
- * <li> @ref eina_hash_06.c "int64"
- * <li> @ref eina_hash_07.c "pointer"
- * </ul>
- * <li> @ref eina_hash_08.c "Different add and delete functions"
- * </ul>
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Hash_Group Hash Table
- *
* @{
*/
/**
* @typedef Eina_Hash
- * Type for a generic hash table.
+ * @brief The structure type for a generic hash table.
*/
typedef struct _Eina_Hash Eina_Hash;
@@ -309,10 +142,9 @@ struct _Eina_Hash_Tuple
* Type for a function to determine the length of a hash key.
*/
typedef unsigned int (*Eina_Key_Length)(const void *key);
-
/**
* @def EINA_KEY_LENGTH
- * @param Function The function used to calculate length of hash key.
+ * @param Function The function used to calculate the length of the hash key
*/
#define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
@@ -323,7 +155,7 @@ typedef unsigned int (*Eina_Key_Length)(const void *key);
typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
/**
* @def EINA_KEY_CMP
- * @param Function The function used to compare hash key.
+ * @param Function The function used to compare the hash key
*/
#define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function)
@@ -334,7 +166,7 @@ typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const vo
typedef int (*Eina_Key_Hash)(const void *key, int key_length);
/**
* @def EINA_KEY_HASH
- * @param Function The function used to hash key.
+ * @param Function The function used to hash the key.
*/
#define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function)
@@ -346,33 +178,36 @@ typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key
/**
- * @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 on each value when the hash table is
- * freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @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.
- * 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
- * @p buckets_power_size of 8, there will be 256 buckets.
- *
- * 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().
+ * @brief Creates a new hash table.
+ *
+ * @details 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 @a key_cmp_cb or @a key_hash_cb
+ * are @c NULL, @c NULL is returned. If @a buckets_power_size is
+ * smaller than or equal to 2, or if it is greater than or equal to 17,
+ * @c NULL is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The number of buckets created are 2 ^ @a buckets_power_size. This means
+ * that if @a buckets_power_size is 5, it creates 32 buckets. For a
+ * @a buckets_power_size of 8, it creates 256 buckets.
+ *
+ * @remarks 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().
+ *
+ * @param[in] key_length_cb The function called when getting the size of the key
+ * @param[in] key_cmp_cb The function called when comparing the keys
+ * @param[in] key_hash_cb The function called when getting the values
+ * @param[in] data_free_cb The function called on each value when the hash table is
+ * freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @param[in] buckets_power_size The size of the buckets
+ * @return The new hash table
+ *
*/
EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
Eina_Key_Cmp key_cmp_cb,
@@ -381,124 +216,133 @@ 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 Redefine the callback that clean the data of a hash
+ * @brief Redefines the callback that cleans the data of a hash.
*
- * @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.
+ * @since 1.1
*
- * The argument received by @p data_free_cb will be that data of the item being
- * removed.
+ * @since_tizen 2.3
*
- * @since 1.1
- * @see eina_hash_new.
+ * @remarks The argument received by @a data_free_cb is the data of the item being
+ * removed.
+ *
+ * @param[in] hash The given hash table
+ * @param[in] data_free_cb The function called on each value when the hash
+ * table is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as
+ * callback to remove an existing callback.
+ *
+ * @see eina_hash_new
*/
EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1);
/**
- * @brief Create a new hash table using the djb2 algorithm.
+ * @brief Creates a new hash table using the djb2 algorithm.
*
- * @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.
+ * @details 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
+ * is used to add values. On failure, this function returns @c NULL.
*
- * 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.
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ *
+ * @return The new hash table
*/
EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Create a new hash table for use with strings.
+ * @brief Creates a new hash table for use with strings.
*
- * @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.
+ * @details 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 is used to add values. On failure, this function returns
+ * @c NULL.
*
- * 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.
+ * @since_tizen 2.3
*
- * 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.
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
*/
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 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.
- *
- * 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.
+ * @brief Creates a new hash table for use with strings having a small bucket size.
+ *
+ * @details 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 minimizes the memory used by the returned hash
+ * table. Values can then be looked up with pointers other than the
+ * original key pointer that is used to add values. On failure, this
+ * function returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
*/
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 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.
- *
- * 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.
+ * @brief Creates a new hash table for use with 32 bit integers.
+ *
+ * @details This function creates a new hash table where keys are 32 bit integers.
+ * When adding or looking up in the hash table, pointers to 32 bit integers
+ * must be passed. They can be addresses on the stack if you let
+ * eina_hash copy the key. Values can then
+ * be looked up with pointers other than the original key pointer that is
+ * 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.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
+ *
*/
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 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.
- *
- * 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.
+ * @brief Creates a new hash table for use with 64 bit integers.
+ *
+ * @details This function creates a new hash table where keys are 64 bit integers.
+ * When adding or looking up in the hash table, pointers to 64 bit 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 is
+ * 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.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
+ *
*/
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 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.
+ * @brief Creates a new hash table for use with pointers.
*
- * 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.
+ * @details 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 is 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.
*
* @code
* // For a hash that will have only one pointer to each structure
@@ -508,23 +352,28 @@ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
* if (!eina_hash_find(hash, &data))
* eina_hash_add(hash, &data, data);
* @endcode
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
+ *
*/
EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Create a new hash table optimized for stringshared values.
+ * @brief Creates a new hash table optimized for stringshared 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
- * callback.
- * @return The new hash table.
+ * @details 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 is used to add a value. On failure,
+ * this function returns @c NULL.
*
- * 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.
+ * @since_tizen 2.3
*
- * Excerpt of code that will NOT work with this type of hash:
+ * An Excerpt of a code that does NOT work with this type of hash:
*
* @code
* extern Eina_Hash *hash;
@@ -532,173 +381,208 @@ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
* const char *a = eina_stringshare_add("key");
*
* eina_hash_add(hash, a, value);
- * eina_hash_find(hash, "key");
+ * eina_hash_find(hash, "key")
* @endcode
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
+ *
*/
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. 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.
- * @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
- * 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.
+ * @brief Adds an entry to the given hash table.
+ *
+ * @details This function adds @a key to @a hash. @a key is
+ * expected to be unique within the hash table. The key's uniqueness varies
+ * depending on the type of @a hash: a stringshared @ref Eina_Hash
+ * needs 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
+ * results in unexpected results when inserting data pointers accessed
+ * by eina_hash_find() and removed by eina_hash_del().
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks 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 @c EINA_FALSE if an error
+ * occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key A unique key \n
+ * It cannot be @c NULL.
+ * @param[in] data The data to associate with the string given by @a key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
+ *
*/
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. 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
- * @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
- * 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.
+ * @brief Adds an entry to the given hash table without duplicating the string
+ * key.
+ *
+ * @details This function adds @a key to @a hash. @a key is
+ * expected to be unique within the hash table. The key's uniqueness varies
+ * depending on the type of @a hash: a stringshared @ref Eina_Hash
+ * needs 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
+ * results in unexpected results when inserting data pointers accessed
+ * by eina_hash_find() and removed by eina_hash_del().
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function does not make a copy of @a key, so it must be a string
+ * constant or should be 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 @c EINA_FALSE if an error
+ * occurs, otherwise @c EINA_TRUE.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key A unique key \n
+ * It cannot be @c NULL.
+ * @param[in] data The data to associate with the string given by @a key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, ptherwise @c EINA_TRUE
+ *
*/
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.
+ * @brief Removes the entry identified by a key or data from the given
+ * hash table.
+ *
+ * @details This function removes the entry identified by @a key or @a data
+ * from @a hash. If a free function is given to the
+ * callback on creation, it is called for the data being
+ * deleted. If @a hash is @c NULL, the functions returns @c EINA_FALSE immediately.
+ * If @a key is @c NULL, then @a data is used to find the
+ * match to remove, otherwise @a key is used and @a data is not
+ * required and can be @c NULL. This function returns @c EINA_FALSE if
+ * an error occurs, otherwise it returns EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks 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.
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key
+ * @param[in] data The data pointer to remove if the key is @c NULL
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
+ *
*/
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.
+ * @brief Finds 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.
+ * @details This function retrieves the entry associated to @a key in
+ * @a hash. If @a hash is @c NULL, this function returns
+ * @c NULL immediately. This function returns the data pointer on success,
+ * otherwise it returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key of the entry to find
+ * @return The data pointer for the stored entry on success, otherwise @c NULL
*
- * 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(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.
+ * @brief Modifies the entry pointer at the specified key and returns the old
+ * entry.
+ *
+ * @details This function modifies the data of @a key with @a data in @a
+ * hash. If no entry is found, nothing is added to @a hash. On success
+ * this function returns the old entry, otherwise it returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key of the entry to modify
+ * @param[in] data The data used to replace the old entry
+ * @return The data pointer for the old stored entry on success,
+ * otherwise @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.
+ * @brief Modifies the entry pointer at the specified key and returns the
+ * old entry or adds the entry if not found.
+ *
+ * @details This function modifies the data of @a key with @a data in @a
+ * hash. If no entry is found, @a data is added to @a hash with the
+ * key @a key. On success, this function returns the old entry,
+ * otherwise it returns @c NULL. To check for errors, use
+ * eina_error_get().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key of the entry to modify
+ * @param[in] data The data used to replace the old entry
+ * @return The data pointer for the old stored entry on success,
+ * otherwise @c NULL
*/
EAPI void *eina_hash_set(Eina_Hash *hash,
const void *key,
const void *data) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Change the key associated with a data without triggering the
- * free callback.
+ * @brief Changes the key associated with the 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.
+ * @details 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.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] old_key The current key associated with the data
+ * @param[in] new_key The new key to associate the data with
+ * @return @c EINA_FALSE in any case but success, otherwise @c 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.
+ * @brief Frees the given hash table resources.
*
- * @param hash The hash table to be freed.
+ * @details This function frees up all the memory allocated to storing @a 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
+ * pointers for data in the table stored elsewhere as well. If @a hash
+ * is @c NULL, the function returns immediately.
*
- * 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.
+ * @since_tizen 2.3
*
* Example:
* @code
@@ -707,55 +591,70 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
* eina_hash_free(hash);
* hash = NULL;
* @endcode
+ *
+ * @param[in] hash The hash table to be freed
+ *
*/
EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
/**
- * Free the given hash table buckets resources.
+ * @brief Frees the given hash table buckets resources.
+ *
+ * @details This function frees up all the memory allocated to storing the
+ * buckets of @a hash, and calls the free callback on all hash table
+ * buckets if it has been passed to the hash table at creation time,
+ * it then frees the buckets. If no free callback has been passed, no
+ * buckets value are freed. If @a hash is @c NULL, the function
+ * returns immediately.
+ *
+ * @since_tizen 2.3
*
- * @param hash The hash table whose buckets have to be freed.
+ * @param[in] 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.
+ * @details This function returns the number of entries in @a hash, or @c 0 on
+ * error. If @a hash is @c NULL, @c 0 is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] 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.
*/
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. 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 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.
+ * @brief Adds an entry to the given hash table.
+ *
+ * @details This function adds @a key to @a hash. @a hash, @a key, and @a data
+ * cannot be @c NULL, in that case @c EINA_FALSE is returned. @a key is
+ * expected to be unique within the hash table. Otherwise,
+ * one cannot be sure which inserted data pointer is accessed
+ * by @ref eina_hash_find, and removed by @ref eina_hash_del. Do
+ * not forget to count '\\0' for string when setting the value of
+ * @a key_length. @a key_hash is expected to always match
+ * @a 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 @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key A unique key \n
+ * It cannot be @c NULL.
+ * @param[in] key_length The length of the key
+ * @param[in] key_hash The hash that always matches the key
+ * @param[in] data The data to associate with the string given by the key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
*
* @see eina_hash_add()
*/
@@ -766,30 +665,36 @@ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *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. 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
- * 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.
+ * @brief Adds an entry to the given hash table and does not duplicate the string
+ * key.
+ *
+ * @details This function adds @a key to @a hash. @a hash, @a key, and @a data
+ * can be @c NULL, in that case @c EINA_FALSE is returned. @a key is
+ * expected to be unique within the hash table. Otherwise,
+ * one cannot be sure which inserted data pointer is going to be accessed
+ * by @ref eina_hash_find, and removed by @ref eina_hash_del. This
+ * function does not make a copy of @a key so it must be a string
+ * constant or should be stored elsewhere (in the object being added). Do
+ * not forget to count '\\0' for string when setting the value of
+ * @a key_length. @a key_hash is expected to always match
+ * @a 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 @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key A unique key \n
+ * It cannot be @c NULL.
+ * @param[in] key_length The length of @a key (don't forget to count
+ * '\\0' for string).
+ * @param[in] key_hash The hash that always matches the key.
+ * @param[in] data The data to associate with the string given by @a key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
*
* @see eina_hash_direct_add()
*/
@@ -800,25 +705,29 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *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. Cannot be @c NULL.
- * @param key The key. Cannot be @c NULL.
- * @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.
+ * @brief Removes the entry identified by a key and a key hash from the given
+ * hash table.
+ *
+ * @details This function removes the entry identified by @a key and
+ * @a key_hash from @a hash. If a free function is given to the
+ * callback on creation, it is called for the data being
+ * deleted. Do not forget to count '\\0' for string when setting the
+ * value of @a key_length. If @a hash or @a key is @c NULL, the
+ * functions return @c EINA_FALSE immediately. This function
+ * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you don't have the key_hash, use eina_hash_del_by_key() instead.
+ * @remarks If you don't have the key, use eina_hash_del_by_data() instead.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key The key \n
+ * It cannot be @c NULL.
+ * @param[in] key_length The length of the key
+ * @param[in] key_hash The hash that always matches the key
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
*/
EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
const void *key,
@@ -826,81 +735,92 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
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. 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 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.
+ * @brief Removes the entry identified by a key from the given hash table.
+ *
+ * @details This function removes the entry identified by @a key from @a
+ * hash. The key length and hash is calculated automatically by
+ * using functions provided to the hash creation function. If a free
+ * function is given to the callback on creation, it is called
+ * for the data being deleted. If @a hash or @a key is @c NULL, the
+ * functions return @c EINA_FALSE immediately. This function
+ * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you already have the key_hash, use eina_hash_del_by_key_hash()
+ * instead.
+ * @remarks If you don't have the key, use eina_hash_del_by_data() instead.
+ *
+ * @remarks This version calculates the key length and hash by using functions
+ * provided to the hash creation function.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key The key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
+ *
*/
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.
+ * @brief Removes the entry identified by data from the given hash table.
*
- * This version is slow since there is no quick access to nodes based on data.
+ * @details This function removes the entry identified by @a data from @a
+ * hash. If a free function is given to the callback on creation, it
+ * is called for the data being deleted. If @a hash or @a data
+ * is @c NULL, the functions return @c EINA_FALSE immediately. This
+ * function returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
*
- * @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.
- * thing goes fine.
+ * @since_tizen 2.3
*
- * 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.
+ * @remarks If you already have the key, use eina_hash_del_by_key() or
+ * eina_hash_del_by_key_hash() instead.
*
- * @note if you already have the key, use eina_hash_del_by_key() or
- * eina_hash_del_by_key_hash() instead.
+ * @remarks This version is slow since there is no quick access to nodes based on the data.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] data The data value to search and remove \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE on success
*/
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. Cannot be @c NULL.
- * @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_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.
- *
- * @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.
+ * @brief Removes the entry identified by a key and a key hash or the
+ * data from the given hash table.
+ *
+ * @details This function removes the entry identified by @a key and
+ * @a key_hash, or @a data, from @a hash. If a free function is given to
+ * the callback on creation, it is called for the data being
+ * deleted. If @a hash is @c NULL, the functions return @c EINA_FALSE immediately.
+ * If @a key is @c NULL, then @a key_length and @a key_hash
+ * are ignored and @a data is used to find a match to remove,
+ * otherwise @a key and @a key_hash are used and @a data is not
+ * required and can be @c NULL. Do not forget to count '\\0' for
+ * string when setting the value of @a key_length. This function
+ * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks 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.
+ *
+ * @remarks If @a key is @c NULL, then @a data is used to find a match to
+ * remove.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key The key
+ * @param[in] key_length The length of the key
+ * @param[in] key_hash The hash that always matches the key
+ * @param[in] data The data pointer to remove if the key is @c NULL
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
+ *
*/
EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
const void *key,
@@ -909,21 +829,24 @@ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieve a specific entry in 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.
- *
- * 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.
+ * @brief Retrieves a specific entry in the given hash table.
+ *
+ * @details This function retrieves the entry associated to @a key of length
+ * @a key_length in @a hash. @a key_hash is the hash that always matches
+ * @a key. It is ignored if @a key is @c NULL. Do not forget to count
+ * '\\0' for string when setting the value of @a key_length. If
+ * @a hash is @c NULL, this function returns @c NULL immediately. This
+ * function returns the data pointer on success, otherwise it returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key The key of the entry to find
+ * @param[in] key_length The length of the key
+ * @param[in] key_hash The hash that always matches the key
+ * @return The data pointer for the stored entry on success,
+ * otherwise @c NULL
*/
EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
const void *key,
@@ -931,19 +854,22 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
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.
+ * @brief Modifies the entry pointer at the specified key and returns
+ * the old entry.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key of the entry to modify
+ * @param[in] key_length The length of @a key (don't forget to count
+ * '\\0' for string)
+ * @param[in] key_hash The hash that always matches the key \n
+ * It is ignored if @a key is @c NULL.
+ * @param[in] data The data to replace the old entry, if it exists
+ * @return The data pointer for the old stored entry, otherwise @c NULL if not
+ * found \n
+ * 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,
@@ -952,80 +878,90 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5);
/**
- * @brief Returned a new iterator associated to hash keys.
+ * @brief Returns a new iterator associated to hash keys.
+ *
+ * @details This function returns a newly allocated iterator associated to @a
+ * hash. If @a hash is not populated, this function still returns a
+ * valid iterator that always returns @c false on a call to
+ * eina_iterator_next(), thus keeping the API sane.
*
- * @param hash The hash.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * 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.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * If the memory can not be allocated, NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the hash structure changes, the iterator becomes
+ * invalid. That is, if you add or remove items this iterator's
+ * behavior is undefined and your program may crash.
+ *
+ * @param[in] hash The hash
+ * @return A new iterator
*
- * @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.
+ * @brief Returns a new iterator associated to hash data.
+ *
+ * @details This function returns a newly allocated iterator associated to
+ * @a hash. If @a hash is not populated, this function still returns a
+ * valid iterator that always returns @c false on a call to
+ * eina_iterator_next(), thus keeping the API sane.
*
- * @param hash The hash.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * 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.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the hash structure changes then the iterator becomes
+ * invalid. That is, if you add or remove items this iterator's behavior
+ * is undefined and your program may crash.
+ *
+ * @param[in] hash The hash
+ * @return A new iterator
*
- * @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.
+ * @brief Returns a new iterator associated to hash keys and data.
+ *
+ * @details This function returns a newly allocated iterator associated to @a
+ * hash. If @a hash is not populated, this function still returns a
+ * valid iterator that always returns @c false on a call to
+ * eina_iterator_next(), thus keeping the API sane.
+ *
+ * @since_tizen 2.3
*
- * @param hash The hash.
- * @return A new iterator.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * 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.
+ * @remarks The iterator data provides values as Eina_Hash_Tuple that should not
+ * be modified.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the hash structure changes then the iterator becomes
+ * invalid. That is, if you add or remove items this iterator's
+ * behavior is undefined and your program may crash.
*
- * @note iterator data will provide values as Eina_Hash_Tuple that should not
- * be modified!
+ * @param[in] hash The hash
+ * @return A new iterator
*
- * @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
+ * @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
+ * @details This function goes through every entry in the hash table @a hash and calls
+ * the function @a 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, it must
+ * return @c 0, otherwise it must return @c 1 to keep processing.
*
- * 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.
+ * @since_tizen 2.3
*
* Example:
* @code
@@ -1048,125 +984,107 @@ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MAL
* free(hash_fn_data);
* }
* @endcode
+ *
+ * @param[in] hash The hash table whose members are walked
+ * @param[in] func The function to call on each parameter
+ * @param[in] fdata The data pointer to pass to the function being called
*/
EAPI void eina_hash_foreach(const Eina_Hash *hash,
Eina_Hash_Foreach func,
const void *fdata) EINA_ARG_NONNULL(1, 2);
-
-
/**
- * @brief Append data to an #Eina_List inside a 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
- * @since 1.10
- */
-EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
-/**
- * @brief Append data to an #Eina_List inside a 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
- * @since 1.10
- */
-EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
-/**
- * @brief Append data to an #Eina_List inside a 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
- * @since 1.10
- */
-EAPI void eina_hash_list_remove(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
-
-/**
- * @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
+ * @brief Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash
+ * function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/)
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] key The key to hash
+ * @param[in] len The length of the key
* @return The hash value
*/
EAPI int eina_hash_superfast(const char *key,
int len) EINA_ARG_NONNULL(1);
-/**
- * @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
+/**
+ * @details The djb2 hash function
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks djb2 hash algorithm was first reported by dan bernstein, and was
+ * the old default hash function for evas.
+ *
+ * @remarks This hash function first reported by dan bernstein many years ago
+ * in comp.lang.c
+ *
+ * @param[in] key The key to hash
+ * @param[in] 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);
-/**
- * @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
+
+/**
+ * @details The djb2 hash function withoug length
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks djb2 hash algorithm was first reported by dan bernstein, and was
+ * the old default hash function for evas.
+ *
+ * @remarks This hash function first reported by dan bernstein many years ago
+ * in comp.lang.c
+ *
+ * @param[in] key The key to hash
+ * @param[out] plen The length of the key to be returned
* @return The hash value
*/
static inline int eina_hash_djb2_len(const char *key,
int *plen) EINA_ARG_NONNULL(1, 2);
-/**
- * @brief
- * Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm
- *
- * @param pkey The key to hash
- * @param len The length of the key
+/**
+ * @details The 32 bit integer hash function
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Hash function from
+ * http://www.concentric.net/~Ttwang/tech/inthash.htm
+ *
+ * @param[in] pkey The key to hash
+ * @param[in] 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);
-/**
- * @brief
- * Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm
- *
- * @param pkey The key to hash
- * @param len The length of the key
+
+/**
+ * @details The 64 bit integer hash function
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] pkey The key to hash
+ * @param[in] len The length of the key
* @return The hash value
*/
-static inline int eina_hash_int64(const unsigned long long int *pkey,
+static inline int eina_hash_int64(const unsigned long int *pkey,
int len) EINA_ARG_NONNULL(1);
-/**
- * @brief
- * Hash function from http://sites.google.com/site/murmurhash/
- *
- * @param key The key to hash
- * @param len The length of the key
+/**
+ * @details The murmur3 hash function
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks http://sites.google.com/site/murmurhash/
+ *
+ * @param[in] key The key to hash
+ * @param[in] 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);
-
#include "eina_inline_hash.x"
/**
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif /*EINA_HASH_H_*/