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  * @addtogroup Eina_Hash_Group Hash Table
  28  *
  29  * @brief give a small description here : what it is for, what it does
  30  * , etc...
  31  * Different implementations exists depending on what to store: strings,
  32  * integers, pointers, stringshared or your own...
  33  * Eina hash tables can copy the keys when using eina_hash_add() or not when
  34  * using eina_hash_direct_add().
  35  *
  36  * Hash API. Give some hints about the use (functions that must be
  37  * used like init / shutdown), general use, etc... Give also a link to
  38  * tutorial below.
  39  *
  40  * @section hashtable_algo Algorithm
  41  *
  42  * Give here the algorithm used in the implementation
  43  *
  44  * @section hashtable_perf Performance
  45  *
  46  * Give some hints about performance if it is possible, and an image !
  47  *
  48  * @section hashtable_tutorial Tutorial
  49  *
  50  * Here is a fantastic tutorial about our hash table
  51  *
  52  * @{
  53  */
  54
  55 /**
  56  * @addtogroup Eina_Data_Types_Group Data Types
  57  *
  58  * @{
  59  */
  60
  61 /**
  62  * @addtogroup Eina_Containers_Group Containers
  63  *
  64  * @{
  65  */
  66
  67 /**
  68  * @defgroup Eina_Hash_Group Hash Table
  69  *
  70  * @{
  71  */
  72
  73 /**
  74  * @typedef Eina_Hash
  75  * Type for a generic hash table.
  76  */
  77 typedef struct _Eina_Hash       Eina_Hash;
  78
  79 typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple;
  80
  81 struct _Eina_Hash_Tuple
  82 {
  83    const void  *key; /**< The key */
  84    void        *data; /**< The data associated to the key */
  85    unsigned int key_length; /**< The length of the key */
  86 };
  87
  88 typedef unsigned int (*Eina_Key_Length)(const void *key);
  89 #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
  90 typedef int          (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
  91 #define EINA_KEY_CMP(Function)    ((Eina_Key_Cmp)Function)
  92 typedef int          (*Eina_Key_Hash)(const void *key, int key_length);
  93 #define EINA_KEY_HASH(Function)   ((Eina_Key_Hash)Function)
  94 typedef Eina_Bool    (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata);
  95
  96
  97 /**
  98  * @brief Create a new hash table.
  99  *
 100  * @param key_length_cb The function called when getting the size of the key.
 101  * @param key_cmp_cb The function called when comparing the keys.
 102  * @param key_hash_cb The function called when getting the values.
 103  * @param data_free_cb The function called when the hash table is freed.
 104  * @param buckets_power_size The size of the buckets.
 105  * @return The new hash table.
 106  *
 107  * This function creates a new hash table using user-defined callbacks
 108  * to manage the hash table. On failure, @c NULL is returned and
 109  * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb
 110  * are @c NULL, @c NULL is returned. If @p buckets_power_size is
 111  * smaller or equal than 2, or if it is greater or equal than 17,
 112  * @c NULL is returned.
 113  *
 114  * Pre-defined functions are available to create a hash table. See
 115  * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(),
 116  * eina_hash_string_small_new(), eina_hash_int32_new(),
 117  * eina_hash_int64_new(), eina_hash_pointer_new() and
 118  * eina_hash_stringshared_new().
 119  */
 120 EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
 121                               Eina_Key_Cmp    key_cmp_cb,
 122                               Eina_Key_Hash   key_hash_cb,
 123                               Eina_Free_Cb    data_free_cb,
 124                               int             buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
 125
 126 /**
 127  * @brief Create a new hash table using the djb2 algorithm.
 128  *
 129  * @param data_free_cb The function called when the hash table is freed.
 130  * @return The new hash table.
 131  *
 132  * This function creates a new hash table using the djb2 algorithm for
 133  * table management and strcmp() to compare the keys. Values can then
 134  * be looked up with pointers other than the original key pointer that
 135  * was used to add values. On failure, this function returns @c NULL.
 136  * @p data_free_cb is a callback called when the hash table is
 137  * freed. @c NULL can be passed as callback.
 138  */
 139 EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
 140
 141 /**
 142  * @brief Create a new hash table for use with strings.
 143  *
 144  * @param data_free_cb The function called when the hash table is freed.
 145  * @return The new hash table.
 146  *
 147  * This function creates a new hash table using the superfast algorithm
 148  * for table management and strcmp() to compare the keys. Values can
 149  * then be looked up with pointers other than the original key pointer
 150  * that was used to add values. On failure, this function returns
 151  * @c NULL. @p data_free_cb is a callback called when the hash table is
 152  * freed. @c NULL can be passed as callback.
 153  */
 154 EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
 155
 156 /**
 157  * @brief Create a new hash table for use with strings with small bucket size.
 158  *
 159  * @param data_free_cb  The function called when the hash table is freed.
 160  * @return  The new hash table.
 161  *
 162  * This function creates a new hash table using the superfast algorithm
 163  * for table management and strcmp() to compare the keys, but with a
 164  * smaller bucket size (compared to eina_hash_string_superfast_new())
 165  * which will minimize the memory used by the returned hash
 166  * table. Values can then be looked up with pointers other than the
 167  * original key pointer that was used to add values. On failure, this
 168  * function returns @c NULL. @p data_free_cb is a callback called when
 169  * the hash table is freed. @c NULL can be passed as callback.
 170  */
 171 EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
 172
 173 /**
 174  * @brief Create a new hash table for use with 32bit integers.
 175  *
 176  * @param data_free_cb  The function called when the hash table is freed.
 177  * @return  The new hash table.
 178  *
 179  * This function creates a new hash table where keys are 32bit integers.
 180  * When adding or looking up in the hash table, pointers to 32bit integers
 181  * must be passed. They can be addresses on the stack if you let the
 182  * eina_hash copy the key. Values can then
 183  * be looked up with pointers other than the original key pointer that was
 184  * used to add values. This method is not suitable to match string keys as
 185  * it would only match the first character.
 186  * On failure, this function returns @c NULL.
 187  * @p data_free_cb is a callback called when the hash table is freed.
 188  * @c NULL can be passed as callback.
 189  */
 190 EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
 191
 192 /**
 193  * @brief Create a new hash table for use with 64bit integers.
 194  *
 195  * @param data_free_cb  The function called when the hash table is freed.
 196  * @return  The new hash table.
 197  *
 198  * This function creates a new hash table where keys are 64bit integers.
 199  * When adding or looking up in the hash table, pointers to 64bit integers
 200  * must be passed. They can be addresses on the stack. Values can then
 201  * be looked up with pointers other than the original key pointer that was
 202  * used to add values. This method is not suitable to match string keys as
 203  * it would only match the first character.
 204  * On failure, this function returns @c NULL.
 205  * @p data_free_cb is a callback called when the hash table is freed.
 206  * @c NULL can be passed as callback.
 207  */
 208 EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
 209
 210 /**
 211  * @brief Create a new hash table for use with pointers.
 212  *
 213  * @param data_free_cb  The function called when the hash table is freed.
 214  * @return  The new hash table.
 215  *
 216  * This function creates a new hash table using the int64/int32 algorithm for
 217  * table management and dereferenced pointers to compare the
 218  * keys. Values can then be looked up with pointers other than the
 219  * original key pointer that was used to add values. This method may
 220  * appear to be able to match string keys, actually it only matches
 221  * the first character. On failure, this function returns @c NULL.
 222  * @p data_free_cb is a callback called when the hash table is freed.
 223  * @c NULL can be passed as callback.
 224  */
 225 EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
 226
 227 /**
 228  * @brief Create a new hash table optimized for stringshared values.
 229  *
 230  * @param data_free_cb  The function called when the hash table is freed.
 231  * @return  The new hash table.
 232  *
 233  * This function creates a new hash table optimized for stringshared
 234  * values. Values CAN NOT be looked up with pointers not
 235  * equal to the original key pointer that was used to add a value. On failure,
 236  * this function returns @c NULL.
 237  * @p data_free_cb is a callback called when the hash table is freed.
 238  * @c NULL can be passed as callback.
 239  *
 240  * Excerpt of code that will NOT work with this type of hash:
 241  *
 242  * @code
 243  * extern Eina_Hash *hash;
 244  * extern const char *value;
 245  * const char *a = eina_stringshare_add("key");
 246  *
 247  * eina_hash_add(hash, a, value);
 248  * eina_hash_find(hash, "key")
 249  * @endcode
 250  */
 251 EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
 252
 253 /**
 254  * @brief Add an entry to the given hash table.
 255  *
 256  * @param hash The given hash table.
 257  * @param key A unique key.
 258  * @param data Data to associate with the string given by @p key.
 259  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 260  *
 261  * This function adds @p key to @p hash. @p hash, @p key and @p data
 262  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 263  * expected to be unique within the hash table. Key uniqueness varies
 264  * depending on the type of @p hash: a stringshared @ref Eina_Hash
 265  * need only have unique pointers for keys, but the strings in the
 266  * pointers may be identical. All other hash types require the strings
 267  * themselves to be unique. Failure to use sufficient uniqueness will
 268  * result in unexpected results when inserting data pointers accessed
 269  * with eina_hash_find(), and removed with eina_hash_del(). Key
 270  * strings are case sensitive. If an error occurs, eina_error_get()
 271  * should be used to determine if an allocation error occurred during
 272  * this function. This function returns #EINA_FALSE if an error
 273  * occurred, #EINA_TRUE otherwise.
 274  */
 275 EAPI Eina_Bool  eina_hash_add(Eina_Hash  *hash,
 276                               const void *key,
 277                               const void *data) EINA_ARG_NONNULL(1, 2, 3);
 278
 279 /**
 280  * @brief Add an entry to the given hash table without duplicating the string
 281  * key.
 282  *
 283  * @param hash The given hash table.  Can be @c NULL.
 284  * @param key A unique key.  Can be @c NULL.
 285  * @param data Data to associate with the string given by @p key.
 286  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 287  *
 288  * This function adds @p key to @p hash. @p hash, @p key and @p data
 289  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 290  * expected to be unique within the hash table. Key uniqueness varies
 291  * depending on the type of @p hash: a stringshared @ref Eina_Hash
 292  * need only have unique pointers for keys, but the strings in the
 293  * pointers may be identical. All other hash types require the strings
 294  * themselves to be unique. Failure to use sufficient uniqueness will
 295  * result in unexpected results when inserting data pointers accessed
 296  * with eina_hash_find(), and removed with eina_hash_del(). This
 297  * function does not make a copy of @p key, so it must be a string
 298  * constant or stored elsewhere ( in the object being added). Key
 299  * strings are case sensitive. If an error occurs, eina_error_get()
 300  * should be used to determine if an allocation error occurred during
 301  * this function. This function returns #EINA_FALSE if an error
 302  * occurred, #EINA_TRUE otherwise.
 303  */
 304 EAPI Eina_Bool eina_hash_direct_add(Eina_Hash  *hash,
 305                                     const void *key,
 306                                     const void *data) EINA_ARG_NONNULL(1, 2, 3);
 307
 308 /**
 309  * @brief Remove the entry identified by a key or a data from the given
 310  * hash table.
 311  *
 312  * @param hash The given hash table.
 313  * @param key  The key.
 314  * @param data The data pointer to remove if the key is @c NULL.
 315  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 316  *
 317  * This function removes the entry identified by @p key or @p data
 318  * from @p hash. If a free function was given to the
 319  * callback on creation, it will be called for the data being
 320  * deleted. If @p hash is @c NULL, the functions returns immediately
 321  * #EINA_FALSE. If @p key is @c NULL, then @p data is used to find the a
 322  * match to remove, otherwise @p key is used and @p data is not
 323  * required and can be @c NULL. This function returns #EINA_FALSE if
 324  * an error occurred, #EINA_TRUE otherwise.
 325  *
 326  * @note if you know you already have the key, use
 327  *       eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
 328  *       know you don't have the key, use eina_hash_del_by_data()
 329  *       directly.
 330  */
 331 EAPI Eina_Bool eina_hash_del(Eina_Hash  *hash,
 332                              const void *key,
 333                              const void *data) EINA_ARG_NONNULL(1);
 334
 335 /**
 336  * @brief Retrieve a specific entry in the given hash table.
 337  *
 338  * @param hash The given hash table.
 339  * @param key The key of the entry to find.
 340  * @return The data pointer for the stored entry on success, @c NULL
 341  * otherwise.
 342  *
 343  * This function retrieves the entry associated to @p key in
 344  * @p hash. If @p hash is @c NULL, this function returns immediately
 345  * @c NULL. This function returns the data pointer on success, @c NULL
 346  * otherwise.
 347  */
 348 EAPI void *eina_hash_find(const Eina_Hash *hash,
 349                           const void      *key) EINA_ARG_NONNULL(1, 2);
 350
 351 /**
 352  * @brief Modify the entry pointer at the specified key and return the old
 353  * entry.
 354  * @param hash The given hash table.
 355  * @param key The key of the entry to modify.
 356  * @param data The data to replace the old entry.
 357  * @return The data pointer for the old stored entry on success, or
 358  * @c NULL otherwise.
 359  *
 360  * This function modifies the data of @p key with @p data in @p
 361  * hash. If no entry is found, nothing is added to @p hash. On success
 362  * this function returns the old entry, otherwise it returns @c NULL.
 363  */
 364 EAPI void *eina_hash_modify(Eina_Hash  *hash,
 365                             const void *key,
 366                             const void *data) EINA_ARG_NONNULL(1, 2, 3);
 367
 368 /**
 369  * @brief Modify the entry pointer at the specified key and return the
 370  * old entry or add the entry if not found.
 371  *
 372  * @param hash The given hash table.
 373  * @param key The key of the entry to modify.
 374  * @param data The data to replace the old entry
 375  * @return The data pointer for the old stored entry, or @c NULL
 376  * otherwise.
 377  *
 378  * This function modifies the data of @p key with @p data in @p
 379  * hash. If no entry is found, @p data is added to @p hash with the
 380  * key @p key. On success this function returns the old entry,
 381  * otherwise it returns @c NULL. To check for errors, use
 382  * eina_error_get().
 383  */
 384 EAPI void *eina_hash_set(Eina_Hash  *hash,
 385                          const void *key,
 386                          const void *data) EINA_ARG_NONNULL(1, 2, 3);
 387
 388 /**
 389  * @brief Change the key associated with a data without triggering the
 390  * free callback.
 391  *
 392  * @param hash    The given hash table.
 393  * @param old_key The current key associated with the data
 394  * @param new_key The new key to associate data with
 395  * @return EINA_FALSE in any case but success, EINA_TRUE on success.
 396  *
 397  * This function allows for the move of data from one key to another,
 398  * but does not call the Eina_Free_Cb associated with the hash table
 399  * when destroying the old key.
 400  */
 401 EAPI Eina_Bool eina_hash_move(Eina_Hash  *hash,
 402                               const void *old_key,
 403                               const void *new_key) EINA_ARG_NONNULL(1, 2, 3);
 404
 405 /**
 406  * Free the given hash table resources.
 407  *
 408  * @param hash The hash table to be freed.
 409  *
 410  * This function frees up all the memory allocated to storing @p hash,
 411  * and call the free callback if it has been passed to the hash table
 412  * at creation time. If no free callback has been passed, any entries
 413  * in the table that the program has no more pointers for elsewhere
 414  * may now be lost, so this should only be called if the program has
 415  * already freed any allocated data in the hash table or has the
 416  * pointers for data in the table stored elsewhere as well. If @p hash
 417  * is @c NULL, the function returns immediately.
 418  *
 419  * Example:
 420  * @code
 421  * extern Eina_Hash *hash;
 422  *
 423  * eina_hash_free(hash);
 424  * hash = NULL;
 425  * @endcode
 426  */
 427 EAPI void      eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
 428
 429 /**
 430  * Free the given hash table buckets resources.
 431  *
 432  * @param hash The hash table whose buckets have to be freed.
 433  *
 434  * This function frees up all the memory allocated to storing the
 435  * buckets of @p hash, and calls the free callback on all hash table
 436  * buckets if it has been passed to the hash table at creation time,
 437  * then frees the buckets. If no free callback has been passed, no
 438  * buckets value will be freed. If @p hash is @c NULL, the function
 439  * returns immediately.
 440  */
 441 EAPI void      eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
 442
 443 /**
 444  * @brief Returns the number of entries in the given hash table.
 445  *
 446  * @param hash The given hash table.
 447  * @return The number of entries in the hash table.
 448  *
 449  * This function returns the number of entries in @p hash, or 0 on
 450  * error. If @p hash is @c NULL, 0 is returned.
 451  */
 452 EAPI int       eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
 453
 454 /**
 455  * @brief Add an entry to the given hash table.
 456  *
 457  * @param hash The given hash table.
 458  * @param key A unique key.
 459  * @param key_length The length of the key.
 460  * @param key_hash The hash that will always match key.
 461  * @param data The data to associate with the string given by the key.
 462  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 463  *
 464  * This function adds @p key to @p hash. @p hash, @p key and @p data
 465  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 466  * expected to be a unique string within the hash table. Otherwise,
 467  * one cannot be sure which inserted data pointer will be accessed
 468  * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do
 469  * not forget to count '\\0' for string when setting the value of
 470  * @p key_length. @p key_hash is expected to always match
 471  * @p key. Otherwise, one cannot be sure to find it again with @ref
 472  * eina_hash_find_by_hash. Key strings are case sensitive. If an error
 473  * occurs, eina_error_get() should be used to determine if an
 474  * allocation error occurred during this function. This function
 475  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 476  */
 477 EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash  *hash,
 478                                      const void *key,
 479                                      int         key_length,
 480                                      int         key_hash,
 481                                      const void *data) EINA_ARG_NONNULL(1, 2, 5);
 482
 483 /**
 484  * @brief Add an entry to the given hash table and do not duplicate the string
 485  * key.
 486  *
 487  * @param hash The given hash table.  Can be @c NULL.
 488  * @param key A unique key.  Can be @c NULL.
 489  * @param key_length Should be the length of @p key (don't forget to count
 490  * '\\0' for string).
 491  * @param key_hash The hash that will always match key.
 492  * @param data Data to associate with the string given by @p key.
 493  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 494  *
 495  * This function adds @p key to @p hash. @p hash, @p key and @p data
 496  * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
 497  * expected to be a unique string within the hash table. Otherwise,
 498  * one cannot be sure which inserted data pointer will be accessed
 499  * with @ref eina_hash_find, and removed with @ref eina_hash_del. This
 500  * function does not make a copy of @p key so it must be a string
 501  * constant or stored elsewhere (in the object being added). Do
 502  * not forget to count '\\0' for string when setting the value of
 503  * @p key_length. @p key_hash is expected to always match
 504  * @p key. Otherwise, one cannot be sure to find it again with @ref
 505  * eina_hash_find_by_hash. Key strings are case sensitive. If an error
 506  * occurs, eina_error_get() should be used to determine if an
 507  * allocation error occurred during this function. This function
 508  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 509  */
 510 EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash  *hash,
 511                                             const void *key,
 512                                             int         key_length,
 513                                             int         key_hash,
 514                                             const void *data) EINA_ARG_NONNULL(1, 2, 5);
 515
 516 /**
 517  * @brief Remove the entry identified by a key and a key hash from the given
 518  * hash table.
 519  *
 520  * @param hash The given hash table.
 521  * @param key The key.
 522  * @param key_length The length of the key.
 523  * @param key_hash The hash that always match the key.
 524  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 525  *
 526  * This function removes the entry identified by @p key and
 527  * @p key_hash from @p hash. If a free function was given to the
 528  * callback on creation, it will be called for the data being
 529  * deleted. Do not forget to count '\\0' for string when setting the
 530  * value of @p key_length. If @p hash or @p key are @c NULL, the
 531  * functions returns immediately #EINA_FALSE. This function returns
 532  * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 533  *
 534  * @note if you don't have the key_hash, use eina_hash_del_by_key() instead.
 535  * @note if you don't have the key, use eina_hash_del_by_data() instead.
 536  */
 537 EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash  *hash,
 538                                          const void *key,
 539                                          int         key_length,
 540                                          int         key_hash) EINA_ARG_NONNULL(1, 2);
 541
 542 /**
 543  * @brief Remove the entry identified by a key from the given hash table.
 544  *
 545  * This version will calculate key length and hash by using functions
 546  * provided to hash creation function.
 547  *
 548  * @param hash The given hash table.
 549  * @param key  The key.
 550  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 551  *
 552  * This function removes the entry identified by @p key from @p
 553  * hash. The key length and hash will be calculated automatically by
 554  * using functiond provided to has creation function. If a free
 555  * function was given to the callback on creation, it will be called
 556  * for the data being deleted. If @p hash or @p key are @c NULL, the
 557  * functions returns immediately #EINA_FALSE. This function returns
 558  * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 559  *
 560  * @note if you already have the key_hash, use eina_hash_del_by_key_hash()
 561  * instead.
 562  * @note if you don't have the key, use eina_hash_del_by_data() instead.
 563  */
 564 EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash  *hash,
 565                                     const void *key) EINA_ARG_NONNULL(1, 2);
 566
 567 /**
 568  * @brief Remove the entry identified by a data from the given hash table.
 569  *
 570  * This version is slow since there is no quick access to nodes based on data.
 571  *
 572  * @param hash The given hash table.
 573  * @param data The data value to search and remove.
 574  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 575  *          thing goes fine.
 576  *
 577  * This function removes the entry identified by @p data from @p
 578  * hash. If a free function was given to the callback on creation, it
 579  * will be called for the data being deleted. If @p hash or @p data
 580  * are @c NULL, the functions returns immediately #EINA_FALSE. This
 581  * function returns #EINA_FALSE if an error occurred, #EINA_TRUE
 582  * otherwise.
 583  *
 584  * @note if you already have the key, use eina_hash_del_by_key() or
 585  * eina_hash_del_by_key_hash() instead.
 586  */
 587 EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash  *hash,
 588                                      const void *data) EINA_ARG_NONNULL(1, 2);
 589
 590 /**
 591  * @brief Remove the entry identified by a key and a key hash or a
 592  * data from the given hash table.
 593  *
 594  * If @p key is @c NULL, then @p data is used to find a match to
 595  * remove.
 596  *
 597  * @param hash The given hash table.
 598  * @param key The key.
 599  * @param key_length The length of the key.
 600  * @param key_hash The hash that always match the key.
 601  * @param data The data pointer to remove if the key is @c NULL.
 602  * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 603  *
 604  * This function removes the entry identified by @p key and
 605  * @p key_hash, or @p data, from @p hash. If a free function was given to
 606  * the  callback on creation, it will be called for the data being
 607  * deleted. If @p hash is @c NULL, the functions returns immediately
 608  * #EINA_FALSE. If @p key is @c NULL, then @p key_hash and @p key_hash
 609  * are ignored and @p data is used to find a match to remove,
 610  * otherwise @p key and @p key_hash are used and @p data is not
 611  * required and can be @c NULL. Do not forget to count '\\0' for
 612  * string when setting the value of @p key_length. This function
 613  * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
 614  *
 615  * @note if you know you already have the key, use eina_hash_del_by_key_hash(),
 616  *       if you know you don't have the key, use eina_hash_del_by_data()
 617  *       directly.
 618  */
 619 EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash  *hash,
 620                                      const void *key,
 621                                      int         key_length,
 622                                      int         key_hash,
 623                                      const void *data) EINA_ARG_NONNULL(1);
 624
 625 /**
 626  * @brief Retrieve a specific entry in the given hash table.
 627  *
 628  * @param hash The given hash table.
 629  * @param key The key of the entry to find.
 630  * @param key_length The length of the key.
 631  * @param key_hash The hash that always match the key
 632  * @return The data pointer for the stored entry on success, @c NULL
 633  * otherwise.
 634  *
 635  * This function retrieves the entry associated to @p key of length
 636  * @p key_length in @p hash. @p key_hash is the hash that always match
 637  * @p key. It is ignored if @p key is @c NULL. Do not forget to count
 638  * '\\0' for string when setting the value of @p key_length. If
 639  * @p hash is @c NULL, this function returns immediately @c NULL. This
 640  * function returns the data pointer on success, @c NULL otherwise.
 641  */
 642 EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
 643                                   const void      *key,
 644                                   int              key_length,
 645                                   int              key_hash) EINA_ARG_NONNULL(1, 2);
 646
 647 /**
 648  * @brief Modify the entry pointer at the specified key and returns
 649  * the old entry.
 650  *
 651  * @param hash The given hash table.
 652  * @param key The key of the entry to modify.
 653  * @param key_length Should be the length of @p key (don't forget to count
 654  * '\\0' for string).
 655  * @param key_hash The hash that always match the key. Ignored if @p key is
 656  *                 @c NULL.
 657  * @param data The data to replace the old entry, if it exists.
 658  * @return The data pointer for the old stored entry, or @c NULL if not
 659  *          found. If an existing entry is not found, nothing is added to the
 660  *          hash.
 661  */
 662 EAPI void *eina_hash_modify_by_hash(Eina_Hash  *hash,
 663                                     const void *key,
 664                                     int         key_length,
 665                                     int         key_hash,
 666                                     const void *data) EINA_ARG_NONNULL(1, 2, 5);
 667
 668 /**
 669  * @brief Returned a new iterator associated to hash keys.
 670  *
 671  * @param hash The hash.
 672  * @return A new iterator.
 673  *
 674  * This function returns a newly allocated iterator associated to @p
 675  * hash. If @p hash is not populated, this function still returns a
 676  * valid iterator that will always return false on
 677  * eina_iterator_next(), thus keeping API sane.
 678  *
 679  * If the memory can not be allocated, NULL is returned and
 680  * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 681  * returned.
 682  *
 683  * @warning if the hash structure changes then the iterator becomes
 684  *    invalid! That is, if you add or remove items this iterator
 685  *    behavior is undefined and your program may crash!
 686  */
 687 EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 688
 689 /**
 690  * @brief Returned a new iterator associated to hash data.
 691  *
 692  * @param hash The hash.
 693  * @return A new iterator.
 694  *
 695  * This function returns a newly allocated iterator associated to
 696  * @p hash. If @p hash is not populated, this function still returns a
 697  * valid iterator that will always return false on
 698  * eina_iterator_next(), thus keeping API sane.
 699  *
 700  * If the memory can not be allocated, @c NULL is returned and
 701  * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 702  * returned.
 703  *
 704  * @warning if the hash structure changes then the iterator becomes
 705  * invalid. That is, if you add or remove items this iterator behavior
 706  * is undefined and your program may crash.
 707  */
 708 EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 709
 710 /**
 711  * @brief Returned a new iterator associated to hash keys and data.
 712  *
 713  * @param hash The hash.
 714  * @return A new iterator.
 715  *
 716  * This function returns a newly allocated iterator associated to @p
 717  * hash. If @p hash is not populated, this function still returns a
 718  * valid iterator that will always return false on
 719  * eina_iterator_next(), thus keeping API sane.
 720  *
 721  * If the memory can not be allocated, NULL is returned and
 722  * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
 723  * returned.
 724  *
 725  * @note iterator data will provide values as Eina_Hash_Tuple that should not
 726  *   be modified!
 727  *
 728  * @warning if the hash structure changes then the iterator becomes
 729  *    invalid! That is, if you add or remove items this iterator
 730  *    behavior is undefined and your program may crash!
 731  */
 732 EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 733
 734 /**
 735  * @brief Call a function on every member stored in the hash table
 736  *
 737  * @param hash The hash table whose members will be walked
 738  * @param func The function to call on each parameter
 739  * @param fdata The data pointer to pass to the function being called
 740  *
 741  * This function goes through every entry in the hash table @p hash and calls
 742  * the function @p func on each member. The function should @b not modify the
 743  * hash table contents if it returns 1. @b If the hash table contents are
 744  * modified by this function or the function wishes to stop processing it must
 745  * return 0, otherwise return 1 to keep processing.
 746  *
 747  * Example:
 748  * @code
 749  * extern Eina_Hash *hash;
 750  *
 751  * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key,
 752  *                   void *data, void *fdata)
 753  * {
 754  *   printf("Func data: %s, Hash entry: %s / %p\n",
 755  *          fdata, (const char *)key, data);
 756  *   return 1;
 757  * }
 758  *
 759  * int main(int argc, char **argv)
 760  * {
 761  *   char *hash_fn_data;
 762  *
 763  *   hash_fn_data = strdup("Hello World");
 764  *   eina_hash_foreach(hash, hash_fn, hash_fn_data);
 765  *   free(hash_fn_data);
 766  * }
 767  * @endcode
 768  */
 769 EAPI void           eina_hash_foreach(const Eina_Hash  *hash,
 770                                       Eina_Hash_Foreach cb,
 771                                       const void       *fdata) EINA_ARG_NONNULL(1, 2);
 772 /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */
 773 EAPI int eina_hash_superfast(const char *key,
 774                              int         len) EINA_ARG_NONNULL(1);
 775 /* Hash function first reported by dan bernstein many years ago in comp.lang.c */
 776 static inline int eina_hash_djb2(const char *key,
 777                                  int         len) EINA_ARG_NONNULL(1);
 778 static inline int eina_hash_djb2_len(const char *key,
 779                                      int        *plen) EINA_ARG_NONNULL(1, 2);
 780 /* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */
 781 static inline int eina_hash_int32(const unsigned int *pkey,
 782                                   int                 len) EINA_ARG_NONNULL(1);
 783 static inline int eina_hash_int64(const unsigned long int *pkey,
 784                                   int                      len) EINA_ARG_NONNULL(1);
 785
 786 #include "eina_inline_hash.x"
 787
 788 /**
 789  * @}
 790  */
 791
 792 /**
 793  * @}
 794  */
 795
 796 /**
 797  * @}
 798  */
 799
 800 /**
 801  * @}
 802  */
 803
 804 #endif /*EINA_HASH_H_*/