aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_hash.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_hash.h')
-rw-r--r--libraries/eina/src/include/eina_hash.h1040
1 files changed, 0 insertions, 1040 deletions
diff --git a/libraries/eina/src/include/eina_hash.h b/libraries/eina/src/include/eina_hash.h
deleted file mode 100644
index 57316b2..0000000
--- a/libraries/eina/src/include/eina_hash.h
+++ /dev/null
@@ -1,1040 +0,0 @@
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 */
287typedef struct _Eina_Hash Eina_Hash;
288
289typedef struct _Eina_Hash_Tuple Eina_Hash_Tuple;
290
291struct _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
298typedef unsigned int (*Eina_Key_Length)(const void *key);
299#define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
300typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
301#define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function)
302typedef int (*Eina_Key_Hash)(const void *key, int key_length);
303#define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function)
304typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key, void *data, void *fdata);
305
306
307/**
308 * @brief Create a new hash table.
309 *
310 * @param key_length_cb The function called when getting the size of the key.
311 * @param key_cmp_cb The function called when comparing the keys.
312 * @param key_hash_cb The function called when getting the values.
313 * @param data_free_cb The function called on each value when the hash table is
314 * freed, or when an item is deleted from it. @c NULL can be passed as
315 * callback.
316 * @param buckets_power_size The size of the buckets.
317 * @return The new hash table.
318 *
319 * This function creates a new hash table using user-defined callbacks
320 * to manage the hash table. On failure, @c NULL is returned and
321 * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb
322 * are @c NULL, @c NULL is returned. If @p buckets_power_size is
323 * smaller or equal than 2, or if it is greater or equal than 17,
324 * @c NULL is returned.
325 *
326 * The number of buckets created will be 2 ^ @p buckets_power_size. This means
327 * that if @p buckets_power_size is 5, there will be created 32 buckets. for a
328 * @p buckets_power_size of 8, there will be 256 buckets.
329 *
330 * Pre-defined functions are available to create a hash table. See
331 * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(),
332 * eina_hash_string_small_new(), eina_hash_int32_new(),
333 * eina_hash_int64_new(), eina_hash_pointer_new() and
334 * eina_hash_stringshared_new().
335 */
336EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
337 Eina_Key_Cmp key_cmp_cb,
338 Eina_Key_Hash key_hash_cb,
339 Eina_Free_Cb data_free_cb,
340 int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
341
342/**
343 * @brief Redefine the callback that clean the data of a hash
344 *
345 * @param hash The given hash table
346 * @param data_free_cb The function called on each value when the hash
347 * table is freed, or when an item is deleted from it. @c NULL can be passed as
348 * callback.
349 * @since 1.1
350 * See @ref eina_hash_new.
351 */
352EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1);
353
354/**
355 * @brief Create a new hash table using the djb2 algorithm.
356 *
357 * @param data_free_cb The function called on each value when the hash table
358 * is freed, or when an item is deleted from it. @c NULL can be passed as
359 * callback.
360 * @return The new hash table.
361 *
362 * This function creates a new hash table using the djb2 algorithm for
363 * table management and strcmp() to compare the keys. Values can then
364 * be looked up with pointers other than the original key pointer that
365 * was used to add values. On failure, this function returns @c NULL.
366 */
367EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
368
369/**
370 * @brief Create a new hash table for use with strings.
371 *
372 * @param data_free_cb The function called on each value when the hash table
373 * is freed, or when an item is deleted from it. @c NULL can be passed as
374 * callback.
375 * @return The new hash table.
376 *
377 * This function creates a new hash table using the superfast algorithm
378 * for table management and strcmp() to compare the keys. Values can
379 * then be looked up with pointers other than the original key pointer
380 * that was used to add values. On failure, this function returns
381 * @c NULL.
382 */
383EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
384
385/**
386 * @brief Create a new hash table for use with strings with small bucket size.
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, but with a
395 * smaller bucket size (compared to eina_hash_string_superfast_new())
396 * which will minimize the memory used by the returned hash
397 * table. Values can then be looked up with pointers other than the
398 * original key pointer that was used to add values. On failure, this
399 * function returns @c NULL.
400 */
401EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
402
403/**
404 * @brief Create a new hash table for use with 32bit integers.
405 *
406 * @param data_free_cb The function called on each value when the hash table
407 * is freed, or when an item is deleted from it. @c NULL can be passed as
408 * callback.
409 * @return The new hash table.
410 *
411 * This function creates a new hash table where keys are 32bit integers.
412 * When adding or looking up in the hash table, pointers to 32bit integers
413 * must be passed. They can be addresses on the stack if you let the
414 * eina_hash copy the key. Values can then
415 * be looked up with pointers other than the original key pointer that was
416 * used to add values. This method is not suitable to match string keys as
417 * it would only match the first character.
418 * On failure, this function returns @c NULL.
419 */
420EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
421
422/**
423 * @brief Create a new hash table for use with 64bit integers.
424 *
425 * @param data_free_cb The function called on each value when the hash table
426 * is freed, or when an item is deleted from it. @c NULL can be passed as
427 * callback.
428 * @return The new hash table.
429 *
430 * This function creates a new hash table where keys are 64bit integers.
431 * When adding or looking up in the hash table, pointers to 64bit integers
432 * must be passed. They can be addresses on the stack. Values can then
433 * be looked up with pointers other than the original key pointer that was
434 * used to add values. This method is not suitable to match string keys as
435 * it would only match the first character.
436 * On failure, this function returns @c NULL.
437 */
438EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
439
440/**
441 * @brief Create a new hash table for use with pointers.
442 *
443 * @param data_free_cb The function called on each value when the hash table
444 * is freed, or when an item is deleted from it. @c NULL can be passed as
445 * callback.
446 * @return The new hash table.
447 *
448 * This function creates a new hash table using the int64/int32 algorithm for
449 * table management and dereferenced pointers to compare the
450 * keys. Values can then be looked up with pointers other than the
451 * original key pointer that was used to add values. This method may
452 * appear to be able to match string keys, actually it only matches
453 * the first character. On failure, this function returns @c NULL.
454 */
455EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
456
457/**
458 * @brief Create a new hash table optimized for stringshared values.
459 *
460 * @param data_free_cb The function called on each value when the hash table
461 * is freed, or when an item is deleted from it. @c NULL can be passed as
462 * callback.
463 * @return The new hash table.
464 *
465 * This function creates a new hash table optimized for stringshared
466 * values. Values CAN NOT be looked up with pointers not
467 * equal to the original key pointer that was used to add a value. On failure,
468 * this function returns @c NULL.
469 *
470 * Excerpt of code that will NOT work with this type of hash:
471 *
472 * @code
473 * extern Eina_Hash *hash;
474 * extern const char *value;
475 * const char *a = eina_stringshare_add("key");
476 *
477 * eina_hash_add(hash, a, value);
478 * eina_hash_find(hash, "key")
479 * @endcode
480 */
481EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
482
483/**
484 * @brief Add an entry to the given hash table.
485 *
486 * @param hash The given hash table. Cannot be @c NULL.
487 * @param key A unique key. Cannot be @c NULL.
488 * @param data Data to associate with the string given by @p key. Cannot be @c
489 * NULL.
490 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
491 *
492 * This function adds @p key to @p hash. @p key is
493 * expected to be unique within the hash table. Key uniqueness varies
494 * depending on the type of @p hash: a stringshared @ref Eina_Hash
495 * need to have unique pointers (which implies unique strings).
496 * All other string hash types require the strings
497 * themselves to be unique. Pointer, int32 and int64 hashes need to have these
498 * values as unique. Failure to use sufficient uniqueness will
499 * result in unexpected results when inserting data pointers accessed
500 * with eina_hash_find(), and removed with eina_hash_del(). Key
501 * strings are case sensitive. If an error occurs, eina_error_get()
502 * should be used to determine if an allocation error occurred during
503 * this function. This function returns #EINA_FALSE if an error
504 * occurred, #EINA_TRUE otherwise.
505 */
506EAPI Eina_Bool eina_hash_add(Eina_Hash *hash,
507 const void *key,
508 const void *data) EINA_ARG_NONNULL(1, 2, 3);
509
510/**
511 * @brief Add an entry to the given hash table without duplicating the string
512 * key.
513 *
514 * @param hash The given hash table. Cannot be @c NULL.
515 * @param key A unique key. Cannot be @c NULL.
516 * @param data Data to associate with the string given by @p key. Cannot be @c
517 * NULL
518 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
519 *
520 * This function adds @p key to @p hash. @p key is
521 * expected to be unique within the hash table. Key uniqueness varies
522 * depending on the type of @p hash: a stringshared @ref Eina_Hash
523 * need have unique pointers (which implies unique strings).
524 * All other string hash types require the strings
525 * themselves to be unique. Pointer, int32 and int64 hashes need to have these
526 * values as unique. Failure to use sufficient uniqueness will
527 * result in unexpected results when inserting data pointers accessed
528 * with eina_hash_find(), and removed with eina_hash_del(). This
529 * function does not make a copy of @p key, so it must be a string
530 * constant or stored elsewhere ( in the object being added). Key
531 * strings are case sensitive. If an error occurs, eina_error_get()
532 * should be used to determine if an allocation error occurred during
533 * this function. This function returns #EINA_FALSE if an error
534 * occurred, #EINA_TRUE otherwise.
535 */
536EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash,
537 const void *key,
538 const void *data) EINA_ARG_NONNULL(1, 2, 3);
539
540/**
541 * @brief Remove the entry identified by a key or a data from the given
542 * hash table.
543 *
544 * @param hash The given hash table.
545 * @param key The key.
546 * @param data The data pointer to remove if the key is @c NULL.
547 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
548 *
549 * This function removes the entry identified by @p key or @p data
550 * from @p hash. If a free function was given to the
551 * callback on creation, it will be called for the data being
552 * deleted. If @p hash is @c NULL, the functions returns immediately
553 * #EINA_FALSE. If @p key is @c NULL, then @p data is used to find the a
554 * match to remove, otherwise @p key is used and @p data is not
555 * required and can be @c NULL. This function returns #EINA_FALSE if
556 * an error occurred, #EINA_TRUE otherwise.
557 *
558 * @note if you know you already have the key, use
559 * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
560 * know you don't have the key, use eina_hash_del_by_data()
561 * directly.
562 */
563EAPI Eina_Bool eina_hash_del(Eina_Hash *hash,
564 const void *key,
565 const void *data) EINA_ARG_NONNULL(1);
566
567/**
568 * @brief Retrieve a specific entry in the given hash table.
569 *
570 * @param hash The given hash table.
571 * @param key The key of the entry to find.
572 * @return The data pointer for the stored entry on success, @c NULL
573 * otherwise.
574 *
575 * This function retrieves the entry associated to @p key in
576 * @p hash. If @p hash is @c NULL, this function returns immediately
577 * @c NULL. This function returns the data pointer on success, @c NULL
578 * otherwise.
579 */
580EAPI void *eina_hash_find(const Eina_Hash *hash,
581 const void *key) EINA_ARG_NONNULL(2);
582
583/**
584 * @brief Modify the entry pointer at the specified key and return the old
585 * entry.
586 * @param hash The given hash table.
587 * @param key The key of the entry to modify.
588 * @param data The data to replace the old entry.
589 * @return The data pointer for the old stored entry on success, or
590 * @c NULL otherwise.
591 *
592 * This function modifies the data of @p key with @p data in @p
593 * hash. If no entry is found, nothing is added to @p hash. On success
594 * this function returns the old entry, otherwise it returns @c NULL.
595 */
596EAPI void *eina_hash_modify(Eina_Hash *hash,
597 const void *key,
598 const void *data) EINA_ARG_NONNULL(1, 2, 3);
599
600/**
601 * @brief Modify the entry pointer at the specified key and return the
602 * old entry or add the entry if not found.
603 *
604 * @param hash The given hash table.
605 * @param key The key of the entry to modify.
606 * @param data The data to replace the old entry
607 * @return The data pointer for the old stored entry, or @c NULL
608 * otherwise.
609 *
610 * This function modifies the data of @p key with @p data in @p
611 * hash. If no entry is found, @p data is added to @p hash with the
612 * key @p key. On success this function returns the old entry,
613 * otherwise it returns @c NULL. To check for errors, use
614 * eina_error_get().
615 */
616EAPI void *eina_hash_set(Eina_Hash *hash,
617 const void *key,
618 const void *data) EINA_ARG_NONNULL(1, 2);
619
620/**
621 * @brief Change the key associated with a data without triggering the
622 * free callback.
623 *
624 * @param hash The given hash table.
625 * @param old_key The current key associated with the data
626 * @param new_key The new key to associate data with
627 * @return EINA_FALSE in any case but success, EINA_TRUE on success.
628 *
629 * This function allows for the move of data from one key to another,
630 * but does not call the Eina_Free_Cb associated with the hash table
631 * when destroying the old key.
632 */
633EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
634 const void *old_key,
635 const void *new_key) EINA_ARG_NONNULL(1, 2, 3);
636
637/**
638 * Free the given hash table resources.
639 *
640 * @param hash The hash table to be freed.
641 *
642 * This function frees up all the memory allocated to storing @p hash,
643 * and call the free callback if it has been passed to the hash table
644 * at creation time. If no free callback has been passed, any entries
645 * in the table that the program has no more pointers for elsewhere
646 * may now be lost, so this should only be called if the program has
647 * already freed any allocated data in the hash table or has the
648 * pointers for data in the table stored elsewhere as well. If @p hash
649 * is @c NULL, the function returns immediately.
650 *
651 * Example:
652 * @code
653 * extern Eina_Hash *hash;
654 *
655 * eina_hash_free(hash);
656 * hash = NULL;
657 * @endcode
658 */
659EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
660
661/**
662 * Free the given hash table buckets resources.
663 *
664 * @param hash The hash table whose buckets have to be freed.
665 *
666 * This function frees up all the memory allocated to storing the
667 * buckets of @p hash, and calls the free callback on all hash table
668 * buckets if it has been passed to the hash table at creation time,
669 * then frees the buckets. If no free callback has been passed, no
670 * buckets value will be freed. If @p hash is @c NULL, the function
671 * returns immediately.
672 */
673EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
674
675/**
676 * @brief Returns the number of entries in the given hash table.
677 *
678 * @param hash The given hash table.
679 * @return The number of entries in the hash table.
680 *
681 * This function returns the number of entries in @p hash, or 0 on
682 * error. If @p hash is @c NULL, 0 is returned.
683 */
684EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
685
686/**
687 * @brief Add an entry to the given hash table.
688 *
689 * @param hash The given hash table. Cannot be @c NULL.
690 * @param key A unique key. Cannot be @c NULL.
691 * @param key_length The length of the key.
692 * @param key_hash The hash that will always match key.
693 * @param data The data to associate with the string given by the key. Cannot be
694 * @c NULL.
695 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
696 *
697 * This function adds @p key to @p hash. @p hash, @p key and @p data
698 * cannot be @c NULL, in that case #EINA_FALSE is returned. @p key is
699 * expected to be a unique within the hash table. Otherwise,
700 * one cannot be sure which inserted data pointer will be accessed
701 * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do
702 * not forget to count '\\0' for string when setting the value of
703 * @p key_length. @p key_hash is expected to always match
704 * @p key. Otherwise, one cannot be sure to find it again with @ref
705 * eina_hash_find_by_hash. Key strings are case sensitive. If an error
706 * occurs, eina_error_get() should be used to determine if an
707 * allocation error occurred during this function. This function
708 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
709 *
710 * @see eina_hash_add()
711 */
712EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash,
713 const void *key,
714 int key_length,
715 int key_hash,
716 const void *data) EINA_ARG_NONNULL(1, 2, 5);
717
718/**
719 * @brief Add an entry to the given hash table and do not duplicate the string
720 * key.
721 *
722 * @param hash The given hash table. Cannot be @c NULL.
723 * @param key A unique key. Cannot be @c NULL.
724 * @param key_length Should be the length of @p key (don't forget to count
725 * '\\0' for string).
726 * @param key_hash The hash that will always match key.
727 * @param data Data to associate with the string given by @p key. Cannot be @c
728 * NULL.
729 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
730 *
731 * This function adds @p key to @p hash. @p hash, @p key and @p data
732 * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
733 * expected to be unique within the hash table. Otherwise,
734 * one cannot be sure which inserted data pointer will be accessed
735 * with @ref eina_hash_find, and removed with @ref eina_hash_del. This
736 * function does not make a copy of @p key so it must be a string
737 * constant or stored elsewhere (in the object being added). Do
738 * not forget to count '\\0' for string when setting the value of
739 * @p key_length. @p key_hash is expected to always match
740 * @p key. Otherwise, one cannot be sure to find it again with @ref
741 * eina_hash_find_by_hash. Key strings are case sensitive. If an error
742 * occurs, eina_error_get() should be used to determine if an
743 * allocation error occurred during this function. This function
744 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
745 *
746 * @see eina_hash_direct_add()
747 */
748EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
749 const void *key,
750 int key_length,
751 int key_hash,
752 const void *data) EINA_ARG_NONNULL(1, 2, 5);
753
754/**
755 * @brief Remove the entry identified by a key and a key hash from the given
756 * hash table.
757 *
758 * @param hash The given hash table. Cannot be @c NULL.
759 * @param key The key. Cannot be @c NULL.
760 * @param key_length The length of the key.
761 * @param key_hash The hash that always match the key.
762 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
763 *
764 * This function removes the entry identified by @p key and
765 * @p key_hash from @p hash. If a free function was given to the
766 * callback on creation, it will be called for the data being
767 * deleted. Do not forget to count '\\0' for string when setting the
768 * value of @p key_length. If @p hash or @p key are @c NULL, the
769 * functions returns immediately #EINA_FALSE. This function returns
770 * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
771 *
772 * @note if you don't have the key_hash, use eina_hash_del_by_key() instead.
773 * @note if you don't have the key, use eina_hash_del_by_data() instead.
774 */
775EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
776 const void *key,
777 int key_length,
778 int key_hash) EINA_ARG_NONNULL(1, 2);
779
780/**
781 * @brief Remove the entry identified by a key from the given hash table.
782 *
783 * This version will calculate key length and hash by using functions
784 * provided to hash creation function.
785 *
786 * @param hash The given hash table. Cannot be @c NULL.
787 * @param key The key. Cannot be @c NULL.
788 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
789 *
790 * This function removes the entry identified by @p key from @p
791 * hash. The key length and hash will be calculated automatically by
792 * using functiond provided to has creation function. If a free
793 * function was given to the callback on creation, it will be called
794 * for the data being deleted. If @p hash or @p key are @c NULL, the
795 * functions returns immediately #EINA_FALSE. This function returns
796 * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
797 *
798 * @note if you already have the key_hash, use eina_hash_del_by_key_hash()
799 * instead.
800 * @note if you don't have the key, use eina_hash_del_by_data() instead.
801 */
802EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
803 const void *key) EINA_ARG_NONNULL(1, 2);
804
805/**
806 * @brief Remove the entry identified by a data from the given hash table.
807 *
808 * This version is slow since there is no quick access to nodes based on data.
809 *
810 * @param hash The given hash table. Cannot be @c NULL.
811 * @param data The data value to search and remove. Cannot be @c NULL.
812 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
813 * thing goes fine.
814 *
815 * This function removes the entry identified by @p data from @p
816 * hash. If a free function was given to the callback on creation, it
817 * will be called for the data being deleted. If @p hash or @p data
818 * are @c NULL, the functions returns immediately #EINA_FALSE. This
819 * function returns #EINA_FALSE if an error occurred, #EINA_TRUE
820 * otherwise.
821 *
822 * @note if you already have the key, use eina_hash_del_by_key() or
823 * eina_hash_del_by_key_hash() instead.
824 */
825EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
826 const void *data) EINA_ARG_NONNULL(1, 2);
827
828/**
829 * @brief Remove the entry identified by a key and a key hash or a
830 * data from the given hash table.
831 *
832 * If @p key is @c NULL, then @p data is used to find a match to
833 * remove.
834 *
835 * @param hash The given hash table. Cannot be @c NULL.
836 * @param key The key.
837 * @param key_length The length of the key.
838 * @param key_hash The hash that always match the key.
839 * @param data The data pointer to remove if the key is @c NULL.
840 * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
841 *
842 * This function removes the entry identified by @p key and
843 * @p key_hash, or @p data, from @p hash. If a free function was given to
844 * the callback on creation, it will be called for the data being
845 * deleted. If @p hash is @c NULL, the functions returns immediately
846 * #EINA_FALSE. If @p key is @c NULL, then @p key_length and @p key_hash
847 * are ignored and @p data is used to find a match to remove,
848 * otherwise @p key and @p key_hash are used and @p data is not
849 * required and can be @c NULL. Do not forget to count '\\0' for
850 * string when setting the value of @p key_length. This function
851 * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
852 *
853 * @note if you know you already have the key, use eina_hash_del_by_key_hash(),
854 * if you know you don't have the key, use eina_hash_del_by_data()
855 * directly.
856 */
857EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
858 const void *key,
859 int key_length,
860 int key_hash,
861 const void *data) EINA_ARG_NONNULL(1);
862
863/**
864 * @brief Retrieve a specific entry in the given hash table.
865 *
866 * @param hash The given hash table. Cannot be @c NULL.
867 * @param key The key of the entry to find.
868 * @param key_length The length of the key.
869 * @param key_hash The hash that always match the key
870 * @return The data pointer for the stored entry on success, @c NULL
871 * otherwise.
872 *
873 * This function retrieves the entry associated to @p key of length
874 * @p key_length in @p hash. @p key_hash is the hash that always match
875 * @p key. It is ignored if @p key is @c NULL. Do not forget to count
876 * '\\0' for string when setting the value of @p key_length. If
877 * @p hash is @c NULL, this function returns immediately @c NULL. This
878 * function returns the data pointer on success, @c NULL otherwise.
879 */
880EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
881 const void *key,
882 int key_length,
883 int key_hash) EINA_ARG_NONNULL(1, 2);
884
885/**
886 * @brief Modify the entry pointer at the specified key and returns
887 * the old entry.
888 *
889 * @param hash The given hash table.
890 * @param key The key of the entry to modify.
891 * @param key_length Should be the length of @p key (don't forget to count
892 * '\\0' for string).
893 * @param key_hash The hash that always match the key. Ignored if @p key is
894 * @c NULL.
895 * @param data The data to replace the old entry, if it exists.
896 * @return The data pointer for the old stored entry, or @c NULL if not
897 * found. If an existing entry is not found, nothing is added to the
898 * hash.
899 */
900EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
901 const void *key,
902 int key_length,
903 int key_hash,
904 const void *data) EINA_ARG_NONNULL(1, 2, 5);
905
906/**
907 * @brief Returned a new iterator associated to hash keys.
908 *
909 * @param hash The hash.
910 * @return A new iterator.
911 *
912 * This function returns a newly allocated iterator associated to @p
913 * hash. If @p hash is not populated, this function still returns a
914 * valid iterator that will always return false on
915 * eina_iterator_next(), thus keeping API sane.
916 *
917 * If the memory can not be allocated, NULL is returned and
918 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
919 * returned.
920 *
921 * @warning if the hash structure changes then the iterator becomes
922 * invalid! That is, if you add or remove items this iterator
923 * behavior is undefined and your program may crash!
924 */
925EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
926
927/**
928 * @brief Returned a new iterator associated to hash data.
929 *
930 * @param hash The hash.
931 * @return A new iterator.
932 *
933 * This function returns a newly allocated iterator associated to
934 * @p hash. If @p hash is not populated, this function still returns a
935 * valid iterator that will always return false on
936 * eina_iterator_next(), thus keeping API sane.
937 *
938 * If the memory can not be allocated, @c NULL is returned and
939 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
940 * returned.
941 *
942 * @warning if the hash structure changes then the iterator becomes
943 * invalid. That is, if you add or remove items this iterator behavior
944 * is undefined and your program may crash.
945 */
946EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
947
948/**
949 * @brief Returned a new iterator associated to hash keys and data.
950 *
951 * @param hash The hash.
952 * @return A new iterator.
953 *
954 * This function returns a newly allocated iterator associated to @p
955 * hash. If @p hash is not populated, this function still returns a
956 * valid iterator that will always return false on
957 * eina_iterator_next(), thus keeping API sane.
958 *
959 * If the memory can not be allocated, NULL is returned and
960 * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
961 * returned.
962 *
963 * @note iterator data will provide values as Eina_Hash_Tuple that should not
964 * be modified!
965 *
966 * @warning if the hash structure changes then the iterator becomes
967 * invalid! That is, if you add or remove items this iterator
968 * behavior is undefined and your program may crash!
969 */
970EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
971
972/**
973 * @brief Call a function on every member stored in the hash table
974 *
975 * @param hash The hash table whose members will be walked
976 * @param func The function to call on each parameter
977 * @param fdata The data pointer to pass to the function being called
978 *
979 * This function goes through every entry in the hash table @p hash and calls
980 * the function @p func on each member. The function should @b not modify the
981 * hash table contents if it returns 1. @b If the hash table contents are
982 * modified by this function or the function wishes to stop processing it must
983 * return 0, otherwise return 1 to keep processing.
984 *
985 * Example:
986 * @code
987 * extern Eina_Hash *hash;
988 *
989 * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key,
990 * void *data, void *fdata)
991 * {
992 * printf("Func data: %s, Hash entry: %s / %p\n",
993 * fdata, (const char *)key, data);
994 * return 1;
995 * }
996 *
997 * int main(int argc, char **argv)
998 * {
999 * char *hash_fn_data;
1000 *
1001 * hash_fn_data = strdup("Hello World");
1002 * eina_hash_foreach(hash, hash_fn, hash_fn_data);
1003 * free(hash_fn_data);
1004 * }
1005 * @endcode
1006 */
1007EAPI void eina_hash_foreach(const Eina_Hash *hash,
1008 Eina_Hash_Foreach func,
1009 const void *fdata) EINA_ARG_NONNULL(1, 2);
1010/* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */
1011EAPI int eina_hash_superfast(const char *key,
1012 int len) EINA_ARG_NONNULL(1);
1013/* Hash function first reported by dan bernstein many years ago in comp.lang.c */
1014static inline int eina_hash_djb2(const char *key,
1015 int len) EINA_ARG_NONNULL(1);
1016static inline int eina_hash_djb2_len(const char *key,
1017 int *plen) EINA_ARG_NONNULL(1, 2);
1018/* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */
1019static inline int eina_hash_int32(const unsigned int *pkey,
1020 int len) EINA_ARG_NONNULL(1);
1021static inline int eina_hash_int64(const unsigned long int *pkey,
1022 int len) EINA_ARG_NONNULL(1);
1023/* http://sites.google.com/site/murmurhash/ */
1024static inline int eina_hash_murmur3(const char *key,
1025 int len) EINA_ARG_NONNULL(1);
1026#include "eina_inline_hash.x"
1027
1028/**
1029 * @}
1030 */
1031
1032/**
1033 * @}
1034 */
1035
1036/**
1037 * @}
1038 */
1039
1040#endif /*EINA_HASH_H_*/
generated by cgit v1.1 at 2024-08-27 21:20:52 +0000