src/include/eina_hash.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2002-2008 Carsten Haitzler, Gustavo Sverzut Barbieri,
   3  *                         Vincent Torri, Jorge Luis Zapata Muga, Cedric Bail
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library;
  17  * if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef EINA_HASH_H_
  21 #define EINA_HASH_H_
  22
  23 #include "eina_types.h"
  24 #include "eina_iterator.h"
  25
  26 /**
  27  * @page hash_01_example_page Eina_Hash in action
  28  * @dontinclude eina_hash_01.c
  29  *
  30  * We are going to store some tuples into our table, that will map each @a name
  31  * to a @a number. The cost to access a given number from the name should be
  32  * very small, even with many entries in our table. This is the initial data:
  33  * @skip _Phone_Entry
  34  * @until // _start_entries
  35  *
  36  * Before starting to play with the hash, let's write a callback that will be
  37  * used to free the elements from it. Since we are just storing strduped
  38  * strings, we just need to free them:
  39  *
  40  * @skip static
  41  * @until }
  42  *
  43  * We also need a callback to iterate over the elements of the list later, so
  44  * we are defining it now:
  45  *
  46  * @skip Eina_Bool
  47  * @until }
  48  *
  49  * Now let's create our @ref Eina_Hash using @ref
  50  * eina_hash_string_superfast_new :
  51  *
  52  * @skip eina_init
  53  * @until phone_book
  54  *
  55  * Now we add the keys and data to the hash using @ref eina_hash_add . This
  56  * means that the key is copied inside the table, together with the pointer to
  57  * the data (phone numbers).
  58  *
  59  * @skip for
  60  * @until }
  61  *
  62  * Some basic manipulations with the hash, like finding a value given a key,
  63  * deleting an entry, modifying an entry are exemplified in the following lines.
  64  * Notice that the @ref eina_hash_modify function returns the old value stored
  65  * in that entry, and it needs to be freed, while the @ref eina_hash_del
  66  * function already calls our free callback:
  67  *
  68  * @skip Look for
  69  * @until free(
  70  *
  71  * The @ref eina_hash_set function can be used to set a key-value entry to the
  72  * table if it doesn't exist, or to modify an existent entry. It returns the old
  73  * entry if it was already set, and NULL otherwise. But since it will
  74  * return NULL on error too, we need to check if an error has occurred:
  75  *
  76  * @skip Modify
  77  * @until printf("\n");
  78  *
  79  * There are different ways of iterate over the entries of a hash. Here we show
  80  * two of them: using @ref eina_hash_foreach and @ref Eina_Iterator .
  81  *
  82  * @skip List of phones
  83  * @until eina_iterator_free(it);
  84  *
  85  * It's also possible to change the key for a specific entry, without having to
  86  * remove the entry from the table and adding it again:
  87  *
  88  * @skipline eina_hash_move
  89  *
  90  * We can remove all the elements from the table without free the table itself:
  91  *
  92  * @skip Empty the phone book
  93  * @until eina_hash_population
  94  *
  95  * Or free the the entire table with its content:
  96  *
  97  * @skipline eina_hash_free
  98  *
  99  *
 100  * The full code for this example can be seen here: @ref eina_hash_01_c
 101  */
 102
 103 /**
 104  * @page eina_hash_01_c Hash table in action
 105  *
 106  * @include eina_hash_01.c
 107  * @example eina_hash_01.c
 108  */
 109
 110 /**
 111  * @page hash_02_example_page Different types of tables
 112  *
 113  * This example shows two more types of hash tables that can be created using
 114  * @ref Eina_Hash . For more types, consult the reference documentation of @ref
 115  * eina_hash_new.
 116  * @include eina_hash_02.c
 117  * @example eina_hash_02.c
 118  */
 119
 120 /**
 121  * @example eina_hash_03.c
 122  * Same example as @ref hash_01_example_page but using a "string small" hash
 123  * table instead of "string superfast".
 124  */
 125
 126 /**
 127  * @example eina_hash_04.c
 128  * Same example as @ref hash_01_example_page but using a "string djb2" hash
 129  * table instead of "string superfast".
 130  */
 131
 132 /**
 133  * @example eina_hash_05.c
 134  * Same example as @ref hash_01_example_page but using a "int32" hash
 135  * table instead of "string superfast".
 136  */
 137
 138 /**
 139  * @example eina_hash_06.c
 140  * Same example as @ref hash_01_example_page but using a "int64" hash
 141  * table instead of "string superfast".
 142  */
 143
 144 /**
 145  * @example eina_hash_07.c
 146  * Same example as @ref hash_01_example_page but using a "pointer" hash
 147  * table instead of "string superfast".
 148  */
 149
 150 /**
 151  * @example eina_hash_08.c
 152  * This example shows the the usage of eina_hash_add(), eina_hash_add_by_hash(),
 153  * eina_hash_direct_add_by_hash(), eina_hash_del(), eina_hash_del_by_key_hash(),
 154  * eina_hash_del_by_key(), eina_hash_del_by_data(), eina_hash_find_by_hash() and
 155  * eina_hash_modify_by_hash().
 156  */
 157
 158 /**
 159  * @addtogroup Eina_Hash_Group Hash Table
 160  *
 161  * @brief Hash table management. Useful for mapping keys to values.
 162  *
 163  * The hash table is useful for when one wants to implement a table that maps
 164  * keys (usually strings) to data, and have relatively fast access time. The
 165  * performance is proportional to the load factor of the table (number of
 166  * elements / number of buckets). See @ref hashtable_algo for implementation
 167  * details.
 168  *
 169  * Different implementations exists depending on what kind of key will be used
 170  * to access the data: strings, integers, pointers, stringshared or your own.
 171  *
 172  * Eina hash tables can copy the keys when using eina_hash_add() or not when
 173  * using eina_hash_direct_add().
 174  *
 175  * @section hashtable_algo Algorithm
 176  *
 177  * The Eina_Hash is implemented using an array of N "buckets", where each
 178  * bucket is a pointer to a structure that is the head of a <a
 179  * href="http://en.wikipedia.org/wiki/Red-black_tree">red-black tree</a>. The
 180  * array can then be indexed by the [hash_of_element mod N]. The
 181  * hash_of_element is calculated using the hashing function, passed as
 182  * parameter to the @ref eina_hash_new function. N is the number of buckets
 183  * (array positions), and is calculated based on the buckets_power_size
 184  * (argument of @ref eina_hash_new too). The following picture ilustrates the
 185  * basic idea:
 186  *
 187  * @htmlonly
 188  * <img src="01_hash-table.png" width="500" />
 189  * @endhtmlonly
 190  * @image latex 01_hash-table.eps
 191  *
 192  * Adding an element to the hash table is made of:
 193  * @li calculating the hash for that key (using the specified hash function);
 194  * @li calculate the array position [hash mod N];
 195  * @li add the element to the rbtree on that position.
 196  *
 197  * The two first steps have constant time, proportional to the hash function
 198  * being used. Adding the key to the rbtree will be proportional on the number
 199  * of keys on that bucket.
 200  *
 201  * The average cost of lookup depends on the number of keys per
 202  * bucket (load factor) of the table, if the distribution of keys is
 203  * sufficiently uniform.
 204  *
 205  * @section hashtable_perf Performance
 206  *
 207  * As said before, the performance depends on the load factor. So trying to keep
 208  * the load factor as small as possible will improve the hash table performance. But
 209  * increasing the buckets_power_size will also increase the memory consumption.
 210  * The default hash table creation functions already have a good number of
 211  * buckets, enough for most cases. Particularly for strings, if just a few keys
 212  * (less than 30) will be added to the hash table, @ref
 213  * eina_hash_string_small_new should be used, since it will reduce the memory
 214  * consumption for the buckets, and you still won't have many collisions.
 215  * However, @ref eina_hash_string_small_new still uses the same hash calculation
 216  * function that @ref eina_hash_string_superfast_new, which is more complex than
 217  * @ref eina_hash_string_djb2_new. The latter has a faster hash computation
 218  * function, but that will imply on a not so good distribution. But if just a
 219  * few keys are being added, this is not a problem, it will still have not many
 220  * collisions and be faster to calculate the hash than in a hash created with
 221  * @ref eina_hash_string_small_new and @ref eina_hash_string_superfast_new.
 222  *
 223  * A simple comparison between them would be:
 224  *
 225  * @li @c djb2 - faster hash function - 256 buckets (higher memory consumption)
 226  * @li @c string_small - slower hash function but less collisions - 32 buckets
 227  * (lower memory consumption)
 228  * @li @c string_superfast - slower hash function but less collisions - 256 buckets
 229  * (higher memory consumption)
 230  *
 231  * Basically for a very small number of keys (10 or less), @c djb2 should be
 232  * used, or @c string_small if you have a restriction on memory usage. And for a
 233  * higher number of keys, @c string_superfast should be always preferred.
 234  *
 235  * If just stringshared keys are being added, use @ref
 236  * eina_hash_stringshared_new. If a lot of keys will be added to the hash table
 237  * (e.g. more than 1000), then it's better to increase the buckets_power_size.
 238  * See @ref eina_hash_new for more details.
 239  *
 240  * When adding a new key to a hash table, use @ref eina_hash_add or @ref
 241  * eina_hash_direct_add (the latter if this key is already stored elsewhere). If
 242  * the key may be already inside the hash table, instead of checking with
 243  * @ref eina_hash_find and then doing @ref eina_hash_add, one can use just @ref
 244  * eina_hash_set (this will change the data pointed by this key if it was
 245  * already present in the table).
 246  *
 247  * @section hashtable_tutorial Tutorial
 248  *
 249  * These examples show many Eina_Hash functions in action:
 250  * <ul>
 251  * <li> @ref hash_01_example_page
 252  * <li> @ref hash_02_example_page
 253  * <li> Different types of hash in use:
 254  *      <ul>
 255  *      <li> @ref eina_hash_03.c "string small"
 256  *      <li> @ref eina_hash_04.c "string djb2"
 257  *      <li> @ref eina_hash_05.c "int32"
 258  *      <li> @ref eina_hash_06.c "int64"
 259  *      <li> @ref eina_hash_07.c "pointer"
 260  *      </ul>
 261  * <li> @ref eina_hash_08.c "Different add and delete functions"
 262  * </ul>
 263  */
 264
 265 /**
 266  * @addtogroup Eina_Data_Types_Group Data Types
 267  *
 268  * @{
 269  */
 270
 271 /**
 272  * @addtogroup Eina_Containers_Group Containers
 273  *
 274  * @{
 275  */
 276
 277 /**
 278  * @defgroup Eina_Hash_Group Hash Table
 279  *
 280  * @{
 281  */
 282
 283 /**
 284  * @typedef Eina_Hash
 285  * Type for a generic hash table.
 286  */
 287 typedef struct _Eina_Hash       Eina_Hash;
 288
 289 typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple;
 290
 291 struct _Eina_Hash_Tuple
 292 {
 293    const void  *key; /**< The key */
 294    void        *data; /**< The data associated to the key */
 295    unsigned int key_length; /**< The length of the key */
 296 };
 297
 298 typedef unsigned int (*Eina_Key_Length)(const void *key);
 299 /**
 300  * @def EINA_KEY_LENGTH
 301  * @param Function The function used to calculate length of hash key.
 302  */
 303 #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
 304 typedef int          (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
 305 /**
 306  * @def EINA_KEY_CMP
 307  * @param Function The function used to compare hash key.
 308  */
 309 #define EINA_KEY_CMP(Function)    ((Eina_Key_Cmp)Function)
 310 typedef int          (*Eina_Key_Hash)(const void *key, int key_length);
 311 /**
 312  * @def EINA_KEY_HASH
 313  * @param Function The function used to hash key.
 314  */
 315 #define EINA_KEY_HASH(Function)   ((Eina_Key_Hash)Function)
 316 typedef Eina_Bool    (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata);
 317
 318
 319 /**
 320  * @brief Create a new hash table.
 321  *
 322  * @param key_length_cb The function called when getting the size of the key.
 323  * @param key_cmp_cb The function called when comparing the keys.
 324  * @param key_hash_cb The function called when getting the values.
 325  * @param data_free_cb The function called on each value when the hash table is
 326  * freed, or when an item is deleted from it. @c NULL can be passed as
 327  * callback.
 328  * @param buckets_power_size The size of the buckets.
 329  * @return The new hash table.
 330  *
 331  * This function creates a new hash table using user-defined callbacks
 332  * to manage the hash table. On failure, @c NULL is returned
 333  * and #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb
 334  * are @c NULL, @c NULL is returned. If @p buckets_power_size is
 335  * smaller or equal than 2, or if it is greater or equal than 17,
 336  * @c NULL is returned.
 337  *
 338  * The number of buckets created will be 2 ^ @p buckets_power_size. This means
 339  * that if @p buckets_power_size is 5, there will be created 32 buckets. for a
 340  * @p buckets_power_size of 8, there will be 256 buckets.
 341  *
 342  * Pre-defined functions are available to create a hash table. See
 343  * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(),
 344  * eina_hash_string_small_new(), eina_hash_int32_new(),
 345  * eina_hash_int64_new(), eina_hash_pointer_new() and
 346  * eina_hash_stringshared_new().
 347  */
 348 EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
 349                               Eina_Key_Cmp    key_cmp_cb,
 350                               Eina_Key_Hash   key_hash_cb,
 351                               Eina_Free_Cb    data_free_cb,
 352                               int             buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
 353
 354 /**
 355  * @brief Redefine the callback that clean the data of a hash
 356  *
 357  * @param hash The given hash table
 358  * @param data_free_cb The function called on each value when the hash
 359  * table is freed, or when an item is deleted from it. @c NULL can be passed as
 360  * callback to remove an existing callback.
 361  *
 362  * The argument received by @p data_free_cb will be that data of the item being
 363  * removed.
 364  *
 365  * @since 1.1
 366  * @see eina_hash_new.
 367  */
 368 EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1);
 369
 370 /**
 371  * @brief Create a new hash table using the djb2 algorithm.
 372  *
 373  * @param data_free_cb The function called on each value when the hash table
 374  * is freed, or when an item is deleted from it. @c NULL can be passed as
 375  * callback.
 376  * @return The new hash table.
 377  *
 378  * This function creates a new hash table using the djb2 algorithm for
 379  * table management and strcmp() to compare the keys. Values can then
 380  * be looked up with pointers other than the original key pointer that
 381  * was used to add values. On failure, this function returns @c NULL.
 382  */
 383 EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
 384
 385 /**
 386  * @brief Create a new hash table for use with strings.
 387  *
 388  * @param data_free_cb The function called on each value when the hash table
 389  * is freed, or when an item is deleted from it. @c NULL can be passed as
 390  * callback.
 391  * @return The new hash table.
 392  *
 393  * This function creates a new hash table using the superfast algorithm
 394  * for table management and strcmp() to compare the keys. Values can
 395  * then be looked up with pointers other than the original key pointer
 396  * that was used to add values. On failure, this function returns
 397  * @c NULL.
 398  */
 399 EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
 400
 401 /**
 402  * @brief Create a new hash table for use with strings with small bucket size.
 403  *
 404  * @param data_free_cb  The function called on each value when the hash table
 405  * is freed, or when an item is deleted from it. @c NULL can be passed as
 406  * callback.
 407  * @return  The new hash table.
 408  *
 409  * This function creates a new hash table using the superfast algorithm
 410  * for table management and strcmp() to compare the keys, but with a
 411  * smaller bucket size (compared to eina_hash_string_superfast_new())
 412  * which will minimize the memory used by the returned hash
 413  * table. Values can then be looked up with pointers other than the
 414  * original key pointer that was used to add values. On failure, this
 415  * function returns @c NULL.
 416  */
 417 EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
 418
 419 /**
 420  * @brief Create a new hash table for use with 32bit integers.
 421  *
 422  * @param data_free_cb  The function called on each value when the hash table
 423  * is freed, or when an item is deleted from it. @c NULL can be passed as
 424  * callback.
 425  * @return  The new hash table.
 426  *
 427  * This function creates a new hash table where keys are 32bit integers.
 428  * When adding or looking up in the hash table, pointers to 32bit integers
 429  * must be passed. They can be addresses on the stack if you let the
 430  * eina_hash copy the key. Values can then
 431  * be looked up with pointers other than the original key pointer that was
 432  * used to add values. This method is not suitable to match string keys as
 433  * it would only match the first character.
 434  * On failure, this function returns @c NULL.
 435  */
 436 EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
 437
 438 /**
 439  * @brief Create a new hash table for use with 64bit integers.
 440  *
 441  * @param data_free_cb  The function called on each value when the hash table
 442  * is freed, or when an item is deleted from it. @c NULL can be passed as
 443  * callback.
 444  * @return  The new hash table.
 445  *
 446  * This function creates a new hash table where keys are 64bit integers.
 447  * When adding or looking up in the hash table, pointers to 64bit integers
 448  * must be passed. They can be addresses on the stack. Values can then
 449  * be looked up with pointers other than the original key pointer that was
 450  * used to add values. This method is not suitable to match string keys as
 451  * it would only match the first character.
 452  * On failure, this function returns @c NULL.
 453  */
 454 EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
 455
 456 /**
 457  * @brief Create a new hash table for use with pointers.
 458  *
 459  * @param data_free_cb  The function called on each value when the hash table
 460  * is freed, or when an item is deleted from it. @c NULL can be passed as
 461  * callback.
 462  * @return  The new hash table.
 463  *
 464  * This function creates a new hash table using the int64/int32 algorithm for
 465  * table management and dereferenced pointers to compare the
 466  * keys. Values can then be looked up with pointers other than the
 467  * original key pointer that was used to add values. This method may
 468  * appear to be able to match string keys, actually it only matches
 469  * the first character. On failure, this function returns @c NULL.
 470  */
 471 EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
 472
 473 /**
 474  * @brief Create a new hash table optimized for stringshared values.
 475  *
 476  * @param data_free_cb  The function called on each value when the hash table
 477  * is freed, or when an item is deleted from it. @c NULL can be passed as
 478  * callback.
 479  * @return  The new hash table.
 480  *
 481  * This function creates a new hash table optimized for stringshared
 482  * values. Values CAN NOT be looked up with pointers not
 483  * equal to the original key pointer that was used to add a value. On failure,
 484  * this function returns @c NULL.
 485  *
 486  * Excerpt of code that will NOT work with this type of hash:
 487  *
 488  * @code
 489  * extern Eina_Hash *hash;
 490  * extern const char *value;
 491  * const char *a = eina_stringshare_add("key");
 492  *
 493  * eina_hash_add(hash, a, value);
 494  * eina_hash_find(hash, "key")
 495  * @endcode
 496  */
 497 EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
 498
 499 /**
 500  * @brief Add an entry to the given hash table.
 501  *
 502  * @param hash The given hash table. Cannot be @c NULL.
 503  * @param key A unique key. Cannot be @c NULL.
 504  * @param data Data to associate with the string given by @p key. Cannot be @c
 505  * NULL.
 506  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 507  *
 508  * This function adds @p key to @p hash. @p key is
 509  * expected to be unique within the hash table. Key uniqueness varies
 510  * depending on the type of @p hash: a stringshared @ref Eina_Hash
 511  * need to have unique pointers (which implies unique strings).
 512  * All other string hash types require the strings
 513  * themselves to be unique. Pointer, int32 and int64 hashes need to have these
 514  * values as unique. Failure to use sufficient uniqueness will
 515  * result in unexpected results when inserting data pointers accessed
 516  * with eina_hash_find(), and removed with eina_hash_del(). Key
 517  * strings are case sensitive. If an error occurs, eina_error_get()
 518  * should be used to determine if an allocation error occurred during
 519  * this function. This function returns #EINA_FALSE if an error
 520  * occurred, #EINA_TRUE otherwise.
 521  */
 522 EAPI Eina_Bool  eina_hash_add(Eina_Hash  *hash,
 523                               const void *key,
 524                               const void *data) EINA_ARG_NONNULL(1, 2, 3);
 525
 526 /**
 527  * @brief Add an entry to the given hash table without duplicating the string
 528  * key.
 529  *
 530  * @param hash The given hash table. Cannot be @c NULL.
 531  * @param key A unique key. Cannot be @c NULL.
 532  * @param data Data to associate with the string given by @p key. Cannot be @c
 533  * NULL
 534  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 535  *
 536  * This function adds @p key to @p hash. @p key is
 537  * expected to be unique within the hash table. Key uniqueness varies
 538  * depending on the type of @p hash: a stringshared @ref Eina_Hash
 539  * need have unique pointers (which implies unique strings).
 540  * All other string hash types require the strings
 541  * themselves to be unique. Pointer, int32 and int64 hashes need to have these
 542  * values as unique. Failure to use sufficient uniqueness will
 543  * result in unexpected results when inserting data pointers accessed
 544  * with eina_hash_find(), and removed with eina_hash_del(). This
 545  * function does not make a copy of @p key, so it must be a string
 546  * constant or stored elsewhere ( in the object being added). Key
 547  * strings are case sensitive. If an error occurs, eina_error_get()
 548  * should be used to determine if an allocation error occurred during
 549  * this function. This function returns #EINA_FALSE if an error
 550  * occurred, #EINA_TRUE otherwise.
 551  */
 552 EAPI Eina_Bool eina_hash_direct_add(Eina_Hash  *hash,
 553                                     const void *key,
 554                                     const void *data) EINA_ARG_NONNULL(1, 2, 3);
 555
 556 /**
 557  * @brief Remove the entry identified by a key or a data from the given
 558  * hash table.
 559  *
 560  * @param hash The given hash table.
 561  * @param key  The key.
 562  * @param data The data pointer to remove if the key is @c NULL.
 563  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 564  *
 565  * This function removes the entry identified by @p key or @p data
 566  * from @p hash. If a free function was given to the
 567  * callback on creation, it will be called for the data being
 568  * deleted. If @p hash is @c NULL, the functions returns immediately #EINA_FALSE.
 569  * If @p key is @c NULL, then @p data is used to find the a
 570  * match to remove, otherwise @p key is used and @p data is not
 571  * required and can be @c NULL. This function returns #EINA_FALSE if
 572  * an error occurred, #EINA_TRUE otherwise.
 573  *
 574  * @note if you know you already have the key, use
 575  *       eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
 576  *       know you don't have the key, use eina_hash_del_by_data()
 577  *       directly.
 578  */
 579 EAPI Eina_Bool eina_hash_del(Eina_Hash  *hash,
 580                              const void *key,
 581                              const void *data) EINA_ARG_NONNULL(1);
 582
 583 /**
 584  * @brief Retrieve a specific entry in the given hash table.
 585  *
 586  * @param hash The given hash table.
 587  * @param key The key of the entry to find.
 588  * @return The data pointer for the stored entry on success, @c NULL
 589  * otherwise.
 590  *
 591  * This function retrieves the entry associated to @p key in
 592  * @p hash. If @p hash is @c NULL, this function returns immediately
 593  * @c NULL. This function returns the data pointer on success, @c NULL
 594  * otherwise.
 595  */
 596 EAPI void *eina_hash_find(const Eina_Hash *hash,
 597                           const void      *key) EINA_ARG_NONNULL(2);
 598
 599 /**
 600  * @brief Modify the entry pointer at the specified key and return the old
 601  * entry.
 602  * @param hash The given hash table.
 603  * @param key The key of the entry to modify.
 604  * @param data The data to replace the old entry.
 605  * @return The data pointer for the old stored entry on success, or
 606  * @c NULL otherwise.
 607  *
 608  * This function modifies the data of @p key with @p data in @p
 609  * hash. If no entry is found, nothing is added to @p hash. On success
 610  * this function returns the old entry, otherwise it returns @c NULL.
 611  */
 612 EAPI void *eina_hash_modify(Eina_Hash  *hash,
 613                             const void *key,
 614                             const void *data) EINA_ARG_NONNULL(1, 2, 3);
 615
 616 /**
 617  * @brief Modify the entry pointer at the specified key and return the
 618  * old entry or add the entry if not found.
 619  *
 620  * @param hash The given hash table.
 621  * @param key The key of the entry to modify.
 622  * @param data The data to replace the old entry
 623  * @return The data pointer for the old stored entry, or @c NULL
 624  * otherwise.
 625  *
 626  * This function modifies the data of @p key with @p data in @p
 627  * hash. If no entry is found, @p data is added to @p hash with the
 628  * key @p key. On success this function returns the old entry,
 629  * otherwise it returns @c NULL. To check for errors, use
 630  * eina_error_get().
 631  */
 632 EAPI void *eina_hash_set(Eina_Hash  *hash,
 633                          const void *key,
 634                          const void *data) EINA_ARG_NONNULL(1, 2);
 635
 636 /**
 637  * @brief Change the key associated with a data without triggering the
 638  * free callback.
 639  *
 640  * @param hash    The given hash table.
 641  * @param old_key The current key associated with the data
 642  * @param new_key The new key to associate data with
 643  * @return #EINA_FALSE in any case but success, #EINA_TRUE on success.
 644  *
 645  * This function allows for the move of data from one key to another,
 646  * but does not call the Eina_Free_Cb associated with the hash table
 647  * when destroying the old key.
 648  */
 649 EAPI Eina_Bool eina_hash_move(Eina_Hash  *hash,
 650                               const void *old_key,
 651                               const void *new_key) EINA_ARG_NONNULL(1, 2, 3);
 652
 653 /**
 654  * Free the given hash table resources.
 655  *
 656  * @param hash The hash table to be freed.
 657  *
 658  * This function frees up all the memory allocated to storing @p hash,
 659  * and call the free callback if it has been passed to the hash table
 660  * at creation time. If no free callback has been passed, any entries
 661  * in the table that the program has no more pointers for elsewhere
 662  * may now be lost, so this should only be called if the program has
 663  * already freed any allocated data in the hash table or has the
 664  * pointers for data in the table stored elsewhere as well. If @p hash
 665  * is @c NULL, the function returns immediately.
 666  *
 667  * Example:
 668  * @code
 669  * extern Eina_Hash *hash;
 670  *
 671  * eina_hash_free(hash);
 672  * hash = NULL;
 673  * @endcode
 674  */
 675 EAPI void      eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
 676
 677 /**
 678  * Free the given hash table buckets resources.
 679  *
 680  * @param hash The hash table whose buckets have to be freed.
 681  *
 682  * This function frees up all the memory allocated to storing the
 683  * buckets of @p hash, and calls the free callback on all hash table
 684  * buckets if it has been passed to the hash table at creation time,
 685  * then frees the buckets. If no free callback has been passed, no
 686  * buckets value will be freed. If @p hash is @c NULL, the function
 687  * returns immediately.
 688  */
 689 EAPI void      eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
 690
 691 /**
 692  * @brief Returns the number of entries in the given hash table.
 693  *
 694  * @param hash The given hash table.
 695  * @return The number of entries in the hash table.
 696  *
 697  * This function returns the number of entries in @p hash, or 0 on
 698  * error. If @p hash is @c NULL, @c 0 is returned.
 699  */
 700 EAPI int       eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
 701
 702 /**
 703  * @brief Add an entry to the given hash table.
 704  *
 705  * @param hash The given hash table. Cannot be @c NULL.
 706  * @param key A unique key. Cannot be @c NULL.
 707  * @param key_length The length of the key.
 708  * @param key_hash The hash that will always match key.
 709  * @param data The data to associate with the string given by the key. Cannot be
 710  * @c NULL.
 711  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 712  *
 713  * This function adds @p key to @p hash. @p hash, @p key and @p data
 714  * cannot be @c NULL, in that case #EINA_FALSE is returned. @p key is
 715  * expected to be a unique within the hash table. Otherwise,
 716  * one cannot be sure which inserted data pointer will be accessed
 717  * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do
 718  * not forget to count '\\0' for string when setting the value of
 719  * @p key_length. @p key_hash is expected to always match
 720  * @p key. Otherwise, one cannot be sure to find it again with @ref
 721  * eina_hash_find_by_hash. Key strings are case sensitive. If an error
 722  * occurs, eina_error_get() should be used to determine if an
 723  * allocation error occurred during this function. This function
 724  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 725  *
 726  * @see eina_hash_add()
 727  */
 728 EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash  *hash,
 729                                      const void *key,
 730                                      int         key_length,
 731                                      int         key_hash,
 732                                      const void *data) EINA_ARG_NONNULL(1, 2, 5);
 733
 734 /**
 735  * @brief Add an entry to the given hash table and do not duplicate the string
 736  * key.
 737  *
 738  * @param hash The given hash table. Cannot be @c NULL.
 739  * @param key A unique key. Cannot be @c NULL.
 740  * @param key_length Should be the length of @p key (don't forget to count
 741  * '\\0' for string).
 742  * @param key_hash The hash that will always match key.
 743  * @param data Data to associate with the string given by @p key. Cannot be @c
 744  * NULL.
 745  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 746  *
 747  * This function adds @p key to @p hash. @p hash, @p key and @p data
 748  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 749  * expected to be unique within the hash table. Otherwise,
 750  * one cannot be sure which inserted data pointer will be accessed
 751  * with @ref eina_hash_find, and removed with @ref eina_hash_del. This
 752  * function does not make a copy of @p key so it must be a string
 753  * constant or stored elsewhere (in the object being added). Do
 754  * not forget to count '\\0' for string when setting the value of
 755  * @p key_length. @p key_hash is expected to always match
 756  * @p key. Otherwise, one cannot be sure to find it again with @ref
 757  * eina_hash_find_by_hash. Key strings are case sensitive. If an error
 758  * occurs, eina_error_get() should be used to determine if an
 759  * allocation error occurred during this function. This function
 760  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 761  *
 762  * @see eina_hash_direct_add()
 763  */
 764 EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash  *hash,
 765                                             const void *key,
 766                                             int         key_length,
 767                                             int         key_hash,
 768                                             const void *data) EINA_ARG_NONNULL(1, 2, 5);
 769
 770 /**
 771  * @brief Remove the entry identified by a key and a key hash from the given
 772  * hash table.
 773  *
 774  * @param hash The given hash table. Cannot be @c NULL.
 775  * @param key The key. Cannot be @c NULL.
 776  * @param key_length The length of the key.
 777  * @param key_hash The hash that always match the key.
 778  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 779  *
 780  * This function removes the entry identified by @p key and
 781  * @p key_hash from @p hash. If a free function was given to the
 782  * callback on creation, it will be called for the data being
 783  * deleted. Do not forget to count '\\0' for string when setting the
 784  * value of @p key_length. If @p hash or @p key are @c NULL, the
 785  * functions returns immediately #EINA_FALSE. This function
 786  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 787  *
 788  * @note if you don't have the key_hash, use eina_hash_del_by_key() instead.
 789  * @note if you don't have the key, use eina_hash_del_by_data() instead.
 790  */
 791 EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash  *hash,
 792                                          const void *key,
 793                                          int         key_length,
 794                                          int         key_hash) EINA_ARG_NONNULL(1, 2);
 795
 796 /**
 797  * @brief Remove the entry identified by a key from the given hash table.
 798  *
 799  * This version will calculate key length and hash by using functions
 800  * provided to hash creation function.
 801  *
 802  * @param hash The given hash table. Cannot be @c NULL.
 803  * @param key  The key. Cannot be @c NULL.
 804  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 805  *
 806  * This function removes the entry identified by @p key from @p
 807  * hash. The key length and hash will be calculated automatically by
 808  * using functiond provided to has creation function. If a free
 809  * function was given to the callback on creation, it will be called
 810  * for the data being deleted. If @p hash or @p key are @c NULL, the
 811  * functions returns immediately #EINA_FALSE. This function
 812  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 813  *
 814  * @note if you already have the key_hash, use eina_hash_del_by_key_hash()
 815  * instead.
 816  * @note if you don't have the key, use eina_hash_del_by_data() instead.
 817  */
 818 EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash  *hash,
 819                                     const void *key) EINA_ARG_NONNULL(1, 2);
 820
 821 /**
 822  * @brief Remove the entry identified by a data from the given hash table.
 823  *
 824  * This version is slow since there is no quick access to nodes based on data.
 825  *
 826  * @param hash The given hash table. Cannot be @c NULL.
 827  * @param data The data value to search and remove. Cannot be @c NULL.
 828  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 829  *          thing goes fine.
 830  *
 831  * This function removes the entry identified by @p data from @p
 832  * hash. If a free function was given to the callback on creation, it
 833  * will be called for the data being deleted. If @p hash or @p data
 834  * are @c NULL, the functions returns immediately #EINA_FALSE. This
 835  * function returns #EINA_FALSE if an error occurred, #EINA_TRUE
 836  * otherwise.
 837  *
 838  * @note if you already have the key, use eina_hash_del_by_key() or
 839  * eina_hash_del_by_key_hash() instead.
 840  */
 841 EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash  *hash,
 842                                      const void *data) EINA_ARG_NONNULL(1, 2);
 843
 844 /**
 845  * @brief Remove the entry identified by a key and a key hash or a
 846  * data from the given hash table.
 847  *
 848  * If @p key is @c NULL, then @p data is used to find a match to
 849  * remove.
 850  *
 851  * @param hash The given hash table. Cannot be @c NULL.
 852  * @param key The key.
 853  * @param key_length The length of the key.
 854  * @param key_hash The hash that always match the key.
 855  * @param data The data pointer to remove if the key is @c NULL.
 856  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 857  *
 858  * This function removes the entry identified by @p key and
 859  * @p key_hash, or @p data, from @p hash. If a free function was given to
 860  * the  callback on creation, it will be called for the data being
 861  * deleted. If @p hash is @c NULL, the functions returns immediately #EINA_FALSE.
 862  * If @p key is @c NULL, then @p key_length and @p key_hash
 863  * are ignored and @p data is used to find a match to remove,
 864  * otherwise @p key and @p key_hash are used and @p data is not
 865  * required and can be @c NULL. Do not forget to count '\\0' for
 866  * string when setting the value of @p key_length. This function
 867  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 868  *
 869  * @note if you know you already have the key, use eina_hash_del_by_key_hash(),
 870  *       if you know you don't have the key, use eina_hash_del_by_data()
 871  *       directly.
 872  */
 873 EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash  *hash,
 874                                      const void *key,
 875                                      int         key_length,
 876                                      int         key_hash,
 877                                      const void *data) EINA_ARG_NONNULL(1);
 878
 879 /**
 880  * @brief Retrieve a specific entry in the given hash table.
 881  *
 882  * @param hash The given hash table. Cannot be @c NULL.
 883  * @param key The key of the entry to find.
 884  * @param key_length The length of the key.
 885  * @param key_hash The hash that always match the key
 886  * @return The data pointer for the stored entry on success, @c NULL
 887  * otherwise.
 888  *
 889  * This function retrieves the entry associated to @p key of length
 890  * @p key_length in @p hash. @p key_hash is the hash that always match
 891  * @p key. It is ignored if @p key is @c NULL. Do not forget to count
 892  * '\\0' for string when setting the value of @p key_length. If
 893  * @p hash is @c NULL, this function returns immediately @c NULL. This
 894  * function returns the data pointer on success, @c NULL otherwise.
 895  */
 896 EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
 897                                   const void      *key,
 898                                   int              key_length,
 899                                   int              key_hash) EINA_ARG_NONNULL(1, 2);
 900
 901 /**
 902  * @brief Modify the entry pointer at the specified key and returns
 903  * the old entry.
 904  *
 905  * @param hash The given hash table.
 906  * @param key The key of the entry to modify.
 907  * @param key_length Should be the length of @p key (don't forget to count
 908  * '\\0' for string).
 909  * @param key_hash The hash that always match the key. Ignored if @p key is
 910  *                 @c NULL.
 911  * @param data The data to replace the old entry, if it exists.
 912  * @return The data pointer for the old stored entry, or @c NULL if not
 913  *          found. If an existing entry is not found, nothing is added to the
 914  *          hash.
 915  */
 916 EAPI void *eina_hash_modify_by_hash(Eina_Hash  *hash,
 917                                     const void *key,
 918                                     int         key_length,
 919                                     int         key_hash,
 920                                     const void *data) EINA_ARG_NONNULL(1, 2, 5);
 921
 922 /**
 923  * @brief Returned a new iterator associated to hash keys.
 924  *
 925  * @param hash The hash.
 926  * @return A new iterator.
 927  *
 928  * This function returns a newly allocated iterator associated to @p
 929  * hash. If @p hash is not populated, this function still returns a
 930  * valid iterator that will always return false on
 931  * eina_iterator_next(), thus keeping API sane.
 932  *
 933  * If the memory can not be allocated, NULL is returned
 934  * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 935  * returned.
 936  *
 937  * @warning if the hash structure changes then the iterator becomes
 938  *    invalid! That is, if you add or remove items this iterator
 939  *    behavior is undefined and your program may crash!
 940  */
 941 EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 942
 943 /**
 944  * @brief Returned a new iterator associated to hash data.
 945  *
 946  * @param hash The hash.
 947  * @return A new iterator.
 948  *
 949  * This function returns a newly allocated iterator associated to
 950  * @p hash. If @p hash is not populated, this function still returns a
 951  * valid iterator that will always return false on
 952  * eina_iterator_next(), thus keeping API sane.
 953  *
 954  * If the memory can not be allocated, @c NULL is returned
 955  * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 956  * returned.
 957  *
 958  * @warning if the hash structure changes then the iterator becomes
 959  * invalid. That is, if you add or remove items this iterator behavior
 960  * is undefined and your program may crash.
 961  */
 962 EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 963
 964 /**
 965  * @brief Returned a new iterator associated to hash keys and data.
 966  *
 967  * @param hash The hash.
 968  * @return A new iterator.
 969  *
 970  * This function returns a newly allocated iterator associated to @p
 971  * hash. If @p hash is not populated, this function still returns a
 972  * valid iterator that will always return false on
 973  * eina_iterator_next(), thus keeping API sane.
 974  *
 975  * If the memory can not be allocated, @c NULL is returned
 976  * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 977  * returned.
 978  *
 979  * @note iterator data will provide values as Eina_Hash_Tuple that should not
 980  *   be modified!
 981  *
 982  * @warning if the hash structure changes then the iterator becomes
 983  *    invalid! That is, if you add or remove items this iterator
 984  *    behavior is undefined and your program may crash!
 985  */
 986 EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 987
 988 /**
 989  * @brief Call a function on every member stored in the hash table
 990  *
 991  * @param hash The hash table whose members will be walked
 992  * @param func The function to call on each parameter
 993  * @param fdata The data pointer to pass to the function being called
 994  *
 995  * This function goes through every entry in the hash table @p hash and calls
 996  * the function @p func on each member. The function should @b not modify the
 997  * hash table contents if it returns @c 1. @b If the hash table contents are
 998  * modified by this function or the function wishes to stop processing it must
 999  * return @c 0, otherwise return @c 1 to keep processing.
1000  *
1001  * Example:
1002  * @code
1003  * extern Eina_Hash *hash;
1004  *
1005  * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key,
1006  *                   void *data, void *fdata)
1007  * {
1008  *   printf("Func data: %s, Hash entry: %s / %p\n",
1009  *          fdata, (const char *)key, data);
1010  *   return 1;
1011  * }
1012  *
1013  * int main(int argc, char **argv)
1014  * {
1015  *   char *hash_fn_data;
1016  *
1017  *   hash_fn_data = strdup("Hello World");
1018  *   eina_hash_foreach(hash, hash_fn, hash_fn_data);
1019  *   free(hash_fn_data);
1020  * }
1021  * @endcode
1022  */
1023 EAPI void           eina_hash_foreach(const Eina_Hash  *hash,
1024                                       Eina_Hash_Foreach func,
1025                                       const void       *fdata) EINA_ARG_NONNULL(1, 2);
1026 /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */
1027 EAPI int eina_hash_superfast(const char *key,
1028                              int         len) EINA_ARG_NONNULL(1);
1029 /* Hash function first reported by dan bernstein many years ago in comp.lang.c */
1030 static inline int eina_hash_djb2(const char *key,
1031                                  int         len) EINA_ARG_NONNULL(1);
1032 static inline int eina_hash_djb2_len(const char *key,
1033                                      int        *plen) EINA_ARG_NONNULL(1, 2);
1034 /* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */
1035 static inline int eina_hash_int32(const unsigned int *pkey,
1036                                   int                 len) EINA_ARG_NONNULL(1);
1037 static inline int eina_hash_int64(const unsigned long int *pkey,
1038                                   int                      len) EINA_ARG_NONNULL(1);
1039 /* http://sites.google.com/site/murmurhash/ */
1040 static inline int eina_hash_murmur3(const char *key,
1041                            int         len) EINA_ARG_NONNULL(1);
1042 #include "eina_inline_hash.x"
1043
1044 /**
1045  * @}
1046  */
1047
1048 /**
1049  * @}
1050  */
1051
1052 /**
1053  * @}
1054  */
1055
1056 #endif /*EINA_HASH_H_*/