1 /* EINA - EFL data type library
2 * Copyright (C) 2002-2008 Carsten Haitzler, Vincent Torri, Jorge Luis Zapata Muga
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.
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.
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/>.
24 #include "eina_config.h"
26 #include "eina_types.h"
27 #include "eina_iterator.h"
28 #include "eina_accessor.h"
29 #include "eina_magic.h"
32 * @page eina_list_01_example_page Adding elements to Eina_List
33 * @dontinclude eina_list_01.c
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.
42 * Just some boilerplate code, declaring some variable and initializing eina.
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
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>
50 * @image rtf eina_list_example_01_a.png
51 * @image latex eina_list_example_01_a.eps width=\textwidth
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.
59 * Now that we have a list with some elements in it we can look at it's contents.
62 * There are many ways of accessing elements in the list, including by it's
65 * @note It should be noted that the index starts at 0.
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():
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".
75 * @ref Eina_List also has prepend analogs to append functions we have used so
78 * With this additions our list now looks like this:@n
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>
83 * @image rtf eina_list_example_01_b.png
84 * @image latex eina_list_example_01_b.eps width=\textwidth
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:
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.
95 * @page eina_list_01_c Adding elements to Eina_List example
97 * @include eina_list_01.c
98 * @example eina_list_01.c
102 * @page eina_list_02_example_page Sorting Eina_List elements
103 * @dontinclude eina_list_02.c
105 * If you don't know how to create lists see
106 * @ref eina_list_01_example_page.
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:
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:
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
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:
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.
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":
135 * It is also possible to add entire lists of elements using
136 * @ref eina_list_sorted_merge():
137 * @until sorted_merge
139 * And as always release memory and shutdown eina before ending:
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.
147 * @page eina_list_02_c Sorting Eina_List elements example
149 * @include eina_list_02.c
150 * @example eina_list_02.c
154 * @page eina_list_03_example_page Reordering Eina_List elements
155 * @dontinclude eina_list_03.c
157 * If you don't know how to create lists see
158 * @ref eina_list_01_example_page.
160 * We start out with code that should be familiar by now:
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:
169 * Removing elements from a list can be done with ease:
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:
176 * We will now take a peek to see if the list still has the right number of
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.
185 * And as always release memory and shutdown eina before ending:
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.
193 * @page eina_list_03_c Reordering Eina_List elements example
195 * @include eina_list_03.c
196 * @example eina_list_03.c
200 * @page eina_list_04_example_page Eina_List and memory allocation
201 * @dontinclude eina_list_04.c
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.
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.
213 * This time we are going to iterate over our list in a different way:
216 * And now we are going to iterate over the list backwards:
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
224 * And shut everything down:
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.
232 * @page eina_list_04_c Eina_List and memory allocation example
234 * @include eina_list_04.c
235 * @example eina_list_04.c
239 * @addtogroup Eina_List_Group List
241 * @brief These functions provide double linked list management.
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.
249 * @ref Eina_List nodes keep references to the previous node, the next node, its
250 * data and to an accounting structure.
253 * <img src="eina_list.png" style="max-width: 100%;" />
254 * <a href="eina_list.png">Full-size</a>
256 * @image rtf eina_list.png
257 * @image latex eina_list.eps width=5cm
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.
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.
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.
273 * @warning You must @b always use the pointer to the first element of the list
275 * @warning You must @b never use a pointer to an element in the middle of the
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
286 * @addtogroup Eina_Data_Types_Group Data Types
292 * @addtogroup Eina_Containers_Group Containers
298 * @defgroup Eina_List_Group List
305 * Type for a generic double linked list.
307 typedef struct _Eina_List Eina_List;
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.
314 typedef struct _Eina_List_Accounting Eina_List_Accounting;
318 * Type for a generic double linked list.
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 */
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
336 struct _Eina_List_Accounting
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 */
345 * @brief Append the given data to the given linked list.
347 * @param list The given list.
348 * @param data The data to append.
349 * @return A list pointer.
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.
356 * The following example code demonstrates how to ensure that the
357 * given data has been successfully appended.
360 * Eina_List *list = NULL;
361 * extern void *my_data;
363 * list = eina_list_append(list, my_data);
364 * if (eina_error_get())
366 * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
371 * @warning @p list must be a pointer to the first element of the list(or NULL).
373 EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
377 * @brief Prepends the given data to the given linked list.
379 * @param list The given list.
380 * @param data The data to prepend.
381 * @return A list pointer.
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.
388 * The following example code demonstrates how to ensure that the
389 * given data has been successfully prepended.
393 * Eina_List *list = NULL;
394 * extern void *my_data;
396 * list = eina_list_prepend(list, my_data);
397 * if (eina_error_get())
399 * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
404 * @warning @p list must be a pointer to the first element of the list.
406 EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
410 * @brief Insert the given data into the given linked list after the specified data.
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.
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.
425 * The following example code demonstrates how to ensure that the
426 * given data has been successfully inserted.
429 * Eina_List *list = NULL;
430 * extern void *my_data;
431 * extern void *relative_member;
433 * list = eina_list_append(list, relative_member);
434 * if (eina_error_get())
436 * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
439 * list = eina_list_append_relative(list, my_data, relative_member);
440 * if (eina_error_get())
442 * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
447 * @warning @p list must be a pointer to the first element of the list.
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;
453 * @brief Append a list node to a linked list after the specified member
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.
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.
469 * @warning @p list must be a pointer to the first element of the list.
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;
475 * @brief Prepend a data pointer to a linked list before the specified member
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.
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.
490 * The following code example demonstrates how to ensure that the
491 * given data has been successfully inserted.
494 * Eina_List *list = NULL;
495 * extern void *my_data;
496 * extern void *relative_member;
498 * list = eina_list_append(list, relative_member);
499 * if (eina_error_get_error())
501 * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
504 * list = eina_list_prepend_relative(list, my_data, relative_member);
505 * if (eina_error_get())
507 * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
512 * @warning @p list must be a pointer to the first element of the list.
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;
518 * @brief Prepend a list node to a linked list before the specified member
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.
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.
534 * @warning @p list must be a pointer to the first element of the list.
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;
540 * @brief Insert a new node into a sorted list.
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.
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().
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).
560 * @warning @p list must be a pointer to the first element of the list.
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;
566 * @brief Remove the first instance of the specified data from the given list.
568 * @param list The given list.
569 * @param data The specified data.
570 * @return A list pointer.
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
579 * @warning @p list must be a pointer to the first element of the list.
581 EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
585 * @brief Remove the specified list node.
587 * @param list The given linked list.
588 * @param remove_list The list node which is to be removed.
589 * @return A list pointer.
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.
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).
602 * extern Eina_List *list;
604 * extern void *my_data;
607 * EINA_LIST_FOREACH(list, l, data)
609 * if (data == my_data)
611 * list = eina_list_remove_list(list, l);
617 * @warning @p list must be a pointer to the first element of the list.
619 EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
623 * @brief Move the specified data to the head of the list.
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
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.
636 * extern Eina_List *list;
638 * extern void *my_data;
641 * EINA_LIST_FOREACH(list, l, data)
643 * if (data == my_data)
645 * list = eina_list_promote_list(list, l);
651 * @warning @p list must be a pointer to the first element of the list.
653 EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
657 * @brief Move the specified data to the tail of the list.
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
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.
670 * extern Eina_List *list;
672 * extern void *my_data;
675 * EINA_LIST_FOREACH(list, l, data)
677 * if (data == my_data)
679 * list = eina_list_demote_list(list, l);
685 * @warning @p list must be a pointer to the first element of the list.
687 EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *move_list);
691 * @brief Find a member of a list and return the member.
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.
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 @c NULL will be returned.
703 * extern Eina_List *list;
704 * extern void *my_data;
706 * if (eina_list_data_find(list, my_data) == my_data)
708 * printf("Found member %p\n", my_data);
712 * @warning @p list must be a pointer to the first element of the list.
714 EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
717 * @brief Find a member of a list and return the list node containing that member.
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.
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.
728 * @warning @p list must be a pointer to the first element of the list.
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;
734 * @brief Move a data pointer from one list to another
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
741 * This function is a shortcut for doing the following:
742 * to = eina_list_append(to, data);
743 * from = eina_list_remove(from, data);
745 * @warning @p list must be a pointer to the first element of the list.
747 EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data);
750 * @brief Move a list node from one list to another
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
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);
761 * @warning @p list must be a pointer to the first element of the list.
763 EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data);
767 * @brief Free an entire list and all the nodes, ignoring the data contained.
769 * @param list The list to free
770 * @return A @c NULL pointer
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.
775 EAPI Eina_List *eina_list_free(Eina_List *list);
779 * @brief Get the nth member's data pointer in a list.
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.
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.
790 * @note Worst case is O(n).
792 * @warning @p list must be a pointer to the first element of the list.
794 EAPI void *eina_list_nth(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
798 * @brief Get the nth member's list node in a list.
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.
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
811 * @note Worst case is O(n).
813 * @warning @p list must be a pointer to the first element of the list.
815 EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
819 * @brief Reverse all the elements in the list.
821 * @param list The list to reverse.
822 * @return The list head after it has been reversed.
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.
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.
831 * @warning @p list must be a pointer to the first element of the list.
833 * @see eina_list_reverse_clone()
834 * @see eina_list_iterator_reversed_new()
836 EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_RESULT;
840 * @brief Clone (copy) all the elements in the list in reverse order.
842 * @param list The list to reverse.
843 * @return The new list that has been reversed.
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.
849 * @note @b copy: this will copy the list and you should then
850 * eina_list_free() when it is not required anymore.
852 * @warning @p list must be a pointer to the first element of the list.
854 * @see eina_list_reverse()
855 * @see eina_list_clone()
857 EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT;
861 * @brief Clone (copy) all the elements in the list in exactly same order.
863 * @param list The list to clone.
864 * @return The new list that has been cloned.
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
870 * @note @b copy: this will copy the list and you should then
871 * eina_list_free() when it is not required anymore.
873 * @warning @p list must be a pointer to the first element of the list.
875 * @see eina_list_reverse_clone()
877 EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT;
881 * @brief Sort a list according to the ordering func will return.
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
887 * @return the new head of list.
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.
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.
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
906 * sort_cb(const void *d1, const void *d2)
908 * const char *txt = d1;
909 * const char *txt2 = d2;
911 * if(!txt) return(1);
912 * if(!txt2) return(-1);
914 * return(strcmp(txt, txt2));
916 * extern Eina_List *list;
918 * list = eina_list_sort(list, eina_list_count(list), sort_cb);
921 * @warning @p list must be a pointer to the first element of the list.
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;
927 * @brief Merge two list.
929 * @param left Head list to merge.
930 * @param right Tail list to merge.
931 * @return A new merged list.
933 * This function puts right at the end of left and returns the head.
935 * Both left and right do not exist anymore after the merge.
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).
941 * @warning @p list must be a pointer to the first element of the list.
943 EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EINA_WARN_UNUSED_RESULT;
947 * @brief Merge two sorted list according to the ordering func will return.
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
953 * @return A new sorted list.
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.
959 * Both left and right do not exist anymore after the merge.
960 * If @p func is @c NULL, it will return @c NULL.
965 * sort_cb(void *d1, void *d2)
967 * const char *txt = NULL;
968 * const char *txt2 = NULL;
971 * if(!d2) return(-1);
973 * return(strcmp((const char*)d1, (const char*)d2));
975 * extern Eina_List *sorted1;
976 * extern Eina_List *sorted2;
978 * list = eina_list_sorted_merge(sorted1, sorted2, sort_cb);
981 * @warning @p list must be a pointer to the first element of the list.
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;
987 * @brief Split a list into 2 lists.
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
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 @c NULL list is returns.
996 * If @p relative is NULL right is set to @p list and @c NULL is returns.
997 * If @p relative is the last node of @p list list is returns and @p right is set to @c NULL.
999 * list does not exist anymore after the split.
1001 * @warning @p list must be a pointer to the first element of the list.
1003 EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right) EINA_WARN_UNUSED_RESULT;
1007 * @brief Returns node nearest to data is in the sorted list.
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, @c NULL if not found.
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.
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:
1028 * void *ptr = eina_list_data_find(list, "my data");
1030 * eina_list_sorted_insert(list, "my data");
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:
1038 * l = eina_list_search_sorted_near_list(list, cmp_func, "my data",
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);
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.
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).
1059 * @warning @p list must be a pointer to the first element of the list.
1061 * @see eina_list_search_sorted_list()
1062 * @see eina_list_sort()
1063 * @see eina_list_sorted_merge()
1065 EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *list, Eina_Compare_Cb func, const void *data, int *result_cmp);
1069 * @brief Returns node if data is in the sorted list.
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, @c NULL if not found.
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.
1080 * Example: imagine user gives a string, you check if it's in the list
1081 * before duplicating its contents.
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).
1093 * @warning @p list must be a pointer to the first element of the list.
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()
1101 EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, Eina_Compare_Cb func, const void *data);
1105 * @brief Returns node data if it is in the sorted list.
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.
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.
1117 * Example: imagine user gives a string, you check if it's in the list
1118 * before duplicating its contents.
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).
1130 * @warning @p list must be a pointer to the first element of the list.
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()
1137 EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_Compare_Cb func, const void *data);
1141 * @brief Returns node if data is in the unsorted list.
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, @c NULL if not found.
1148 * This can be used to check if some value is inside the list and get
1149 * the container node in this case.
1151 * Example: imagine user gives a string, you check if it's in the list
1152 * before duplicating its contents.
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
1158 * @warning @p list must be a pointer to the first element of the list.
1160 * @see eina_list_search_sorted_list()
1161 * @see eina_list_search_unsorted()
1163 EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list, Eina_Compare_Cb func, const void *data);
1167 * @brief Returns node data if it is in the unsorted list.
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 * @c NULL if not found.
1175 * This can be used to check if some value is inside the list and get
1176 * the existing instance in this case.
1178 * Example: imagine user gives a string, you check if it's in the list
1179 * before duplicating its contents.
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
1185 * @warning @p list must be a pointer to the first element of the list.
1187 * @see eina_list_search_sorted()
1188 * @see eina_list_search_unsorted_list()
1190 EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina_Compare_Cb func, const void *data);
1193 * @brief Get the last list node in the list.
1195 * @param list The list to get the last list node from.
1196 * @return The last list node in the list.
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.
1201 * This is a order-1 operation (it takes the same short time
1202 * regardless of the length of the list).
1204 * @warning @p list must be a pointer to the first element of the list.
1206 static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
1209 * @brief Get the next list node after the specified list node.
1211 * @param list The list node to get the next list node from
1212 * @return The next list node on success, @c NULL otherwise.
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.
1218 * @warning @p list must be a pointer to the first element of the list.
1220 static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
1223 * @brief Get the previous list node before the specified list node.
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
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.
1233 * @warning @p list must be a pointer to the first element of the list.
1235 static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
1238 * @brief Get the list node data member.
1240 * @param list The list node to get the data member of.
1241 * @return The data member from the list node.
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.
1247 * @warning @p list must be a pointer to the first element of the list.
1249 static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
1252 * @brief Set the list node data member.
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.
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.
1262 * @warning @p list must be a pointer to the first element of the list.
1264 static inline void *eina_list_data_set(Eina_List *list, const void *data);
1267 * @brief Get the count of the number of items in a list.
1269 * @param list The list whose count to return.
1270 * @return The number of members in the list.
1272 * This function returns how many members @p list contains. If the
1273 * list is @c NULL, @c 0 is returned.
1275 * NB: This is an order-1 operation and takes the same time regardless
1276 * of the length of the list.
1278 * @warning @p list must be a pointer to the first element of the list.
1280 static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
1284 * @brief Returned a new iterator associated to a list.
1286 * @param list The list.
1287 * @return A new iterator.
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
1295 * If the memory can not be allocated, NULL is returned
1296 * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator
1299 * @warning @p list must be a pointer to the first element of the list.
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!
1305 EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
1309 * @brief Returned a new reversed iterator associated to a list.
1311 * @param list The list.
1312 * @return A new iterator.
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
1320 * Unlike eina_list_iterator_new(), this will walk the list backwards.
1322 * If the memory can not be allocated, NULL is returned
1323 * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator
1326 * @warning @p list must be a pointer to the first element of the list.
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!
1332 EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
1336 * @brief Returned a new accessor associated to a list.
1338 * @param list The list.
1339 * @return A new accessor.
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 @c NULL. If the memory can
1344 * not be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
1345 * set. Otherwise, a valid accessor is returned.
1347 * @warning @p list must be a pointer to the first element of the list.
1349 EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
1352 * @def EINA_LIST_FOREACH
1353 * @brief Macro to iterate over a list.
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.
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.
1363 * The following diagram ilustrates this macro iterating over a list of four
1364 * elements("one", "two", "three" and "four"):
1366 * <img src="eina-list-foreach.png" style="max-width: 100%;" />
1367 * <a href="eina-list-foreach.png">Full-size</a>
1369 * @image latex eina-list-foreach.eps width=\textwidth
1371 * It can be used to free list data, as in the following example:
1378 * // list is already filled,
1379 * // its elements are just duplicated strings,
1380 * // EINA_LIST_FOREACH will be used to free those strings
1382 * EINA_LIST_FOREACH(list, l, data)
1384 * eina_list_free(list);
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().
1391 * @warning @p list must be a pointer to the first element of the list.
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().
1401 #define EINA_LIST_FOREACH(list, l, data) \
1403 data = eina_list_data_get(l); \
1405 l = eina_list_next(l), \
1406 data = eina_list_data_get(l))
1409 * @def EINA_LIST_REVERSE_FOREACH
1410 * @brief Macro to iterate over a list in the reverse order.
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.
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.
1421 * The following diagram ilustrates this macro iterating over a list of four
1422 * elements("one", "two", "three" and "four"):
1424 * <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" />
1425 * <a href="eina-list-reverse-foreach.png">Full-size</a>
1427 * @image latex eina-list-reverse-foreach.eps width=\textwidth
1429 * It can be used to free list data, as in the following example:
1436 * // list is already filled,
1437 * // its elements are just duplicated strings,
1438 * // EINA_LIST_REVERSE_FOREACH will be used to free those strings
1440 * EINA_LIST_REVERSE_FOREACH(list, l, data)
1442 * eina_list_free(list);
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().
1449 * @warning @p list must be a pointer to the first element of the list.
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().
1459 #define EINA_LIST_REVERSE_FOREACH(list, l, data) \
1460 for (l = eina_list_last(list), \
1461 data = eina_list_data_get(l); \
1463 l = eina_list_prev(l), \
1464 data = eina_list_data_get(l))
1467 * @def EINA_LIST_FOREACH_SAFE
1468 * @brief Macro to iterate over a list with support for node deletion.
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.
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.
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.
1482 * The following diagram ilustrates this macro iterating over a list of four
1483 * elements("one", "two", "three" and "four"):
1485 * <img src="eina-list-foreach-safe.png" style="max-width: 100%;" />
1486 * <a href="eina-list-foreach-safe.png">Full-size</a>
1488 * @image latex eina-list-foreach-safe.eps width=\textwidth
1490 * This macro can be used to free list nodes, as in the following example:
1495 * Eina_List *l_next;
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".
1502 * EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
1503 * if (strcmp(data, "key") == 0) {
1505 * list = eina_list_remove_list(list, l);
1509 * @warning @p list must be a pointer to the first element of the list.
1511 #define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \
1513 l_next = eina_list_next(l), \
1514 data = eina_list_data_get(l); \
1517 l_next = eina_list_next(l), \
1518 data = eina_list_data_get(l))
1521 * @def EINA_LIST_REVERSE_FOREACH_SAFE
1522 * @brief Macro to iterate over a list in the reverse order with support
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.
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.
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.
1538 * The following diagram ilustrates this macro iterating over a list of four
1539 * elements("one", "two", "three" and "four"):
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>
1544 * @image latex eina-list-reverse-foreach-safe.eps width=\textwidth
1546 * This macro can be used to free list nodes, as in the following example:
1551 * Eina_List *l_prev;
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".
1558 * EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data)
1559 * if (strcmp(data, "key") == 0) {
1561 * list = eina_list_remove_list(list, l);
1565 * @warning @p list must be a pointer to the first element of the list.
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); \
1573 l_prev = eina_list_prev(l), \
1574 data = eina_list_data_get(l))
1577 * @def EINA_LIST_FREE
1578 * @brief Macro to remove each list node while having access to each node's data.
1580 * @param list The list that will be cleared.
1581 * @param data Current node's data.
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.
1586 * The following diagram ilustrates this macro iterating over a list of four
1587 * elements("one", "two", "three" and "four"):
1589 * <img src="eina-list-free.png" style="max-width: 100%;" />
1590 * <a href="eina-list-free.png">Full-size</a>
1592 * @image latex eina-list-free.eps width=\textwidth
1594 * If you do not need to release node data, it is easier to call #eina_list_free().
1600 * // list is already filled,
1601 * // its elements are just duplicated strings,
1603 * EINA_LIST_FREE(list, data)
1607 * @warning @p list must be a pointer to the first element of the list.
1609 * @see eina_list_free()
1611 #define EINA_LIST_FREE(list, data) \
1612 for (data = eina_list_data_get(list); \
1614 list = eina_list_remove_list(list, list), \
1615 data = eina_list_data_get(list))
1617 #include "eina_inline_list.x"
1631 #endif /* EINA_LIST_H_ */