diff options
author | David Walter Seikel | 2013-01-13 17:29:19 +1000 |
---|---|---|
committer | David Walter Seikel | 2013-01-13 17:29:19 +1000 |
commit | 07274513e984f0b5544586c74508ccd16e7dcafa (patch) | |
tree | b32ff2a9136fbc1a4a6a0ed1e4d79cde0f5f16d9 /libraries/eina/src/include/eina_list.h | |
parent | Added Irrlicht 1.8, but without all the Windows binaries. (diff) | |
download | SledjHamr-07274513e984f0b5544586c74508ccd16e7dcafa.zip SledjHamr-07274513e984f0b5544586c74508ccd16e7dcafa.tar.gz SledjHamr-07274513e984f0b5544586c74508ccd16e7dcafa.tar.bz2 SledjHamr-07274513e984f0b5544586c74508ccd16e7dcafa.tar.xz |
Remove EFL, since it's been released now.
Diffstat (limited to 'libraries/eina/src/include/eina_list.h')
-rw-r--r-- | libraries/eina/src/include/eina_list.h | 1631 |
1 files changed, 0 insertions, 1631 deletions
diff --git a/libraries/eina/src/include/eina_list.h b/libraries/eina/src/include/eina_list.h deleted file mode 100644 index c8ef06d..0000000 --- a/libraries/eina/src/include/eina_list.h +++ /dev/null | |||
@@ -1,1631 +0,0 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2002-2008 Carsten Haitzler, Vincent Torri, Jorge Luis Zapata Muga | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_LIST_H_ | ||
20 | #define EINA_LIST_H_ | ||
21 | |||
22 | #include <stdlib.h> | ||
23 | |||
24 | #include "eina_config.h" | ||
25 | |||
26 | #include "eina_types.h" | ||
27 | #include "eina_iterator.h" | ||
28 | #include "eina_accessor.h" | ||
29 | #include "eina_magic.h" | ||
30 | |||
31 | /** | ||
32 | * @page eina_list_01_example_page Adding elements to Eina_List | ||
33 | * @dontinclude eina_list_01.c | ||
34 | * | ||
35 | * Creating an @ref Eina_List and adding elements to it is very easy and can be | ||
36 | * understood from an example: | ||
37 | * First thing is always to include Eina.h, for this example we also | ||
38 | * include stdio.h so we can use printf. | ||
39 | * @skip #include | ||
40 | * @until Eina.h | ||
41 | * | ||
42 | * Just some boilerplate code, declaring some variable and initializing eina. | ||
43 | * @until eina_init | ||
44 | * Here we add a sequence of elements to our list. By using append we add | ||
45 | * elements to the end of the list, so the list will look like this:@n | ||
46 | * @htmlonly | ||
47 | * <img src="eina_list_example_01_a.png" style="max-width: 100%;" /> | ||
48 | * <a href="eina_list_example_01_a.png">Full-size</a> | ||
49 | * @endhtmlonly | ||
50 | * @image rtf eina_list_example_01_a.png | ||
51 | * @image latex eina_list_example_01_a.eps width=\textwidth | ||
52 | * @until roslin | ||
53 | * There are a couple of interesting things happening here, first is that we are | ||
54 | * passing a NULL pointer to the first @ref eina_list_append() call, when this | ||
55 | * is done a list is created. The other @b very important detail to notice is | ||
56 | * that the return value is attributed to the @a list variable, this needs to | ||
57 | * be done every time we use a a function that alters the contents of the list. | ||
58 | * | ||
59 | * Now that we have a list we some elements in it we can look at it's contents. | ||
60 | * @until printf | ||
61 | * | ||
62 | * There are many ways of accessing elements in the list, including by it's | ||
63 | * index: | ||
64 | * @until nth | ||
65 | * @note It should be noted that the index starts at 0. | ||
66 | * | ||
67 | * @ref eina_list_append() is not the only way to add elements to a a list. A | ||
68 | * common requirement is to add an element in a specific position this can be | ||
69 | * accomplished using @ref eina_list_append_relative() and | ||
70 | * @ref eina_list_append_relative_list(): | ||
71 | * @until zarek | ||
72 | * First @a "cain" is added after the second element(remember that indexes are | ||
73 | * 0 based) and then we add @a "zarek" after @a "cain". | ||
74 | * | ||
75 | * @ref Eina_List also has prepend analogs to append functions we have used so | ||
76 | * far: | ||
77 | * @until lampkin | ||
78 | * With this additions our list now looks like this:@n | ||
79 | * @htmlonly | ||
80 | * <img src="eina_list_example_01_b.png" style="max-width: 100%;" /> | ||
81 | * <a href="eina_list_example_01_b.png">Full-size</a> | ||
82 | * @endhtmlonly | ||
83 | * @image rtf eina_list_example_01_b.png | ||
84 | * @image latex eina_list_example_01_b.eps width=\textwidth | ||
85 | * | ||
86 | * Once done using the list it needs to be freed, and since we are done with | ||
87 | * eina that also need to be shutdown: | ||
88 | * @until } | ||
89 | * | ||
90 | * The full source code can be found on the examples folder | ||
91 | * on the @ref eina_list_01_c "eina_list_01.c" file. | ||
92 | */ | ||
93 | |||
94 | /** | ||
95 | * @page eina_list_01_c Adding elements to Eina_List example | ||
96 | * | ||
97 | * @include eina_list_01.c | ||
98 | * @example eina_list_01.c | ||
99 | */ | ||
100 | |||
101 | /** | ||
102 | * @page eina_list_02_example_page Sorting Eina_List elements | ||
103 | * @dontinclude eina_list_02.c | ||
104 | * | ||
105 | * If you don't know how to create lists see | ||
106 | * @ref eina_list_01_example_page. | ||
107 | * | ||
108 | * @skip #include | ||
109 | * @until boomer | ||
110 | * This is the code we have already seen to create a list. Now if we need to | ||
111 | * search the list we can do it like this: | ||
112 | * @until return | ||
113 | * | ||
114 | * However if searching the list multiple times it probably is better to sort | ||
115 | * the list since the sorted_search functions are much faster: | ||
116 | * @until return | ||
117 | * | ||
118 | * Once the list is sorted it's not a good idea to use append/prepend functions | ||
119 | * since that would add the element in the wrong place, instead elements should | ||
120 | * be added with @ref eina_list_sorted_insert(): | ||
121 | * @until sorted_insert | ||
122 | * | ||
123 | * A noteworthy use case is adding an element to a list only if it doesn't exist | ||
124 | * already, this can accomplished by searching for the element that is closest | ||
125 | * to what is being added, and if that doesn't match add: | ||
126 | * @until append | ||
127 | * @note @ref eina_list_search_sorted_near_list() will tell you not only the | ||
128 | * nearest node to what was searched for but how it compares to your term, this | ||
129 | * way it is easy to know if you have to add before or after that node. | ||
130 | * | ||
131 | * It is sometimes useful to get a portion of the list as another list, here we | ||
132 | * take every element that comes after "boomer" and split it into "other_list": | ||
133 | * @until split_list | ||
134 | * | ||
135 | * It is also possible to add entire lists of elements using | ||
136 | * @ref eina_list_sorted_merge(): | ||
137 | * @until sorted_merge | ||
138 | * | ||
139 | * And as always release memory and shutdown eina before ending: | ||
140 | * @until } | ||
141 | * | ||
142 | * The full source code can be found on the examples folder | ||
143 | * on the @ref eina_list_02_c "eina_list_02.c" file. | ||
144 | */ | ||
145 | |||
146 | /** | ||
147 | * @page eina_list_02_c Sorting Eina_List elements example | ||
148 | * | ||
149 | * @include eina_list_02.c | ||
150 | * @example eina_list_02.c | ||
151 | */ | ||
152 | |||
153 | /** | ||
154 | * @page eina_list_03_example_page Reordering Eina_List elments | ||
155 | * @dontinclude eina_list_03.c | ||
156 | * | ||
157 | * If you don't know how to create lists see | ||
158 | * @ref eina_list_01_example_page. | ||
159 | * | ||
160 | * We start out with code that should be familiar by now: | ||
161 | * @skip #include | ||
162 | * @until gemenon | ||
163 | * | ||
164 | * You can move elements around in a list using @ref eina_list_move() or using | ||
165 | * @ref eina_list_promote_list() and @ref eina_list_demote_list() which move a | ||
166 | * list node to the head and end of the list respectevely: | ||
167 | * @until demote | ||
168 | * | ||
169 | * Removing elements from a list can be done with ease: | ||
170 | * @until sagitarius | ||
171 | * | ||
172 | * To replace an element in the list it is not necessary to remove it and then | ||
173 | * add with the new value, it is possible to just change the value of a node: | ||
174 | * @until aquarius | ||
175 | * | ||
176 | * We will now take a peek to see if the list still has the right number of | ||
177 | * elements: | ||
178 | * @until printf | ||
179 | * | ||
180 | * Now that the list is in alphabetical order let's create a copy of it in | ||
181 | * reverse order and print every element to see if worked as expected: | ||
182 | * @until iterator_free | ||
183 | * @note Always remember to free your iterators when done using them. | ||
184 | * | ||
185 | * And as always release memory and shutdown eina before ending: | ||
186 | * @until } | ||
187 | * | ||
188 | * The full source code can be found on the examples folder | ||
189 | * on the @ref eina_list_03_c "eina_list_03.c" file. | ||
190 | */ | ||
191 | |||
192 | /** | ||
193 | * @page eina_list_03_c Reordering Eina_List elments example | ||
194 | * | ||
195 | * @include eina_list_03.c | ||
196 | * @example eina_list_03.c | ||
197 | */ | ||
198 | |||
199 | /** | ||
200 | * @page eina_list_04_example_page Eina_List and memory allocation | ||
201 | * @dontinclude eina_list_04.c | ||
202 | * | ||
203 | * If you don't know how to create lists see | ||
204 | * @ref eina_list_01_example_page. In this example we also use | ||
205 | * @ref Eina_Stringshare_Group, however it should be possible to understand the code | ||
206 | * regardless of previous knowledge about it. | ||
207 | * | ||
208 | * Here we have the usual list creation code with a twist, now we are using as | ||
209 | * data for the list memory that has to be freed later on. | ||
210 | * @skip #include | ||
211 | * @until Sharon | ||
212 | * | ||
213 | * This time we are going to iterate over our list in a different way: | ||
214 | * @until printf | ||
215 | * | ||
216 | * And now we are going to iterate over the list backwards: | ||
217 | * @until printf | ||
218 | * | ||
219 | * And now we need to free up the memory allocated during creation of the list: | ||
220 | * @until stringshare_del | ||
221 | * @note We don't need to use eina_list_free() since @ref EINA_LIST_FREE takes | ||
222 | * care of that. | ||
223 | * | ||
224 | * And shut everything down: | ||
225 | * @until } | ||
226 | * | ||
227 | * The full source code can be found on the examples folder | ||
228 | * on the @ref eina_list_04_c "eina_list_04.c" file. | ||
229 | */ | ||
230 | |||
231 | /** | ||
232 | * @page eina_list_04_c Eina_List and memory allocation example | ||
233 | * | ||
234 | * @include eina_list_04.c | ||
235 | * @example eina_list_04.c | ||
236 | */ | ||
237 | |||
238 | /** | ||
239 | * @addtogroup Eina_List_Group List | ||
240 | * | ||
241 | * @brief These functions provide double linked list management. | ||
242 | * | ||
243 | * Eina_List is a doubly linked list. It can store data of any type in the | ||
244 | * form of void pointers. It has convenience functions to do all the common | ||
245 | * operations which means it should rarely if ever be necessary to directly | ||
246 | * access the struct's fields. Nevertheless it can be useful to understand the | ||
247 | * inner workings of the data structure being used. | ||
248 | * | ||
249 | * @ref Eina_List nodes keep references to the previous node, the next node, its | ||
250 | * data and to an accounting structure. | ||
251 | * | ||
252 | * @htmlonly | ||
253 | * <img src="eina_list.png" style="max-width: 100%;" /> | ||
254 | * <a href="eina_list.png">Full-size</a> | ||
255 | * @endhtmlonly | ||
256 | * @image rtf eina_list.png | ||
257 | * @image latex eina_list.eps width=5cm | ||
258 | * | ||
259 | * @ref Eina_List_Accounting is used to improve the performance of some | ||
260 | * functions. It is private and <b>should not</b> be modified. It contains a | ||
261 | * reference to the end of the list and the number of elements in the list. | ||
262 | * | ||
263 | * @note Every function that modifies the contents of the list returns a pointer | ||
264 | * to the head of the list and it is essential that this be pointer be used in | ||
265 | * any future references to the list. | ||
266 | * | ||
267 | * Most functions have two versions that have the same effect but operate on | ||
268 | * different arguments, the @a plain functions operate over data(eg.: | ||
269 | * @ref eina_list_append_relative, @ref eina_list_remove, | ||
270 | * @ref eina_list_data_find), the @a list versions of these functions operate | ||
271 | * on @ref Eina_List nodes. | ||
272 | * | ||
273 | * @warning You must @b always use the pointer to the first element of the list | ||
274 | * as the list! | ||
275 | * @warning You must @b never use a pointer to an element in the middle of the | ||
276 | * list as the list! | ||
277 | * | ||
278 | * Here are some examples of @ref Eina_List usage: | ||
279 | * @li @ref eina_list_01_example_page | ||
280 | * @li @ref eina_list_02_example_page | ||
281 | * @li @ref eina_list_03_example_page | ||
282 | * @li @ref eina_list_04_example_page | ||
283 | */ | ||
284 | |||
285 | /** | ||
286 | * @addtogroup Eina_Data_Types_Group Data Types | ||
287 | * | ||
288 | * @{ | ||
289 | */ | ||
290 | |||
291 | /** | ||
292 | * @addtogroup Eina_Containers_Group Containers | ||
293 | * | ||
294 | * @{ | ||
295 | */ | ||
296 | |||
297 | /** | ||
298 | * @defgroup Eina_List_Group List | ||
299 | * | ||
300 | * @{ | ||
301 | */ | ||
302 | |||
303 | /** | ||
304 | * @typedef Eina_List | ||
305 | * Type for a generic double linked list. | ||
306 | */ | ||
307 | typedef struct _Eina_List Eina_List; | ||
308 | |||
309 | /** | ||
310 | * @typedef Eina_List_Accounting | ||
311 | * Cache used to store the last element of a list and the number of | ||
312 | * elements, for fast access. | ||
313 | */ | ||
314 | typedef struct _Eina_List_Accounting Eina_List_Accounting; | ||
315 | |||
316 | /** | ||
317 | * @struct _Eina_List | ||
318 | * Type for a generic double linked list. | ||
319 | */ | ||
320 | struct _Eina_List | ||
321 | { | ||
322 | void *data; /**< Pointer to list element payload */ | ||
323 | Eina_List *next; /**< Next member in the list */ | ||
324 | Eina_List *prev; /**< Previous member in the list */ | ||
325 | Eina_List_Accounting *accounting; /**< Private list accounting info - don't touch */ | ||
326 | |||
327 | EINA_MAGIC | ||
328 | }; | ||
329 | |||
330 | /** | ||
331 | * @struct _Eina_List_Accounting | ||
332 | * Cache used to store the last element of a list and the number of | ||
333 | * elements, for fast access. It is for private used and must not be | ||
334 | * touched. | ||
335 | */ | ||
336 | struct _Eina_List_Accounting | ||
337 | { | ||
338 | Eina_List *last; /**< Pointer to the last element of the list - don't touch */ | ||
339 | unsigned int count; /**< Number of elements of the list - don't touch */ | ||
340 | EINA_MAGIC | ||
341 | }; | ||
342 | |||
343 | |||
344 | /** | ||
345 | * @brief Append the given data to the given linked list. | ||
346 | * | ||
347 | * @param list The given list. | ||
348 | * @param data The data to append. | ||
349 | * @return A list pointer. | ||
350 | * | ||
351 | * This function appends @p data to @p list. If @p list is @c NULL, a | ||
352 | * new list is returned. On success, a new list pointer that should be | ||
353 | * used in place of the one given to this function is | ||
354 | * returned. Otherwise, the old pointer is returned. | ||
355 | * | ||
356 | * The following example code demonstrates how to ensure that the | ||
357 | * given data has been successfully appended. | ||
358 | * | ||
359 | * @code | ||
360 | * Eina_List *list = NULL; | ||
361 | * extern void *my_data; | ||
362 | * | ||
363 | * list = eina_list_append(list, my_data); | ||
364 | * if (eina_error_get()) | ||
365 | * { | ||
366 | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | ||
367 | * exit(-1); | ||
368 | * } | ||
369 | * @endcode | ||
370 | * | ||
371 | * @warning @p list must be a pointer to the first element of the list(or NULL). | ||
372 | */ | ||
373 | EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
374 | |||
375 | |||
376 | /** | ||
377 | * @brief Prepends the given data to the given linked list. | ||
378 | * | ||
379 | * @param list The given list. | ||
380 | * @param data The data to prepend. | ||
381 | * @return A list pointer. | ||
382 | * | ||
383 | * This function prepends @p data to @p list. If @p list is @c NULL, a | ||
384 | * new list is returned. On success, a new list pointer that should be | ||
385 | * used in place of the one given to this function is | ||
386 | * returned. Otherwise, the old pointer is returned. | ||
387 | * | ||
388 | * The following example code demonstrates how to ensure that the | ||
389 | * given data has been successfully prepended. | ||
390 | * | ||
391 | * Example: | ||
392 | * @code | ||
393 | * Eina_List *list = NULL; | ||
394 | * extern void *my_data; | ||
395 | * | ||
396 | * list = eina_list_prepend(list, my_data); | ||
397 | * if (eina_error_get()) | ||
398 | * { | ||
399 | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | ||
400 | * exit(-1); | ||
401 | * } | ||
402 | * @endcode | ||
403 | * | ||
404 | * @warning @p list must be a pointer to the first element of the list. | ||
405 | */ | ||
406 | EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
407 | |||
408 | |||
409 | /** | ||
410 | * @brief Insert the given data into the given linked list after the specified data. | ||
411 | * | ||
412 | * @param list The given linked list. | ||
413 | * @param data The data to insert. | ||
414 | * @param relative The data to insert after. | ||
415 | * @return A list pointer. | ||
416 | * | ||
417 | * This function inserts @p data to @p list after @p relative. If | ||
418 | * @p relative is not in the list, @p data is appended to the end of | ||
419 | * the list. If @p list is @c NULL, a new list is returned. If there | ||
420 | * are multiple instances of @p relative in the list, @p data is | ||
421 | * inserted after the first instance.On success, a new list pointer | ||
422 | * that should be used in place of the one given to this function is | ||
423 | * returned. Otherwise, the old pointer is returned. | ||
424 | * | ||
425 | * The following example code demonstrates how to ensure that the | ||
426 | * given data has been successfully inserted. | ||
427 | * | ||
428 | * @code | ||
429 | * Eina_List *list = NULL; | ||
430 | * extern void *my_data; | ||
431 | * extern void *relative_member; | ||
432 | * | ||
433 | * list = eina_list_append(list, relative_member); | ||
434 | * if (eina_error_get()) | ||
435 | * { | ||
436 | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | ||
437 | * exit(-1); | ||
438 | * } | ||
439 | * list = eina_list_append_relative(list, my_data, relative_member); | ||
440 | * if (eina_error_get()) | ||
441 | * { | ||
442 | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | ||
443 | * exit(-1); | ||
444 | * } | ||
445 | * @endcode | ||
446 | * | ||
447 | * @warning @p list must be a pointer to the first element of the list. | ||
448 | */ | ||
449 | EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
450 | |||
451 | |||
452 | /** | ||
453 | * @brief Append a list node to a linked list after the specified member | ||
454 | * | ||
455 | * @param list The given linked list. | ||
456 | * @param data The data to insert. | ||
457 | * @param relative The list node to insert after. | ||
458 | * @return A list pointer. | ||
459 | * | ||
460 | * This function inserts @p data to @p list after the list node | ||
461 | * @p relative. If @p list or @p relative are @c NULL, @p data is just | ||
462 | * appended to @p list using eina_list_append(). If @p list is | ||
463 | * @c NULL, a new list is returned. If there are multiple instances | ||
464 | * of @p relative in the list, @p data is inserted after the first | ||
465 | * instance. On success, a new list pointer that should be used in | ||
466 | * place of the one given to this function is returned. Otherwise, the | ||
467 | * old pointer is returned. | ||
468 | * | ||
469 | * @warning @p list must be a pointer to the first element of the list. | ||
470 | */ | ||
471 | EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
472 | |||
473 | |||
474 | /** | ||
475 | * @brief Prepend a data pointer to a linked list before the specified member | ||
476 | * | ||
477 | * @param list The given linked list. | ||
478 | * @param data The data to insert. | ||
479 | * @param relative The data to insert before. | ||
480 | * @return A list pointer. | ||
481 | * | ||
482 | * This function inserts @p data to @p list before @p relative. If | ||
483 | * @p relative is not in the list, @p data is prepended to the list | ||
484 | * with eina_list_prepend(). If @p list is @c NULL, a new list is | ||
485 | * returned. If there are multiple instances of @p relative in the | ||
486 | * list, @p data is inserted before the first instance. On success, a | ||
487 | * new list pointer that should be used in place of the one given to | ||
488 | * this function is returned. Otherwise, the old pointer is returned. | ||
489 | * | ||
490 | * The following code example demonstrates how to ensure that the | ||
491 | * given data has been successfully inserted. | ||
492 | * | ||
493 | * @code | ||
494 | * Eina_List *list = NULL; | ||
495 | * extern void *my_data; | ||
496 | * extern void *relative_member; | ||
497 | * | ||
498 | * list = eina_list_append(list, relative_member); | ||
499 | * if (eina_error_get_error()) | ||
500 | * { | ||
501 | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | ||
502 | * exit(-1); | ||
503 | * } | ||
504 | * list = eina_list_prepend_relative(list, my_data, relative_member); | ||
505 | * if (eina_error_get()) | ||
506 | * { | ||
507 | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | ||
508 | * exit(-1); | ||
509 | * } | ||
510 | * @endcode | ||
511 | * | ||
512 | * @warning @p list must be a pointer to the first element of the list. | ||
513 | */ | ||
514 | EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
515 | |||
516 | |||
517 | /** | ||
518 | * @brief Prepend a list node to a linked list before the specified member | ||
519 | * | ||
520 | * @param list The given linked list. | ||
521 | * @param data The data to insert. | ||
522 | * @param relative The list node to insert before. | ||
523 | * @return A list pointer. | ||
524 | * | ||
525 | * This function inserts @p data to @p list before the list node | ||
526 | * @p relative. If @p list or @p relative are @c NULL, @p data is just | ||
527 | * prepended to @p list using eina_list_prepend(). If @p list is | ||
528 | * @c NULL, a new list is returned. If there are multiple instances | ||
529 | * of @p relative in the list, @p data is inserted before the first | ||
530 | * instance. On success, a new list pointer that should be used in | ||
531 | * place of the one given to this function is returned. Otherwise, the | ||
532 | * old pointer is returned. | ||
533 | * | ||
534 | * @warning @p list must be a pointer to the first element of the list. | ||
535 | */ | ||
536 | EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
537 | |||
538 | |||
539 | /** | ||
540 | * @brief Insert a new node into a sorted list. | ||
541 | * | ||
542 | * @param list The given linked list, @b must be sorted. | ||
543 | * @param func The function called for the sort. | ||
544 | * @param data The data to insert sorted. | ||
545 | * @return A list pointer. | ||
546 | * | ||
547 | * This function inserts values into a linked list assuming it was | ||
548 | * sorted and the result will be sorted. If @p list is @c NULLL, a new | ||
549 | * list is returned. On success, a new list pointer that should be | ||
550 | * used in place of the one given to this function is | ||
551 | * returned. Otherwise, the old pointer is returned. See eina_error_get(). | ||
552 | * | ||
553 | * @note O(log2(n)) comparisons (calls to @p func) average/worst case | ||
554 | * performance as it uses eina_list_search_sorted_near_list() and thus | ||
555 | * is bounded to that. As said in eina_list_search_sorted_near_list(), | ||
556 | * lists do not have O(1) access time, so walking to the correct node | ||
557 | * can be costly, consider worst case to be almost O(n) pointer | ||
558 | * dereference (list walk). | ||
559 | * | ||
560 | * @warning @p list must be a pointer to the first element of the list. | ||
561 | */ | ||
562 | EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare_Cb func, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; | ||
563 | |||
564 | |||
565 | /** | ||
566 | * @brief Remove the first instance of the specified data from the given list. | ||
567 | * | ||
568 | * @param list The given list. | ||
569 | * @param data The specified data. | ||
570 | * @return A list pointer. | ||
571 | * | ||
572 | * This function removes the first instance of @p data from | ||
573 | * @p list. If the specified data is not in the given list (tihis | ||
574 | * include the case where @p data is @c NULL), nothing is done. If | ||
575 | * @p list is @c NULL, @c NULL is returned, otherwise a new list | ||
576 | * pointer that should be used in place of the one passed to this | ||
577 | * function. | ||
578 | * | ||
579 | * @warning @p list must be a pointer to the first element of the list. | ||
580 | */ | ||
581 | EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
582 | |||
583 | |||
584 | /** | ||
585 | * @brief Remove the specified list node. | ||
586 | * | ||
587 | * @param list The given linked list. | ||
588 | * @param remove_list The list node which is to be removed. | ||
589 | * @return A list pointer. | ||
590 | * | ||
591 | * This function removes the list node @p remove_list from @p list and | ||
592 | * frees the list node structure @p remove_list. If @p list is | ||
593 | * @c NULL, this function returns @c NULL. If @p remove_list is | ||
594 | * @c NULL, it returns @p list, otherwise, a new list pointer that | ||
595 | * should be used in place of the one passed to this function. | ||
596 | * | ||
597 | * The following code gives an example (notice we use EINA_LIST_FOREACH | ||
598 | * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after | ||
599 | * removing the current node). | ||
600 | * | ||
601 | * @code | ||
602 | * extern Eina_List *list; | ||
603 | * Eina_List *l; | ||
604 | * extern void *my_data; | ||
605 | * void *data | ||
606 | * | ||
607 | * EINA_LIST_FOREACH(list, l, data) | ||
608 | * { | ||
609 | * if (data == my_data) | ||
610 | * { | ||
611 | * list = eina_list_remove_list(list, l); | ||
612 | * break; | ||
613 | * } | ||
614 | * } | ||
615 | * @endcode | ||
616 | * | ||
617 | * @warning @p list must be a pointer to the first element of the list. | ||
618 | */ | ||
619 | EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
620 | |||
621 | |||
622 | /** | ||
623 | * @brief Move the specified data to the head of the list. | ||
624 | * | ||
625 | * @param list The list handle to move the data. | ||
626 | * @param move_list The list node to move. | ||
627 | * @return A new list handle to replace the old one | ||
628 | * | ||
629 | * This function move @p move_list to the front of @p list. If list is | ||
630 | * @c NULL, @c NULL is returned. If @p move_list is @c NULL, | ||
631 | * @p list is returned. Otherwise, a new list pointer that should be | ||
632 | * used in place of the one passed to this function. | ||
633 | * | ||
634 | * Example: | ||
635 | * @code | ||
636 | * extern Eina_List *list; | ||
637 | * Eina_List *l; | ||
638 | * extern void *my_data; | ||
639 | * void *data; | ||
640 | * | ||
641 | * EINA_LIST_FOREACH(list, l, data) | ||
642 | * { | ||
643 | * if (data == my_data) | ||
644 | * { | ||
645 | * list = eina_list_promote_list(list, l); | ||
646 | * break; | ||
647 | * } | ||
648 | * } | ||
649 | * @endcode | ||
650 | * | ||
651 | * @warning @p list must be a pointer to the first element of the list. | ||
652 | */ | ||
653 | EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
654 | |||
655 | |||
656 | /** | ||
657 | * @brief Move the specified data to the tail of the list. | ||
658 | * | ||
659 | * @param list The list handle to move the data. | ||
660 | * @param move_list The list node to move. | ||
661 | * @return A new list handle to replace the old one | ||
662 | * | ||
663 | * This function move @p move_list to the back of @p list. If list is | ||
664 | * @c NULL, @c NULL is returned. If @p move_list is @c NULL, | ||
665 | * @p list is returned. Otherwise, a new list pointer that should be | ||
666 | * used in place of the one passed to this function. | ||
667 | * | ||
668 | * Example: | ||
669 | * @code | ||
670 | * extern Eina_List *list; | ||
671 | * Eina_List *l; | ||
672 | * extern void *my_data; | ||
673 | * void *data; | ||
674 | * | ||
675 | * EINA_LIST_FOREACH(list, l, data) | ||
676 | * { | ||
677 | * if (data == my_data) | ||
678 | * { | ||
679 | * list = eina_list_demote_list(list, l); | ||
680 | * break; | ||
681 | * } | ||
682 | * } | ||
683 | * @endcode | ||
684 | * | ||
685 | * @warning @p list must be a pointer to the first element of the list. | ||
686 | */ | ||
687 | EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *move_list); | ||
688 | |||
689 | |||
690 | /** | ||
691 | * @brief Find a member of a list and return the member. | ||
692 | * | ||
693 | * @param list The list to search for a data. | ||
694 | * @param data The data pointer to find in the list. | ||
695 | * @return The found member data pointer if found, @c NULL otherwise. | ||
696 | * | ||
697 | * This function searches in @p list from beginning to end for the | ||
698 | * first member whose data pointer is @p data. If it is found, @p data | ||
699 | * will be returned, otherwise NULL will be returned. | ||
700 | * | ||
701 | * Example: | ||
702 | * @code | ||
703 | * extern Eina_List *list; | ||
704 | * extern void *my_data; | ||
705 | * | ||
706 | * if (eina_list_data_find(list, my_data) == my_data) | ||
707 | * { | ||
708 | * printf("Found member %p\n", my_data); | ||
709 | * } | ||
710 | * @endcode | ||
711 | * | ||
712 | * @warning @p list must be a pointer to the first element of the list. | ||
713 | */ | ||
714 | EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
715 | |||
716 | /** | ||
717 | * @brief Find a member of a list and return the list node containing that member. | ||
718 | * | ||
719 | * @param list The list to search for data. | ||
720 | * @param data The data pointer to find in the list. | ||
721 | * @return The found members list node on success, @c NULL otherwise. | ||
722 | * | ||
723 | * This function searches in @p list from beginning to end for the | ||
724 | * first member whose data pointer is @p data. If it is found, the | ||
725 | * list node containing the specified member is returned, otherwise | ||
726 | * @c NULL is returned. | ||
727 | * | ||
728 | * @warning @p list must be a pointer to the first element of the list. | ||
729 | */ | ||
730 | EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | ||
731 | |||
732 | |||
733 | /** | ||
734 | * @brief Move a data pointer from one list to another | ||
735 | * | ||
736 | * @param to The list to move the data to | ||
737 | * @param from The list to move from | ||
738 | * @param data The data to move | ||
739 | * @return #EINA_TRUE on success, else #EINA_FALSE | ||
740 | * | ||
741 | * This function is a shortcut for doing the following: | ||
742 | * to = eina_list_append(to, data); | ||
743 | * from = eina_list_remove(from, data); | ||
744 | * | ||
745 | * @warning @p list must be a pointer to the first element of the list. | ||
746 | */ | ||
747 | EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data); | ||
748 | |||
749 | /** | ||
750 | * @brief Move a list node from one list to another | ||
751 | * | ||
752 | * @param to The list to move the data to | ||
753 | * @param from The list to move from | ||
754 | * @param data The list node containing the data to move | ||
755 | * @return #EINA_TRUE on success, else #EINA_FALSE | ||
756 | * | ||
757 | * This function is a shortcut for doing the following: | ||
758 | * to = eina_list_append(to, data->data); | ||
759 | * from = eina_list_remove_list(from, data); | ||
760 | * | ||
761 | * @warning @p list must be a pointer to the first element of the list. | ||
762 | */ | ||
763 | EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data); | ||
764 | |||
765 | |||
766 | /** | ||
767 | * @brief Free an entire list and all the nodes, ignoring the data contained. | ||
768 | |||
769 | * @param list The list to free | ||
770 | * @return A NULL pointer | ||
771 | * | ||
772 | * This function frees all the nodes of @p list. It does not free the | ||
773 | * data of the nodes. To free them, use #EINA_LIST_FREE. | ||
774 | */ | ||
775 | EAPI Eina_List *eina_list_free(Eina_List *list); | ||
776 | |||
777 | |||
778 | /** | ||
779 | * @brief Get the nth member's data pointer in a list. | ||
780 | * | ||
781 | * @param list The list to get the specified member number from. | ||
782 | * @param n The number of the element (0 being the first). | ||
783 | * @return The data pointer stored in the specified element. | ||
784 | * | ||
785 | * This function returns the data pointer of element number @p n, in | ||
786 | * the @p list. The first element in the array is element number 0. If | ||
787 | * the element number @p n does not exist, @c NULL is | ||
788 | * returned. Otherwise, the data of the found element is returned. | ||
789 | * | ||
790 | * @note Worst case is O(n). | ||
791 | * | ||
792 | * @warning @p list must be a pointer to the first element of the list. | ||
793 | */ | ||
794 | EAPI void *eina_list_nth(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT; | ||
795 | |||
796 | |||
797 | /** | ||
798 | * @brief Get the nth member's list node in a list. | ||
799 | * | ||
800 | * @param list The list to get the specfied member number from. | ||
801 | * @param n The number of the element (0 being the first). | ||
802 | * @return The list node stored in the numbered element. | ||
803 | * | ||
804 | * This function returns the list node of element number @p n, in | ||
805 | * @p list. The first element in the array is element number 0. If the | ||
806 | * element number @p n does not exist or @p list is @c NULL or @p n is | ||
807 | * greater than the count of elements in @p list minus 1, @c NULL is | ||
808 | * returned. Otherwise the list node stored in the numbered element is | ||
809 | * returned. | ||
810 | * | ||
811 | * @note Worst case is O(n). | ||
812 | * | ||
813 | * @warning @p list must be a pointer to the first element of the list. | ||
814 | */ | ||
815 | EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT; | ||
816 | |||
817 | |||
818 | /** | ||
819 | * @brief Reverse all the elements in the list. | ||
820 | * | ||
821 | * @param list The list to reverse. | ||
822 | * @return The list head after it has been reversed. | ||
823 | * | ||
824 | * This function reverses the order of all elements in @p list, so the | ||
825 | * last member is now first, and so on. If @p list is @c NULL, this | ||
826 | * functon returns @c NULL. | ||
827 | * | ||
828 | * @note @b in-place: this will change the given list, so you should | ||
829 | * now point to the new list head that is returned by this function. | ||
830 | * | ||
831 | * @warning @p list must be a pointer to the first element of the list. | ||
832 | * | ||
833 | * @see eina_list_reverse_clone() | ||
834 | * @see eina_list_iterator_reversed_new() | ||
835 | */ | ||
836 | EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_RESULT; | ||
837 | |||
838 | |||
839 | /** | ||
840 | * @brief Clone (copy) all the elements in the list in reverse order. | ||
841 | * | ||
842 | * @param list The list to reverse. | ||
843 | * @return The new list that has been reversed. | ||
844 | * | ||
845 | * This function reverses the order of all elements in @p list, so the | ||
846 | * last member is now first, and so on. If @p list is @c NULL, this | ||
847 | * functon returns @c NULL. This returns a copy of the given list. | ||
848 | * | ||
849 | * @note @b copy: this will copy the list and you should then | ||
850 | * eina_list_free() when it is not required anymore. | ||
851 | * | ||
852 | * @warning @p list must be a pointer to the first element of the list. | ||
853 | * | ||
854 | * @see eina_list_reverse() | ||
855 | * @see eina_list_clone() | ||
856 | */ | ||
857 | EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT; | ||
858 | |||
859 | |||
860 | /** | ||
861 | * @brief Clone (copy) all the elements in the list in exactly same order. | ||
862 | * | ||
863 | * @param list The list to clone. | ||
864 | * @return The new list that has been cloned. | ||
865 | * | ||
866 | * This function clone in order of all elements in @p list. If @p list | ||
867 | * is @c NULL, this functon returns @c NULL. This returns a copy of | ||
868 | * the given list. | ||
869 | * | ||
870 | * @note @b copy: this will copy the list and you should then | ||
871 | * eina_list_free() when it is not required anymore. | ||
872 | * | ||
873 | * @warning @p list must be a pointer to the first element of the list. | ||
874 | * | ||
875 | * @see eina_list_reverse_clone() | ||
876 | */ | ||
877 | EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT; | ||
878 | |||
879 | |||
880 | /** | ||
881 | * @brief Sort a list according to the ordering func will return. | ||
882 | * | ||
883 | * @param list The list handle to sort. | ||
884 | * @param limit The maximum number of list elements to sort. | ||
885 | * @param func A function pointer that can handle comparing the list data | ||
886 | * nodes. | ||
887 | * @return the new head of list. | ||
888 | * | ||
889 | * This function sorts @p list. @p size if the number of the first | ||
890 | * element to sort. If @p limit is 0 or greater than the number of | ||
891 | * elements in @p list, all the elements are sorted. @p func is used to | ||
892 | * compare two elements of @p list. If @p list or @p func are @c NULL, | ||
893 | * this function returns @c NULL. | ||
894 | * | ||
895 | * @note @b in-place: this will change the given list, so you should | ||
896 | * now point to the new list head that is returned by this function. | ||
897 | * | ||
898 | * @note worst case is O(n * log2(n)) comparisons (calls to func()), | ||
899 | * O(n) comparisons average case. That means that for 1,000,000 list | ||
900 | * elements, sort will usually do 1,000,000 comparisons, but may do up | ||
901 | * to 20,000,000. | ||
902 | * | ||
903 | * Example: | ||
904 | * @code | ||
905 | * int | ||
906 | * sort_cb(const void *d1, const void *d2) | ||
907 | * { | ||
908 | * const char *txt = d1; | ||
909 | * const char *txt2 = d2; | ||
910 | * | ||
911 | * if(!txt) return(1); | ||
912 | * if(!txt2) return(-1); | ||
913 | * | ||
914 | * return(strcmp(txt, txt2)); | ||
915 | * } | ||
916 | * extern Eina_List *list; | ||
917 | * | ||
918 | * list = eina_list_sort(list, eina_list_count(list), sort_cb); | ||
919 | * @endcode | ||
920 | * | ||
921 | * @warning @p list must be a pointer to the first element of the list. | ||
922 | */ | ||
923 | EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int limit, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; | ||
924 | |||
925 | |||
926 | /** | ||
927 | * @brief Merge two list. | ||
928 | * | ||
929 | * @param left Head list to merge. | ||
930 | * @param right Tail list to merge. | ||
931 | * @return A new merged list. | ||
932 | * | ||
933 | * This function puts right at the end of left and return the head. | ||
934 | * | ||
935 | * Both left and right does not exist anymore after the merge. | ||
936 | * | ||
937 | * @note merge cost is O(n), being @b n the size of the smallest | ||
938 | * list. This is due the need to fix accounting of that segment, | ||
939 | * making count and last access O(1). | ||
940 | * | ||
941 | * @warning @p list must be a pointer to the first element of the list. | ||
942 | */ | ||
943 | EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EINA_WARN_UNUSED_RESULT; | ||
944 | |||
945 | |||
946 | /** | ||
947 | * @brief Merge two sorted list according to the ordering func will return. | ||
948 | * | ||
949 | * @param left First list to merge. | ||
950 | * @param right Second list to merge. | ||
951 | * @param func A function pointer that can handle comparing the list data | ||
952 | * nodes. | ||
953 | * @return A new sorted list. | ||
954 | * | ||
955 | * This function compares the head of @p left and @p right, and choose the | ||
956 | * smallest one to be head of the returned list. It will continue this process | ||
957 | * for all entry of both list. | ||
958 | * | ||
959 | * Both left and right does not exist anymore after the merge. | ||
960 | * If @p func is NULL, it will return NULL. | ||
961 | * | ||
962 | * Example: | ||
963 | * @code | ||
964 | * int | ||
965 | * sort_cb(void *d1, void *d2) | ||
966 | * { | ||
967 | * const char *txt = NULL; | ||
968 | * const char *txt2 = NULL; | ||
969 | * | ||
970 | * if(!d1) return(1); | ||
971 | * if(!d2) return(-1); | ||
972 | * | ||
973 | * return(strcmp((const char*)d1, (const char*)d2)); | ||
974 | * } | ||
975 | * extern Eina_List *sorted1; | ||
976 | * extern Eina_List *sorted2; | ||
977 | * | ||
978 | * list = eina_list_sorted_merge(sorted1, sorted2, sort_cb); | ||
979 | * @endcode | ||
980 | * | ||
981 | * @warning @p list must be a pointer to the first element of the list. | ||
982 | */ | ||
983 | EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *right, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; | ||
984 | |||
985 | |||
986 | /** | ||
987 | * @brief Split a list into 2 lists. | ||
988 | * | ||
989 | * @param list List to split. | ||
990 | * @param relative The list will be split after @p relative. | ||
991 | * @param right The head of the new right list. | ||
992 | * @return The new left list | ||
993 | * | ||
994 | * This function splits @p list into two lists ( left and right ) after the node @p relative. @p Relative | ||
995 | * will become the last node of the left list. If @p list or @p right are NULL list is returns. | ||
996 | * If @p relative is NULL right is set to @p list and NULL is returns. | ||
997 | * If @p relative is the last node of @p list list is returns and @p right is set to NULL. | ||
998 | * | ||
999 | * list does not exist anymore after the split. | ||
1000 | * | ||
1001 | * @warning @p list must be a pointer to the first element of the list. | ||
1002 | */ | ||
1003 | EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right) EINA_WARN_UNUSED_RESULT; | ||
1004 | |||
1005 | |||
1006 | /** | ||
1007 | * @brief Returns node nearest to data is in the sorted list. | ||
1008 | * | ||
1009 | * @param list The list to search for data, @b must be sorted. | ||
1010 | * @param func A function pointer that can handle comparing the list data nodes. | ||
1011 | * @param data reference value to search. | ||
1012 | * @param result_cmp if provided returns the result of | ||
1013 | * func(node->data, data) node being the last (returned) node. If node | ||
1014 | * was found (exact match), then it is 0. If returned node is smaller | ||
1015 | * than requested data, it is less than 0 and if it's bigger it's | ||
1016 | * greater than 0. It is the last value returned by func(). | ||
1017 | * @return the nearest node, NULL if not found. | ||
1018 | * | ||
1019 | * This function searches for a node containing @p data as it's data in @p list, | ||
1020 | * if such a node exists it will be returned and @p result_cmp will be @p 0. If | ||
1021 | * the data of no node in @p list is equal to @p data, the node with the nearest | ||
1022 | * value to that will be returned and @p result_cmp will be the return value of | ||
1023 | * @p func with @p data and the returned node's data as arguments. | ||
1024 | * | ||
1025 | * This function is useful for inserting an element in the list only in case it | ||
1026 | * isn't already present in the list, the naive way of doing this would be: | ||
1027 | * @code | ||
1028 | * void *ptr = eina_list_data_find(list, "my data"); | ||
1029 | * if (!ptr) | ||
1030 | * eina_list_sorted_insert(list, "my data"); | ||
1031 | * @endcode | ||
1032 | * | ||
1033 | * However this has the downside of walking through the list twice, once to | ||
1034 | * check if the data is already present and another to insert the element in the | ||
1035 | * corret position. This can be done more eficiently: | ||
1036 | * @code | ||
1037 | * int cmp_result; | ||
1038 | * l = eina_list_search_sorted_near_list(list, cmp_func, "my data", | ||
1039 | * &cmp_result); | ||
1040 | * if (cmp_result > 0) | ||
1041 | * list = eina_list_prepend_relative_list(list, "my data", l); | ||
1042 | * else if (cmp_result < 0) | ||
1043 | * list = eina_list_append_relative_list(list, "my data", l); | ||
1044 | * @endcode | ||
1045 | * | ||
1046 | * If @a cmp_result is 0 the element is already in the list and we need not | ||
1047 | * insert it, if @a cmp_result is greater than zero @a "my @a data" needs to | ||
1048 | * come after @a l(the nearest node present), if less than zero before. | ||
1049 | * | ||
1050 | * @note O(log2(n)) average/worst case performance, for 1,000,000 | ||
1051 | * elements it will do a maximum of 20 comparisons. This is much | ||
1052 | * faster than the 1,000,000 comparisons made naively walking the list | ||
1053 | * from head to tail, so depending on the number of searches and | ||
1054 | * insertions, it may be worth to eina_list_sort() the list and do the | ||
1055 | * searches later. As lists do not have O(1) access time, walking to | ||
1056 | * the correct node can be costly, consider worst case to be almost | ||
1057 | * O(n) pointer dereference (list walk). | ||
1058 | * | ||
1059 | * @warning @p list must be a pointer to the first element of the list. | ||
1060 | * | ||
1061 | * @see eina_list_search_sorted_list() | ||
1062 | * @see eina_list_sort() | ||
1063 | * @see eina_list_sorted_merge() | ||
1064 | */ | ||
1065 | EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *list, Eina_Compare_Cb func, const void *data, int *result_cmp); | ||
1066 | |||
1067 | |||
1068 | /** | ||
1069 | * @brief Returns node if data is in the sorted list. | ||
1070 | * | ||
1071 | * @param list The list to search for data, @b must be sorted. | ||
1072 | * @param func A function pointer that can handle comparing the list data nodes. | ||
1073 | * @param data reference value to search. | ||
1074 | * @return the node if func(node->data, data) == 0, NULL if not found. | ||
1075 | * | ||
1076 | * This can be used to check if some value is inside the list and get | ||
1077 | * the container node in this case. It should be used when list is | ||
1078 | * known to be sorted as it will do binary search for results. | ||
1079 | * | ||
1080 | * Example: imagine user gives a string, you check if it's in the list | ||
1081 | * before duplicating its contents. | ||
1082 | * | ||
1083 | * @note O(log2(n)) average/worst case performance, for 1,000,000 | ||
1084 | * elements it will do a maximum of 20 comparisons. This is much | ||
1085 | * faster than the 1,000,000 comparisons made by | ||
1086 | * eina_list_search_unsorted_list(), so depending on the number of | ||
1087 | * searches and insertions, it may be worth to eina_list_sort() the | ||
1088 | * list and do the searches later. As said in | ||
1089 | * eina_list_search_sorted_near_list(), lists do not have O(1) access | ||
1090 | * time, so walking to the correct node can be costly, consider worst | ||
1091 | * case to be almost O(n) pointer dereference (list walk). | ||
1092 | * | ||
1093 | * @warning @p list must be a pointer to the first element of the list. | ||
1094 | * | ||
1095 | * @see eina_list_search_sorted() | ||
1096 | * @see eina_list_sort() | ||
1097 | * @see eina_list_sorted_merge() | ||
1098 | * @see eina_list_search_unsorted_list() | ||
1099 | * @see eina_list_search_sorted_near_list() | ||
1100 | */ | ||
1101 | EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, Eina_Compare_Cb func, const void *data); | ||
1102 | |||
1103 | |||
1104 | /** | ||
1105 | * @brief Returns node data if it is in the sorted list. | ||
1106 | * | ||
1107 | * @param list The list to search for data, @b must be sorted. | ||
1108 | * @param func A function pointer that can handle comparing the list data nodes. | ||
1109 | * @param data reference value to search. | ||
1110 | * @return the node value (@c node->data) if func(node->data, data) == 0, | ||
1111 | * NULL if not found. | ||
1112 | * | ||
1113 | * This can be used to check if some value is inside the list and get | ||
1114 | * the existing instance in this case. It should be used when list is | ||
1115 | * known to be sorted as it will do binary search for results. | ||
1116 | * | ||
1117 | * Example: imagine user gives a string, you check if it's in the list | ||
1118 | * before duplicating its contents. | ||
1119 | * | ||
1120 | * @note O(log2(n)) average/worst case performance, for 1,000,000 | ||
1121 | * elements it will do a maximum of 20 comparisons. This is much | ||
1122 | * faster than the 1,000,000 comparisons made by | ||
1123 | * eina_list_search_unsorted(), so depending on the number of | ||
1124 | * searches and insertions, it may be worth to eina_list_sort() the | ||
1125 | * list and do the searches later. As said in | ||
1126 | * eina_list_search_sorted_near_list(), lists do not have O(1) access | ||
1127 | * time, so walking to the correct node can be costly, consider worst | ||
1128 | * case to be almost O(n) pointer dereference (list walk). | ||
1129 | * | ||
1130 | * @warning @p list must be a pointer to the first element of the list. | ||
1131 | * | ||
1132 | * @see eina_list_search_sorted_list() | ||
1133 | * @see eina_list_sort() | ||
1134 | * @see eina_list_sorted_merge() | ||
1135 | * @see eina_list_search_unsorted_list() | ||
1136 | */ | ||
1137 | EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_Compare_Cb func, const void *data); | ||
1138 | |||
1139 | |||
1140 | /** | ||
1141 | * @brief Returns node if data is in the unsorted list. | ||
1142 | * | ||
1143 | * @param list The list to search for data, may be unsorted. | ||
1144 | * @param func A function pointer that can handle comparing the list data nodes. | ||
1145 | * @param data reference value to search. | ||
1146 | * @return the node if func(node->data, data) == 0, NULL if not found. | ||
1147 | * | ||
1148 | * This can be used to check if some value is inside the list and get | ||
1149 | * the container node in this case. | ||
1150 | * | ||
1151 | * Example: imagine user gives a string, you check if it's in the list | ||
1152 | * before duplicating its contents. | ||
1153 | * | ||
1154 | * @note this is expensive and may walk the whole list, it's order-N, | ||
1155 | * that is for 1,000,000 elements list it may walk and compare | ||
1156 | * 1,000,000 nodes. | ||
1157 | * | ||
1158 | * @warning @p list must be a pointer to the first element of the list. | ||
1159 | * | ||
1160 | * @see eina_list_search_sorted_list() | ||
1161 | * @see eina_list_search_unsorted() | ||
1162 | */ | ||
1163 | EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list, Eina_Compare_Cb func, const void *data); | ||
1164 | |||
1165 | |||
1166 | /** | ||
1167 | * @brief Returns node data if it is in the unsorted list. | ||
1168 | * | ||
1169 | * @param list The list to search for data, may be unsorted. | ||
1170 | * @param func A function pointer that can handle comparing the list data nodes. | ||
1171 | * @param data reference value to search. | ||
1172 | * @return the node value (@c node->data) if func(node->data, data) == 0, | ||
1173 | * NULL if not found. | ||
1174 | * | ||
1175 | * This can be used to check if some value is inside the list and get | ||
1176 | * the existing instance in this case. | ||
1177 | * | ||
1178 | * Example: imagine user gives a string, you check if it's in the list | ||
1179 | * before duplicating its contents. | ||
1180 | * | ||
1181 | * @note this is expensive and may walk the whole list, it's order-N, | ||
1182 | * that is for 1,000,000 elements list it may walk and compare | ||
1183 | * 1,000,000 nodes. | ||
1184 | * | ||
1185 | * @warning @p list must be a pointer to the first element of the list. | ||
1186 | * | ||
1187 | * @see eina_list_search_sorted() | ||
1188 | * @see eina_list_search_unsorted_list() | ||
1189 | */ | ||
1190 | EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina_Compare_Cb func, const void *data); | ||
1191 | |||
1192 | /** | ||
1193 | * @brief Get the last list node in the list. | ||
1194 | * | ||
1195 | * @param list The list to get the last list node from. | ||
1196 | * @return The last list node in the list. | ||
1197 | * | ||
1198 | * This function returns the last list node in the list @p list. If | ||
1199 | * @p list is @c NULL or empty, @c NULL is returned. | ||
1200 | * | ||
1201 | * This is a order-1 operation (it takes the same short time | ||
1202 | * regardless of the length of the list). | ||
1203 | * | ||
1204 | * @warning @p list must be a pointer to the first element of the list. | ||
1205 | */ | ||
1206 | static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; | ||
1207 | |||
1208 | /** | ||
1209 | * @brief Get the next list node after the specified list node. | ||
1210 | * | ||
1211 | * @param list The list node to get the next list node from | ||
1212 | * @return The next list node on success, @c NULL otherwise. | ||
1213 | * | ||
1214 | * This function returns the next list node after the current one in | ||
1215 | * @p list. It is equivalent to list->next. If @p list is @c NULL or | ||
1216 | * if no next list node exists, it returns @c NULL. | ||
1217 | * | ||
1218 | * @warning @p list must be a pointer to the first element of the list. | ||
1219 | */ | ||
1220 | static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; | ||
1221 | |||
1222 | /** | ||
1223 | * @brief Get the previous list node before the specified list node. | ||
1224 | * | ||
1225 | * @param list The list node to get the previous list node from. | ||
1226 | * @return The previous list node o success, @c NULL otherwise. | ||
1227 | * if no previous list node exists | ||
1228 | * | ||
1229 | * This function returns the previous list node before the current one | ||
1230 | * in @p list. It is equivalent to list->prev. If @p list is @c NULL or | ||
1231 | * if no previous list node exists, it returns @c NULL. | ||
1232 | * | ||
1233 | * @warning @p list must be a pointer to the first element of the list. | ||
1234 | */ | ||
1235 | static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; | ||
1236 | |||
1237 | /** | ||
1238 | * @brief Get the list node data member. | ||
1239 | * | ||
1240 | * @param list The list node to get the data member of. | ||
1241 | * @return The data member from the list node. | ||
1242 | * | ||
1243 | * This function returns the data member of the specified list node @p | ||
1244 | * list. It is equivalent to list->data. If @p list is @c NULL, this | ||
1245 | * function returns @c NULL. | ||
1246 | * | ||
1247 | * @warning @p list must be a pointer to the first element of the list. | ||
1248 | */ | ||
1249 | static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; | ||
1250 | |||
1251 | /** | ||
1252 | * @brief Set the list node data member. | ||
1253 | * | ||
1254 | * @param list The list node to get the data member of. | ||
1255 | * @param data The data member to the list node. | ||
1256 | * @return The previous data value. | ||
1257 | * | ||
1258 | * This function set the data member @p data of the specified list node | ||
1259 | * @p list. It returns the previous data of the node. If @p list is | ||
1260 | * @c NULL, this function returns @c NULL. | ||
1261 | * | ||
1262 | * @warning @p list must be a pointer to the first element of the list. | ||
1263 | */ | ||
1264 | static inline void *eina_list_data_set(Eina_List *list, const void *data); | ||
1265 | |||
1266 | /** | ||
1267 | * @brief Get the count of the number of items in a list. | ||
1268 | * | ||
1269 | * @param list The list whose count to return. | ||
1270 | * @return The number of members in the list. | ||
1271 | * | ||
1272 | * This function returns how many members @p list contains. If the | ||
1273 | * list is @c NULL, 0 is returned. | ||
1274 | * | ||
1275 | * NB: This is an order-1 operation and takes the same time regardless | ||
1276 | * of the length of the list. | ||
1277 | * | ||
1278 | * @warning @p list must be a pointer to the first element of the list. | ||
1279 | */ | ||
1280 | static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE; | ||
1281 | |||
1282 | |||
1283 | /** | ||
1284 | * @brief Returned a new iterator associated to a list. | ||
1285 | * | ||
1286 | * @param list The list. | ||
1287 | * @return A new iterator. | ||
1288 | * | ||
1289 | * This function returns a newly allocated iterator associated to @p | ||
1290 | * list. If @p list is @c NULL or the count member of @p list is less | ||
1291 | * or equal than 0, this function still returns a valid iterator that | ||
1292 | * will always return false on eina_iterator_next(), thus keeping API | ||
1293 | * sane. | ||
1294 | * | ||
1295 | * If the memory can not be allocated, NULL is returned and | ||
1296 | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | ||
1297 | * returned. | ||
1298 | * | ||
1299 | * @warning @p list must be a pointer to the first element of the list. | ||
1300 | * | ||
1301 | * @warning if the list structure changes then the iterator becomes | ||
1302 | * invalid! That is, if you add or remove nodes this iterator | ||
1303 | * behavior is undefined and your program may crash! | ||
1304 | */ | ||
1305 | EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
1306 | |||
1307 | |||
1308 | /** | ||
1309 | * @brief Returned a new reversed iterator associated to a list. | ||
1310 | * | ||
1311 | * @param list The list. | ||
1312 | * @return A new iterator. | ||
1313 | * | ||
1314 | * This function returns a newly allocated iterator associated to @p | ||
1315 | * list. If @p list is @c NULL or the count member of @p list is less | ||
1316 | * or equal than 0, this function still returns a valid iterator that | ||
1317 | * will always return false on eina_iterator_next(), thus keeping API | ||
1318 | * sane. | ||
1319 | * | ||
1320 | * Unlike eina_list_iterator_new(), this will walk the list backwards. | ||
1321 | * | ||
1322 | * If the memory can not be allocated, NULL is returned and | ||
1323 | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | ||
1324 | * returned. | ||
1325 | * | ||
1326 | * @warning @p list must be a pointer to the first element of the list. | ||
1327 | * | ||
1328 | * @warning if the list structure changes then the iterator becomes | ||
1329 | * invalid! That is, if you add or remove nodes this iterator | ||
1330 | * behavior is undefined and your program may crash! | ||
1331 | */ | ||
1332 | EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
1333 | |||
1334 | |||
1335 | /** | ||
1336 | * @brief Returned a new accessor associated to a list. | ||
1337 | * | ||
1338 | * @param list The list. | ||
1339 | * @return A new accessor. | ||
1340 | * | ||
1341 | * This function returns a newly allocated accessor associated to | ||
1342 | * @p list. If @p list is @c NULL or the count member of @p list is | ||
1343 | * less or equal than 0, this function returns NULL. If the memory can | ||
1344 | * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | ||
1345 | * set. Otherwise, a valid accessor is returned. | ||
1346 | * | ||
1347 | * @warning @p list must be a pointer to the first element of the list. | ||
1348 | */ | ||
1349 | EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
1350 | |||
1351 | /** | ||
1352 | * @def EINA_LIST_FOREACH | ||
1353 | * @brief Macro to iterate over a list. | ||
1354 | * | ||
1355 | * @param list The list to iterate over. | ||
1356 | * @param l A list that is used as an iterator and points to the current node. | ||
1357 | * @param data Current item's data. | ||
1358 | * | ||
1359 | * This macro iterates over @p list from the first element to | ||
1360 | * the last. @p data is the data related to the current element. | ||
1361 | * @p l is an #Eina_List used as the list iterator. | ||
1362 | * | ||
1363 | * The following diagram ilustrates this macro iterating over a list of four | ||
1364 | * elements("one", "two", "three" and "four"): | ||
1365 | * @htmlonly | ||
1366 | * <img src="eina-list-foreach.png" style="max-width: 100%;" /> | ||
1367 | * <a href="eina-list-foreach.png">Full-size</a> | ||
1368 | * @endhtmlonly | ||
1369 | * @image latex eina-list-foreach.eps width=\textwidth | ||
1370 | * | ||
1371 | * It can be used to free list data, as in the following example: | ||
1372 | * | ||
1373 | * @code | ||
1374 | * Eina_List *list; | ||
1375 | * Eina_List *l; | ||
1376 | * char *data; | ||
1377 | * | ||
1378 | * // list is already filled, | ||
1379 | * // its elements are just duplicated strings, | ||
1380 | * // EINA_LIST_FOREACH will be used to free those strings | ||
1381 | * | ||
1382 | * EINA_LIST_FOREACH(list, l, data) | ||
1383 | * free(data); | ||
1384 | * eina_list_free(list); | ||
1385 | * @endcode | ||
1386 | * | ||
1387 | * @note This is not the optimal way to release memory allocated to | ||
1388 | * a list, since it iterates over the list twice. | ||
1389 | * For an optimized algorithm, use EINA_LIST_FREE(). | ||
1390 | * | ||
1391 | * @warning @p list must be a pointer to the first element of the list. | ||
1392 | * | ||
1393 | * @warning Be careful when deleting list nodes. | ||
1394 | * If you remove the current node and continue iterating, | ||
1395 | * the code will fail because the macro will not be able | ||
1396 | * to get the next node. Notice that it's OK to remove any | ||
1397 | * node if you stop the loop after that. | ||
1398 | * For destructive operations such as this, consider | ||
1399 | * using EINA_LIST_FOREACH_SAFE(). | ||
1400 | */ | ||
1401 | #define EINA_LIST_FOREACH(list, l, data) \ | ||
1402 | for (l = list, \ | ||
1403 | data = eina_list_data_get(l); \ | ||
1404 | l; \ | ||
1405 | l = eina_list_next(l), \ | ||
1406 | data = eina_list_data_get(l)) | ||
1407 | |||
1408 | /** | ||
1409 | * @def EINA_LIST_REVERSE_FOREACH | ||
1410 | * @brief Macro to iterate over a list in the reverse order. | ||
1411 | * | ||
1412 | * @param list The list to iterate over. | ||
1413 | * @param l A list that is used as an iterator and points to the current node. | ||
1414 | * @param data Current item's data. | ||
1415 | * | ||
1416 | * This macro works like EINA_LIST_FOREACH, but iterates from the | ||
1417 | * last element of a list to the first. | ||
1418 | * @p data is the data related to the current element, while @p l | ||
1419 | * is an #Eina_List that is used as the list iterator. | ||
1420 | * | ||
1421 | * The following diagram ilustrates this macro iterating over a list of four | ||
1422 | * elements("one", "two", "three" and "four"): | ||
1423 | * @htmlonly | ||
1424 | * <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" /> | ||
1425 | * <a href="eina-list-reverse-foreach.png">Full-size</a> | ||
1426 | * @endhtmlonly | ||
1427 | * @image latex eina-list-reverse-foreach.eps width=\textwidth | ||
1428 | * | ||
1429 | * It can be used to free list data, as in the following example: | ||
1430 | * | ||
1431 | * @code | ||
1432 | * Eina_List *list; | ||
1433 | * Eina_List *l; | ||
1434 | * char *data; | ||
1435 | * | ||
1436 | * // list is already filled, | ||
1437 | * // its elements are just duplicated strings, | ||
1438 | * // EINA_LIST_REVERSE_FOREACH will be used to free those strings | ||
1439 | * | ||
1440 | * EINA_LIST_REVERSE_FOREACH(list, l, data) | ||
1441 | * free(data); | ||
1442 | * eina_list_free(list); | ||
1443 | * @endcode | ||
1444 | * | ||
1445 | * @note This is not the optimal way to release memory allocated to | ||
1446 | * a list, since it iterates over the list twice. | ||
1447 | * For an optimized algorithm, use EINA_LIST_FREE(). | ||
1448 | * | ||
1449 | * @warning @p list must be a pointer to the first element of the list. | ||
1450 | * | ||
1451 | * @warning Be careful when deleting list nodes. | ||
1452 | * If you remove the current node and continue iterating, | ||
1453 | * the code will fail because the macro will not be able | ||
1454 | * to get the next node. Notice that it's OK to remove any | ||
1455 | * node if you stop the loop after that. | ||
1456 | * For destructive operations such as this, consider | ||
1457 | * using EINA_LIST_REVERSE_FOREACH_SAFE(). | ||
1458 | */ | ||
1459 | #define EINA_LIST_REVERSE_FOREACH(list, l, data) \ | ||
1460 | for (l = eina_list_last(list), \ | ||
1461 | data = eina_list_data_get(l); \ | ||
1462 | l; \ | ||
1463 | l = eina_list_prev(l), \ | ||
1464 | data = eina_list_data_get(l)) | ||
1465 | |||
1466 | /** | ||
1467 | * @def EINA_LIST_FOREACH_SAFE | ||
1468 | * @brief Macro to iterate over a list with support for node deletion. | ||
1469 | * | ||
1470 | * @param list The list to iterate over. | ||
1471 | * @param l A list that is used as an iterator and points to the current node. | ||
1472 | * @param l_next A list that is used as an iterator and points to the next node. | ||
1473 | * @param data Current item's data. | ||
1474 | * | ||
1475 | * This macro iterates over @p list from the first element to | ||
1476 | * the last. @p data is the data related to the current element. | ||
1477 | * @p l is an #Eina_List used as the list iterator. | ||
1478 | * | ||
1479 | * Since this macro stores a pointer to the next list node in @p l_next, | ||
1480 | * deleting the current node and continuing looping is safe. | ||
1481 | * | ||
1482 | * The following diagram ilustrates this macro iterating over a list of four | ||
1483 | * elements("one", "two", "three" and "four"): | ||
1484 | * @htmlonly | ||
1485 | * <img src="eina-list-foreach-safe.png" style="max-width: 100%;" /> | ||
1486 | * <a href="eina-list-foreach-safe.png">Full-size</a> | ||
1487 | * @endhtmlonly | ||
1488 | * @image latex eina-list-foreach-safe.eps width=\textwidth | ||
1489 | * | ||
1490 | * This macro can be used to free list nodes, as in the following example: | ||
1491 | * | ||
1492 | * @code | ||
1493 | * Eina_List *list; | ||
1494 | * Eina_List *l; | ||
1495 | * Eina_List *l_next; | ||
1496 | * char *data; | ||
1497 | * | ||
1498 | * // list is already filled, | ||
1499 | * // its elements are just duplicated strings, | ||
1500 | * // EINA_LIST_FOREACH_SAFE will be used to free elements that match "key". | ||
1501 | * | ||
1502 | * EINA_LIST_FOREACH_SAFE(list, l, l_next, data) | ||
1503 | * if (strcmp(data, "key") == 0) { | ||
1504 | * free(data); | ||
1505 | * list = eina_list_remove_list(list, l); | ||
1506 | * } | ||
1507 | * @endcode | ||
1508 | * | ||
1509 | * @warning @p list must be a pointer to the first element of the list. | ||
1510 | */ | ||
1511 | #define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \ | ||
1512 | for (l = list, \ | ||
1513 | l_next = eina_list_next(l), \ | ||
1514 | data = eina_list_data_get(l); \ | ||
1515 | l; \ | ||
1516 | l = l_next, \ | ||
1517 | l_next = eina_list_next(l), \ | ||
1518 | data = eina_list_data_get(l)) | ||
1519 | |||
1520 | /** | ||
1521 | * @def EINA_LIST_REVERSE_FOREACH_SAFE | ||
1522 | * @brief Macro to iterate over a list in the reverse order with support | ||
1523 | * for deletion. | ||
1524 | * | ||
1525 | * @param list The list to iterate over. | ||
1526 | * @param l A list that is used as an iterator and points to the current node. | ||
1527 | * @param l_prev A list that is used as an iterator and points to the previous node. | ||
1528 | * @param data Current item's data. | ||
1529 | * | ||
1530 | * This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the | ||
1531 | * last element of a list to the first. | ||
1532 | * @p data is the data related to the current element, while @p l | ||
1533 | * is an #Eina_List that is used as the list iterator. | ||
1534 | * | ||
1535 | * Since this macro stores a pointer to the previous list node in @p l_prev, | ||
1536 | * deleting the current node and continuing looping is safe. | ||
1537 | * | ||
1538 | * The following diagram ilustrates this macro iterating over a list of four | ||
1539 | * elements("one", "two", "three" and "four"): | ||
1540 | * @htmlonly | ||
1541 | * <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" /> | ||
1542 | * <a href="eina-list-reverse-foreach-safe.png">Full-size</a> | ||
1543 | * @endhtmlonly | ||
1544 | * @image latex eina-list-reverse-foreach-safe.eps width=\textwidth | ||
1545 | * | ||
1546 | * This macro can be used to free list nodes, as in the following example: | ||
1547 | * | ||
1548 | * @code | ||
1549 | * Eina_List *list; | ||
1550 | * Eina_List *l; | ||
1551 | * Eina_List *l_prev; | ||
1552 | * char *data; | ||
1553 | * | ||
1554 | * // list is already filled, | ||
1555 | * // its elements are just duplicated strings, | ||
1556 | * // EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that match "key". | ||
1557 | * | ||
1558 | * EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) | ||
1559 | * if (strcmp(data, "key") == 0) { | ||
1560 | * free(data); | ||
1561 | * list = eina_list_remove_list(list, l); | ||
1562 | * } | ||
1563 | * @endcode | ||
1564 | * | ||
1565 | * @warning @p list must be a pointer to the first element of the list. | ||
1566 | */ | ||
1567 | #define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) \ | ||
1568 | for (l = eina_list_last(list), \ | ||
1569 | l_prev = eina_list_prev(l), \ | ||
1570 | data = eina_list_data_get(l); \ | ||
1571 | l; \ | ||
1572 | l = l_prev, \ | ||
1573 | l_prev = eina_list_prev(l), \ | ||
1574 | data = eina_list_data_get(l)) | ||
1575 | |||
1576 | /** | ||
1577 | * @def EINA_LIST_FREE | ||
1578 | * @brief Macro to remove each list node while having access to each node's data. | ||
1579 | * | ||
1580 | * @param list The list that will be cleared. | ||
1581 | * @param data Current node's data. | ||
1582 | * | ||
1583 | * This macro will call #eina_list_remove_list for each list node, and store | ||
1584 | * the data contained in the current node in @p data. | ||
1585 | * | ||
1586 | * The following diagram ilustrates this macro iterating over a list of four | ||
1587 | * elements("one", "two", "three" and "four"): | ||
1588 | * @htmlonly | ||
1589 | * <img src="eina-list-free.png" style="max-width: 100%;" /> | ||
1590 | * <a href="eina-list-free.png">Full-size</a> | ||
1591 | * @endhtmlonly | ||
1592 | * @image latex eina-list-free.eps width=\textwidth | ||
1593 | * | ||
1594 | * If you do not need to release node data, it is easier to call #eina_list_free(). | ||
1595 | * | ||
1596 | * @code | ||
1597 | * Eina_List *list; | ||
1598 | * char *data; | ||
1599 | * | ||
1600 | * // list is already filled, | ||
1601 | * // its elements are just duplicated strings, | ||
1602 | * | ||
1603 | * EINA_LIST_FREE(list, data) | ||
1604 | * free(data); | ||
1605 | * @endcode | ||
1606 | * | ||
1607 | * @warning @p list must be a pointer to the first element of the list. | ||
1608 | * | ||
1609 | * @see eina_list_free() | ||
1610 | */ | ||
1611 | #define EINA_LIST_FREE(list, data) \ | ||
1612 | for (data = eina_list_data_get(list); \ | ||
1613 | list; \ | ||
1614 | list = eina_list_remove_list(list, list), \ | ||
1615 | data = eina_list_data_get(list)) | ||
1616 | |||
1617 | #include "eina_inline_list.x" | ||
1618 | |||
1619 | /** | ||
1620 | * @} | ||
1621 | */ | ||
1622 | |||
1623 | /** | ||
1624 | * @} | ||
1625 | */ | ||
1626 | |||
1627 | /** | ||
1628 | * @} | ||
1629 | */ | ||
1630 | |||
1631 | #endif /* EINA_LIST_H_ */ | ||