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  * @addtogroup Eina_Hash_Group Hash Table
 122  *
 123  * @brief Hash table management. Useful for mapping keys to values.
 124  *
 125  * The hash table is useful for when one wants to implement a table that maps
 126  * keys (usually strings) to data, and have relatively fast access time. The
 127  * performance is proportional to the load factor of the table (number of
 128  * elements / number of buckets). See @ref hashtable_algo for implementation
 129  * details.
 130  *
 131  * Different implementations exists depending on what kind of key will be used
 132  * to access the data: strings, integers, pointers, stringshared or your own.
 133  *
 134  * Eina hash tables can copy the keys when using eina_hash_add() or not when
 135  * using eina_hash_direct_add().
 136  *
 137  * @section hashtable_algo Algorithm
 138  *
 139  * The Eina_Hash is implemented using an array of N "buckets", where each
 140  * bucket is a pointer to a structure that is the head of a <a
 141  * href="http://en.wikipedia.org/wiki/Red-black_tree">red-black tree</a>. The
 142  * array can then be indexed by the [hash_of_element mod N]. The
 143  * hash_of_element is calculated using the hashing function, passed as
 144  * parameter to the @ref eina_hash_new function. N is the number of buckets
 145  * (array positions), and is calculated based on the buckets_power_size
 146  * (argument of @ref eina_hash_new too). The following picture ilustrates the
 147  * basic idea:
 148  *
 149  * @image html 01_hash-table.png
 150  * @image latex 01_hash-table.eps
 151  *
 152  * Adding an element to the hash table is made of:
 153  * @li calculating the hash for that key (using the specified hash function);
 154  * @li calculate the array position [hash mod N];
 155  * @li add the element to the rbtree on that position.
 156  *
 157  * The two first steps have constant time, proportional to the hash function
 158  * being used. Adding the key to the rbtree will be proportional on the number
 159  * of keys on that bucket.
 160  *
 161  * The average cost of lookup depends on the number of keys per
 162  * bucket (load factor) of the table, if the distribution of keys is
 163  * sufficiently uniform.
 164  *
 165  * @section hashtable_perf Performance
 166  *
 167  * As said before, the performance depends on the load factor. So trying to keep
 168  * it as small as possible will improve the hash table performance. But
 169  * increasing the buckets_power_size will also increase the memory consumption.
 170  * The default hash table creation functions already have a good number of
 171  * buckets, enough for most cases. Particularly for strings, if just a few keys
 172  * (less than 30) will be added to the hash table, @ref
 173  * eina_hash_string_small_new should be used. If just stringshared keys are
 174  * being added, use @ref eina_hash_stringshared_new. If a lot of keys will be
 175  * added to the hash table (e.g. more than 1000), then it's better to increase
 176  * the buckets_power_size. See @ref eina_hash_new for more details.
 177  *
 178  * When adding a new key to a hash table, use @ref eina_hash_add or @ref
 179  * eina_hash_direct_add (the latter if this key is already stored elsewhere). If
 180  * the key may be already inside the hash table, instead of checking with
 181  * @ref eina_hash_find and then doing @ref eina_hash_add, one can use just @ref
 182  * eina_hash_set (this will change the data pointed by this key if it was
 183  * already present in the table).
 184  *
 185  * @section hashtable_tutorial Tutorial
 186  *
 187  * These examples show many Eina_Hash functions in action:
 188  * @li @ref hash_01_example_page
 189  * @li @ref hash_02_example_page
 190  *
 191  * @{
 192  */
 193
 194 /**
 195  * @addtogroup Eina_Data_Types_Group Data Types
 196  *
 197  * @{
 198  */
 199
 200 /**
 201  * @addtogroup Eina_Containers_Group Containers
 202  *
 203  * @{
 204  */
 205
 206 /**
 207  * @defgroup Eina_Hash_Group Hash Table
 208  *
 209  * @{
 210  */
 211
 212 /**
 213  * @typedef Eina_Hash
 214  * Type for a generic hash table.
 215  */
 216 typedef struct _Eina_Hash       Eina_Hash;
 217
 218 typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple;
 219
 220 struct _Eina_Hash_Tuple
 221 {
 222    const void  *key; /**< The key */
 223    void        *data; /**< The data associated to the key */
 224    unsigned int key_length; /**< The length of the key */
 225 };
 226
 227 typedef unsigned int (*Eina_Key_Length)(const void *key);
 228 #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
 229 typedef int          (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
 230 #define EINA_KEY_CMP(Function)    ((Eina_Key_Cmp)Function)
 231 typedef int          (*Eina_Key_Hash)(const void *key, int key_length);
 232 #define EINA_KEY_HASH(Function)   ((Eina_Key_Hash)Function)
 233 typedef Eina_Bool    (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata);
 234
 235
 236 /**
 237  * @brief Create a new hash table.
 238  *
 239  * @param key_length_cb The function called when getting the size of the key.
 240  * @param key_cmp_cb The function called when comparing the keys.
 241  * @param key_hash_cb The function called when getting the values.
 242  * @param data_free_cb The function called on each value when the hash
 243  * table is freed. @c NULL can be passed as callback.
 244  * @param buckets_power_size The size of the buckets.
 245  * @return The new hash table.
 246  *
 247  * This function creates a new hash table using user-defined callbacks
 248  * to manage the hash table. On failure, @c NULL is returned and
 249  * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb
 250  * are @c NULL, @c NULL is returned. If @p buckets_power_size is
 251  * smaller or equal than 2, or if it is greater or equal than 17,
 252  * @c NULL is returned.
 253  *
 254  * Pre-defined functions are available to create a hash table. See
 255  * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(),
 256  * eina_hash_string_small_new(), eina_hash_int32_new(),
 257  * eina_hash_int64_new(), eina_hash_pointer_new() and
 258  * eina_hash_stringshared_new().
 259  */
 260 EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
 261                               Eina_Key_Cmp    key_cmp_cb,
 262                               Eina_Key_Hash   key_hash_cb,
 263                               Eina_Free_Cb    data_free_cb,
 264                               int             buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
 265
 266 /**
 267  * @brief Create a new hash table using the djb2 algorithm.
 268  *
 269  * @param data_free_cb The function called on each value when the hash table
 270  * is freed. @c NULL can be passed as callback.
 271  * @return The new hash table.
 272  *
 273  * This function creates a new hash table using the djb2 algorithm for
 274  * table management and strcmp() to compare the keys. Values can then
 275  * be looked up with pointers other than the original key pointer that
 276  * was used to add values. On failure, this function returns @c NULL.
 277  */
 278 EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
 279
 280 /**
 281  * @brief Create a new hash table for use with strings.
 282  *
 283  * @param data_free_cb The function called on each value when the hash table
 284  * is freed. @c NULL can be passed as callback.
 285  * @return The new hash table.
 286  *
 287  * This function creates a new hash table using the superfast algorithm
 288  * for table management and strcmp() to compare the keys. Values can
 289  * then be looked up with pointers other than the original key pointer
 290  * that was used to add values. On failure, this function returns
 291  * @c NULL.
 292  */
 293 EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
 294
 295 /**
 296  * @brief Create a new hash table for use with strings with small bucket size.
 297  *
 298  * @param data_free_cb  The function called on each value when the hash table
 299  * is freed. @c NULL can be passed as callback.
 300  * @return  The new hash table.
 301  *
 302  * This function creates a new hash table using the superfast algorithm
 303  * for table management and strcmp() to compare the keys, but with a
 304  * smaller bucket size (compared to eina_hash_string_superfast_new())
 305  * which will minimize the memory used by the returned hash
 306  * table. Values can then be looked up with pointers other than the
 307  * original key pointer that was used to add values. On failure, this
 308  * function returns @c NULL.
 309  */
 310 EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
 311
 312 /**
 313  * @brief Create a new hash table for use with 32bit integers.
 314  *
 315  * @param data_free_cb  The function called on each value when the hash table
 316  * is freed. @c NULL can be passed as callback.
 317  * @return  The new hash table.
 318  *
 319  * This function creates a new hash table where keys are 32bit integers.
 320  * When adding or looking up in the hash table, pointers to 32bit integers
 321  * must be passed. They can be addresses on the stack if you let the
 322  * eina_hash copy the key. Values can then
 323  * be looked up with pointers other than the original key pointer that was
 324  * used to add values. This method is not suitable to match string keys as
 325  * it would only match the first character.
 326  * On failure, this function returns @c NULL.
 327  */
 328 EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
 329
 330 /**
 331  * @brief Create a new hash table for use with 64bit integers.
 332  *
 333  * @param data_free_cb  The function called on each value when the hash table
 334  * is freed. @c NULL can be passed as callback.
 335  * @return  The new hash table.
 336  *
 337  * This function creates a new hash table where keys are 64bit integers.
 338  * When adding or looking up in the hash table, pointers to 64bit integers
 339  * must be passed. They can be addresses on the stack. Values can then
 340  * be looked up with pointers other than the original key pointer that was
 341  * used to add values. This method is not suitable to match string keys as
 342  * it would only match the first character.
 343  * On failure, this function returns @c NULL.
 344  */
 345 EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
 346
 347 /**
 348  * @brief Create a new hash table for use with pointers.
 349  *
 350  * @param data_free_cb  The function called on each value when the hash table
 351  * is freed. @c NULL can be passed as callback.
 352  * @return  The new hash table.
 353  *
 354  * This function creates a new hash table using the int64/int32 algorithm for
 355  * table management and dereferenced pointers to compare the
 356  * keys. Values can then be looked up with pointers other than the
 357  * original key pointer that was used to add values. This method may
 358  * appear to be able to match string keys, actually it only matches
 359  * the first character. On failure, this function returns @c NULL.
 360  */
 361 EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
 362
 363 /**
 364  * @brief Create a new hash table optimized for stringshared values.
 365  *
 366  * @param data_free_cb  The function called on each value when the hash table
 367  * is freed. @c NULL can be passed as callback.
 368  * @return  The new hash table.
 369  *
 370  * This function creates a new hash table optimized for stringshared
 371  * values. Values CAN NOT be looked up with pointers not
 372  * equal to the original key pointer that was used to add a value. On failure,
 373  * this function returns @c NULL.
 374  *
 375  * Excerpt of code that will NOT work with this type of hash:
 376  *
 377  * @code
 378  * extern Eina_Hash *hash;
 379  * extern const char *value;
 380  * const char *a = eina_stringshare_add("key");
 381  *
 382  * eina_hash_add(hash, a, value);
 383  * eina_hash_find(hash, "key")
 384  * @endcode
 385  */
 386 EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
 387
 388 /**
 389  * @brief Add an entry to the given hash table.
 390  *
 391  * @param hash The given hash table.
 392  * @param key A unique key.
 393  * @param data Data to associate with the string given by @p key.
 394  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 395  *
 396  * This function adds @p key to @p hash. @p hash, @p key and @p data
 397  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 398  * expected to be unique within the hash table. Key uniqueness varies
 399  * depending on the type of @p hash: a stringshared @ref Eina_Hash
 400  * need only have unique pointers for keys, but the strings in the
 401  * pointers may be identical. All other hash types require the strings
 402  * themselves to be unique. Failure to use sufficient uniqueness will
 403  * result in unexpected results when inserting data pointers accessed
 404  * with eina_hash_find(), and removed with eina_hash_del(). Key
 405  * strings are case sensitive. If an error occurs, eina_error_get()
 406  * should be used to determine if an allocation error occurred during
 407  * this function. This function returns #EINA_FALSE if an error
 408  * occurred, #EINA_TRUE otherwise.
 409  */
 410 EAPI Eina_Bool  eina_hash_add(Eina_Hash  *hash,
 411                               const void *key,
 412                               const void *data) EINA_ARG_NONNULL(1, 2, 3);
 413
 414 /**
 415  * @brief Add an entry to the given hash table without duplicating the string
 416  * key.
 417  *
 418  * @param hash The given hash table.  Can be @c NULL.
 419  * @param key A unique key.  Can be @c NULL.
 420  * @param data Data to associate with the string given by @p key.
 421  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 422  *
 423  * This function adds @p key to @p hash. @p hash, @p key and @p data
 424  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 425  * expected to be unique within the hash table. Key uniqueness varies
 426  * depending on the type of @p hash: a stringshared @ref Eina_Hash
 427  * need only have unique pointers for keys, but the strings in the
 428  * pointers may be identical. All other hash types require the strings
 429  * themselves to be unique. Failure to use sufficient uniqueness will
 430  * result in unexpected results when inserting data pointers accessed
 431  * with eina_hash_find(), and removed with eina_hash_del(). This
 432  * function does not make a copy of @p key, so it must be a string
 433  * constant or stored elsewhere ( in the object being added). Key
 434  * strings are case sensitive. If an error occurs, eina_error_get()
 435  * should be used to determine if an allocation error occurred during
 436  * this function. This function returns #EINA_FALSE if an error
 437  * occurred, #EINA_TRUE otherwise.
 438  */
 439 EAPI Eina_Bool eina_hash_direct_add(Eina_Hash  *hash,
 440                                     const void *key,
 441                                     const void *data) EINA_ARG_NONNULL(1, 2, 3);
 442
 443 /**
 444  * @brief Remove the entry identified by a key or a data from the given
 445  * hash table.
 446  *
 447  * @param hash The given hash table.
 448  * @param key  The key.
 449  * @param data The data pointer to remove if the key is @c NULL.
 450  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 451  *
 452  * This function removes the entry identified by @p key or @p data
 453  * from @p hash. If a free function was given to the
 454  * callback on creation, it will be called for the data being
 455  * deleted. If @p hash is @c NULL, the functions returns immediately
 456  * #EINA_FALSE. If @p key is @c NULL, then @p data is used to find the a
 457  * match to remove, otherwise @p key is used and @p data is not
 458  * required and can be @c NULL. This function returns #EINA_FALSE if
 459  * an error occurred, #EINA_TRUE otherwise.
 460  *
 461  * @note if you know you already have the key, use
 462  *       eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
 463  *       know you don't have the key, use eina_hash_del_by_data()
 464  *       directly.
 465  */
 466 EAPI Eina_Bool eina_hash_del(Eina_Hash  *hash,
 467                              const void *key,
 468                              const void *data) EINA_ARG_NONNULL(1);
 469
 470 /**
 471  * @brief Retrieve a specific entry in the given hash table.
 472  *
 473  * @param hash The given hash table.
 474  * @param key The key of the entry to find.
 475  * @return The data pointer for the stored entry on success, @c NULL
 476  * otherwise.
 477  *
 478  * This function retrieves the entry associated to @p key in
 479  * @p hash. If @p hash is @c NULL, this function returns immediately
 480  * @c NULL. This function returns the data pointer on success, @c NULL
 481  * otherwise.
 482  */
 483 EAPI void *eina_hash_find(const Eina_Hash *hash,
 484                           const void      *key) EINA_ARG_NONNULL(1, 2);
 485
 486 /**
 487  * @brief Modify the entry pointer at the specified key and return the old
 488  * entry.
 489  * @param hash The given hash table.
 490  * @param key The key of the entry to modify.
 491  * @param data The data to replace the old entry.
 492  * @return The data pointer for the old stored entry on success, or
 493  * @c NULL otherwise.
 494  *
 495  * This function modifies the data of @p key with @p data in @p
 496  * hash. If no entry is found, nothing is added to @p hash. On success
 497  * this function returns the old entry, otherwise it returns @c NULL.
 498  */
 499 EAPI void *eina_hash_modify(Eina_Hash  *hash,
 500                             const void *key,
 501                             const void *data) EINA_ARG_NONNULL(1, 2, 3);
 502
 503 /**
 504  * @brief Modify the entry pointer at the specified key and return the
 505  * old entry or add the entry if not found.
 506  *
 507  * @param hash The given hash table.
 508  * @param key The key of the entry to modify.
 509  * @param data The data to replace the old entry
 510  * @return The data pointer for the old stored entry, or @c NULL
 511  * otherwise.
 512  *
 513  * This function modifies the data of @p key with @p data in @p
 514  * hash. If no entry is found, @p data is added to @p hash with the
 515  * key @p key. On success this function returns the old entry,
 516  * otherwise it returns @c NULL. To check for errors, use
 517  * eina_error_get().
 518  */
 519 EAPI void *eina_hash_set(Eina_Hash  *hash,
 520                          const void *key,
 521                          const void *data) EINA_ARG_NONNULL(1, 2);
 522
 523 /**
 524  * @brief Change the key associated with a data without triggering the
 525  * free callback.
 526  *
 527  * @param hash    The given hash table.
 528  * @param old_key The current key associated with the data
 529  * @param new_key The new key to associate data with
 530  * @return EINA_FALSE in any case but success, EINA_TRUE on success.
 531  *
 532  * This function allows for the move of data from one key to another,
 533  * but does not call the Eina_Free_Cb associated with the hash table
 534  * when destroying the old key.
 535  */
 536 EAPI Eina_Bool eina_hash_move(Eina_Hash  *hash,
 537                               const void *old_key,
 538                               const void *new_key) EINA_ARG_NONNULL(1, 2, 3);
 539
 540 /**
 541  * Free the given hash table resources.
 542  *
 543  * @param hash The hash table to be freed.
 544  *
 545  * This function frees up all the memory allocated to storing @p hash,
 546  * and call the free callback if it has been passed to the hash table
 547  * at creation time. If no free callback has been passed, any entries
 548  * in the table that the program has no more pointers for elsewhere
 549  * may now be lost, so this should only be called if the program has
 550  * already freed any allocated data in the hash table or has the
 551  * pointers for data in the table stored elsewhere as well. If @p hash
 552  * is @c NULL, the function returns immediately.
 553  *
 554  * Example:
 555  * @code
 556  * extern Eina_Hash *hash;
 557  *
 558  * eina_hash_free(hash);
 559  * hash = NULL;
 560  * @endcode
 561  */
 562 EAPI void      eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
 563
 564 /**
 565  * Free the given hash table buckets resources.
 566  *
 567  * @param hash The hash table whose buckets have to be freed.
 568  *
 569  * This function frees up all the memory allocated to storing the
 570  * buckets of @p hash, and calls the free callback on all hash table
 571  * buckets if it has been passed to the hash table at creation time,
 572  * then frees the buckets. If no free callback has been passed, no
 573  * buckets value will be freed. If @p hash is @c NULL, the function
 574  * returns immediately.
 575  */
 576 EAPI void      eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
 577
 578 /**
 579  * @brief Returns the number of entries in the given hash table.
 580  *
 581  * @param hash The given hash table.
 582  * @return The number of entries in the hash table.
 583  *
 584  * This function returns the number of entries in @p hash, or 0 on
 585  * error. If @p hash is @c NULL, 0 is returned.
 586  */
 587 EAPI int       eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
 588
 589 /**
 590  * @brief Add an entry to the given hash table.
 591  *
 592  * @param hash The given hash table.
 593  * @param key A unique key.
 594  * @param key_length The length of the key.
 595  * @param key_hash The hash that will always match key.
 596  * @param data The data to associate with the string given by the key.
 597  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 598  *
 599  * This function adds @p key to @p hash. @p hash, @p key and @p data
 600  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 601  * expected to be a unique string within the hash table. Otherwise,
 602  * one cannot be sure which inserted data pointer will be accessed
 603  * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do
 604  * not forget to count '\\0' for string when setting the value of
 605  * @p key_length. @p key_hash is expected to always match
 606  * @p key. Otherwise, one cannot be sure to find it again with @ref
 607  * eina_hash_find_by_hash. Key strings are case sensitive. If an error
 608  * occurs, eina_error_get() should be used to determine if an
 609  * allocation error occurred during this function. This function
 610  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 611  */
 612 EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash  *hash,
 613                                      const void *key,
 614                                      int         key_length,
 615                                      int         key_hash,
 616                                      const void *data) EINA_ARG_NONNULL(1, 2, 5);
 617
 618 /**
 619  * @brief Add an entry to the given hash table and do not duplicate the string
 620  * key.
 621  *
 622  * @param hash The given hash table.  Can be @c NULL.
 623  * @param key A unique key.  Can be @c NULL.
 624  * @param key_length Should be the length of @p key (don't forget to count
 625  * '\\0' for string).
 626  * @param key_hash The hash that will always match key.
 627  * @param data Data to associate with the string given by @p key.
 628  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 629  *
 630  * This function adds @p key to @p hash. @p hash, @p key and @p data
 631  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 632  * expected to be a unique string within the hash table. Otherwise,
 633  * one cannot be sure which inserted data pointer will be accessed
 634  * with @ref eina_hash_find, and removed with @ref eina_hash_del. This
 635  * function does not make a copy of @p key so it must be a string
 636  * constant or stored elsewhere (in the object being added). Do
 637  * not forget to count '\\0' for string when setting the value of
 638  * @p key_length. @p key_hash is expected to always match
 639  * @p key. Otherwise, one cannot be sure to find it again with @ref
 640  * eina_hash_find_by_hash. Key strings are case sensitive. If an error
 641  * occurs, eina_error_get() should be used to determine if an
 642  * allocation error occurred during this function. This function
 643  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 644  */
 645 EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash  *hash,
 646                                             const void *key,
 647                                             int         key_length,
 648                                             int         key_hash,
 649                                             const void *data) EINA_ARG_NONNULL(1, 2, 5);
 650
 651 /**
 652  * @brief Remove the entry identified by a key and a key hash from the given
 653  * hash table.
 654  *
 655  * @param hash The given hash table.
 656  * @param key The key.
 657  * @param key_length The length of the key.
 658  * @param key_hash The hash that always match the key.
 659  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 660  *
 661  * This function removes the entry identified by @p key and
 662  * @p key_hash from @p hash. If a free function was given to the
 663  * callback on creation, it will be called for the data being
 664  * deleted. Do not forget to count '\\0' for string when setting the
 665  * value of @p key_length. If @p hash or @p key are @c NULL, the
 666  * functions returns immediately #EINA_FALSE. This function returns
 667  * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 668  *
 669  * @note if you don't have the key_hash, use eina_hash_del_by_key() instead.
 670  * @note if you don't have the key, use eina_hash_del_by_data() instead.
 671  */
 672 EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash  *hash,
 673                                          const void *key,
 674                                          int         key_length,
 675                                          int         key_hash) EINA_ARG_NONNULL(1, 2);
 676
 677 /**
 678  * @brief Remove the entry identified by a key from the given hash table.
 679  *
 680  * This version will calculate key length and hash by using functions
 681  * provided to hash creation function.
 682  *
 683  * @param hash The given hash table.
 684  * @param key  The key.
 685  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 686  *
 687  * This function removes the entry identified by @p key from @p
 688  * hash. The key length and hash will be calculated automatically by
 689  * using functiond provided to has creation function. If a free
 690  * function was given to the callback on creation, it will be called
 691  * for the data being deleted. If @p hash or @p key are @c NULL, the
 692  * functions returns immediately #EINA_FALSE. This function returns
 693  * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 694  *
 695  * @note if you already have the key_hash, use eina_hash_del_by_key_hash()
 696  * instead.
 697  * @note if you don't have the key, use eina_hash_del_by_data() instead.
 698  */
 699 EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash  *hash,
 700                                     const void *key) EINA_ARG_NONNULL(1, 2);
 701
 702 /**
 703  * @brief Remove the entry identified by a data from the given hash table.
 704  *
 705  * This version is slow since there is no quick access to nodes based on data.
 706  *
 707  * @param hash The given hash table.
 708  * @param data The data value to search and remove.
 709  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 710  *          thing goes fine.
 711  *
 712  * This function removes the entry identified by @p data from @p
 713  * hash. If a free function was given to the callback on creation, it
 714  * will be called for the data being deleted. If @p hash or @p data
 715  * are @c NULL, the functions returns immediately #EINA_FALSE. This
 716  * function returns #EINA_FALSE if an error occurred, #EINA_TRUE
 717  * otherwise.
 718  *
 719  * @note if you already have the key, use eina_hash_del_by_key() or
 720  * eina_hash_del_by_key_hash() instead.
 721  */
 722 EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash  *hash,
 723                                      const void *data) EINA_ARG_NONNULL(1, 2);
 724
 725 /**
 726  * @brief Remove the entry identified by a key and a key hash or a
 727  * data from the given hash table.
 728  *
 729  * If @p key is @c NULL, then @p data is used to find a match to
 730  * remove.
 731  *
 732  * @param hash The given hash table.
 733  * @param key The key.
 734  * @param key_length The length of the key.
 735  * @param key_hash The hash that always match the key.
 736  * @param data The data pointer to remove if the key is @c NULL.
 737  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 738  *
 739  * This function removes the entry identified by @p key and
 740  * @p key_hash, or @p data, from @p hash. If a free function was given to
 741  * the  callback on creation, it will be called for the data being
 742  * deleted. If @p hash is @c NULL, the functions returns immediately
 743  * #EINA_FALSE. If @p key is @c NULL, then @p key_hash and @p key_hash
 744  * are ignored and @p data is used to find a match to remove,
 745  * otherwise @p key and @p key_hash are used and @p data is not
 746  * required and can be @c NULL. Do not forget to count '\\0' for
 747  * string when setting the value of @p key_length. This function
 748  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 749  *
 750  * @note if you know you already have the key, use eina_hash_del_by_key_hash(),
 751  *       if you know you don't have the key, use eina_hash_del_by_data()
 752  *       directly.
 753  */
 754 EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash  *hash,
 755                                      const void *key,
 756                                      int         key_length,
 757                                      int         key_hash,
 758                                      const void *data) EINA_ARG_NONNULL(1);
 759
 760 /**
 761  * @brief Retrieve a specific entry in the given hash table.
 762  *
 763  * @param hash The given hash table.
 764  * @param key The key of the entry to find.
 765  * @param key_length The length of the key.
 766  * @param key_hash The hash that always match the key
 767  * @return The data pointer for the stored entry on success, @c NULL
 768  * otherwise.
 769  *
 770  * This function retrieves the entry associated to @p key of length
 771  * @p key_length in @p hash. @p key_hash is the hash that always match
 772  * @p key. It is ignored if @p key is @c NULL. Do not forget to count
 773  * '\\0' for string when setting the value of @p key_length. If
 774  * @p hash is @c NULL, this function returns immediately @c NULL. This
 775  * function returns the data pointer on success, @c NULL otherwise.
 776  */
 777 EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
 778                                   const void      *key,
 779                                   int              key_length,
 780                                   int              key_hash) EINA_ARG_NONNULL(1, 2);
 781
 782 /**
 783  * @brief Modify the entry pointer at the specified key and returns
 784  * the old entry.
 785  *
 786  * @param hash The given hash table.
 787  * @param key The key of the entry to modify.
 788  * @param key_length Should be the length of @p key (don't forget to count
 789  * '\\0' for string).
 790  * @param key_hash The hash that always match the key. Ignored if @p key is
 791  *                 @c NULL.
 792  * @param data The data to replace the old entry, if it exists.
 793  * @return The data pointer for the old stored entry, or @c NULL if not
 794  *          found. If an existing entry is not found, nothing is added to the
 795  *          hash.
 796  */
 797 EAPI void *eina_hash_modify_by_hash(Eina_Hash  *hash,
 798                                     const void *key,
 799                                     int         key_length,
 800                                     int         key_hash,
 801                                     const void *data) EINA_ARG_NONNULL(1, 2, 5);
 802
 803 /**
 804  * @brief Returned a new iterator associated to hash keys.
 805  *
 806  * @param hash The hash.
 807  * @return A new iterator.
 808  *
 809  * This function returns a newly allocated iterator associated to @p
 810  * hash. If @p hash is not populated, this function still returns a
 811  * valid iterator that will always return false on
 812  * eina_iterator_next(), thus keeping API sane.
 813  *
 814  * If the memory can not be allocated, NULL is returned and
 815  * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 816  * returned.
 817  *
 818  * @warning if the hash structure changes then the iterator becomes
 819  *    invalid! That is, if you add or remove items this iterator
 820  *    behavior is undefined and your program may crash!
 821  */
 822 EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 823
 824 /**
 825  * @brief Returned a new iterator associated to hash data.
 826  *
 827  * @param hash The hash.
 828  * @return A new iterator.
 829  *
 830  * This function returns a newly allocated iterator associated to
 831  * @p hash. If @p hash is not populated, this function still returns a
 832  * valid iterator that will always return false on
 833  * eina_iterator_next(), thus keeping API sane.
 834  *
 835  * If the memory can not be allocated, @c NULL is returned and
 836  * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 837  * returned.
 838  *
 839  * @warning if the hash structure changes then the iterator becomes
 840  * invalid. That is, if you add or remove items this iterator behavior
 841  * is undefined and your program may crash.
 842  */
 843 EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 844
 845 /**
 846  * @brief Returned a new iterator associated to hash keys and data.
 847  *
 848  * @param hash The hash.
 849  * @return A new iterator.
 850  *
 851  * This function returns a newly allocated iterator associated to @p
 852  * hash. If @p hash is not populated, this function still returns a
 853  * valid iterator that will always return false on
 854  * eina_iterator_next(), thus keeping API sane.
 855  *
 856  * If the memory can not be allocated, NULL is returned and
 857  * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 858  * returned.
 859  *
 860  * @note iterator data will provide values as Eina_Hash_Tuple that should not
 861  *   be modified!
 862  *
 863  * @warning if the hash structure changes then the iterator becomes
 864  *    invalid! That is, if you add or remove items this iterator
 865  *    behavior is undefined and your program may crash!
 866  */
 867 EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 868
 869 /**
 870  * @brief Call a function on every member stored in the hash table
 871  *
 872  * @param hash The hash table whose members will be walked
 873  * @param func The function to call on each parameter
 874  * @param fdata The data pointer to pass to the function being called
 875  *
 876  * This function goes through every entry in the hash table @p hash and calls
 877  * the function @p func on each member. The function should @b not modify the
 878  * hash table contents if it returns 1. @b If the hash table contents are
 879  * modified by this function or the function wishes to stop processing it must
 880  * return 0, otherwise return 1 to keep processing.
 881  *
 882  * Example:
 883  * @code
 884  * extern Eina_Hash *hash;
 885  *
 886  * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key,
 887  *                   void *data, void *fdata)
 888  * {
 889  *   printf("Func data: %s, Hash entry: %s / %p\n",
 890  *          fdata, (const char *)key, data);
 891  *   return 1;
 892  * }
 893  *
 894  * int main(int argc, char **argv)
 895  * {
 896  *   char *hash_fn_data;
 897  *
 898  *   hash_fn_data = strdup("Hello World");
 899  *   eina_hash_foreach(hash, hash_fn, hash_fn_data);
 900  *   free(hash_fn_data);
 901  * }
 902  * @endcode
 903  */
 904 EAPI void           eina_hash_foreach(const Eina_Hash  *hash,
 905                                       Eina_Hash_Foreach cb,
 906                                       const void       *fdata) EINA_ARG_NONNULL(1, 2);
 907 /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */
 908 EAPI int eina_hash_superfast(const char *key,
 909                              int         len) EINA_ARG_NONNULL(1);
 910 /* Hash function first reported by dan bernstein many years ago in comp.lang.c */
 911 static inline int eina_hash_djb2(const char *key,
 912                                  int         len) EINA_ARG_NONNULL(1);
 913 static inline int eina_hash_djb2_len(const char *key,
 914                                      int        *plen) EINA_ARG_NONNULL(1, 2);
 915 /* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */
 916 static inline int eina_hash_int32(const unsigned int *pkey,
 917                                   int                 len) EINA_ARG_NONNULL(1);
 918 static inline int eina_hash_int64(const unsigned long int *pkey,
 919                                   int                      len) EINA_ARG_NONNULL(1);
 920
 921 #include "eina_inline_hash.x"
 922
 923 /**
 924  * @}
 925  */
 926
 927 /**
 928  * @}
 929  */
 930
 931 /**
 932  * @}
 933  */
 934
 935 /**
 936  * @}
 937  */
 938
 939 #endif /*EINA_HASH_H_*/