From 08dbadd3c1c7d67121c2127f32fa5a74624b85be Mon Sep 17 00:00:00 2001 From: Lucas De Marchi Date: Tue, 4 Sep 2012 22:56:37 +0000 Subject: [PATCH] eina: Improve doc of Eina_Inlist macros What a misleading doc we had in these macros!! Improve it: * Rename the parameter from "l" to "it", since it's not an Eina_Inlist that we are expecting, but rather its container. * Better explain each parameter... "second list" is not so good to document "list2" param * Add doc where it was missing Finally, add Changelog for the fix in EINA_INLIST_FOREACH_SAFE SVN revision: 76156 --- legacy/eina/ChangeLog | 5 +++ legacy/eina/src/include/eina_inlist.h | 44 +++++++++++++++++---------- 2 files changed, 33 insertions(+), 16 deletions(-) diff --git a/legacy/eina/ChangeLog b/legacy/eina/ChangeLog index 39662abb06..b27fa052c2 100644 --- a/legacy/eina/ChangeLog +++ b/legacy/eina/ChangeLog @@ -332,3 +332,8 @@ 2012-08-30 Carsten Haitzler (The Rasterman) 1.7.0 release + +2012-09-04 Roberto de Souza + + * Fix EINA_INLIST_FOREACH_SAFE macro to work when inlist is not the + first item in the struct. diff --git a/legacy/eina/src/include/eina_inlist.h b/legacy/eina/src/include/eina_inlist.h index c1c94df77f..6fa5bd4da7 100644 --- a/legacy/eina/src/include/eina_inlist.h +++ b/legacy/eina/src/include/eina_inlist.h @@ -790,28 +790,40 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func); _EINA_INLIST_OFFSET(ref)) #endif -/** Macro to iterate over an inlist */ -#define EINA_INLIST_FOREACH(list, l) \ - for (l = NULL, l = (list ? _EINA_INLIST_CONTAINER(l, list) : NULL); l; \ - l = (EINA_INLIST_GET(l)->next ? _EINA_INLIST_CONTAINER(l, EINA_INLIST_GET(l)->next) : NULL)) +/** + * @def EINA_INLIST_FOREACH + * @param list The list to iterate on. + * @param it The pointer to the list item, i.e. a pointer to each item + * that is part of the list. + */ +#define EINA_INLIST_FOREACH(list, it) \ + for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL); it; \ + it = (EINA_INLIST_GET(it)->next ? _EINA_INLIST_CONTAINER(it, EINA_INLIST_GET(it)->next) : NULL)) + /** * @def EINA_INLIST_FOREACH_SAFE - * @param list The first list to be used. - * @param list2 The second list to be used. - * @param l The auxiliar variable to be used. + * @param list The list to iterate on. + * @param list2 Auxiliar Eina_Inlist variable so we can save the pointer to the + * next element, allowing us to free/remove the current one. Note that this + * macro is only safe if the next element is not removed. Only the current one + * is allowed to be removed. + * @param it The pointer to the list item, i.e. a pointer to each item + * that is part of the list. */ -#define EINA_INLIST_FOREACH_SAFE(list, list2, l) \ - for (l = (list ? _EINA_INLIST_CONTAINER(l, list) : NULL), list2 = l ? ((EINA_INLIST_GET(l) ? EINA_INLIST_GET(l)->next : NULL)) : NULL; \ - l; \ - l = list2 ? _EINA_INLIST_CONTAINER(l, list2) : NULL, list2 = list2 ? list2->next : NULL) +#define EINA_INLIST_FOREACH_SAFE(list, list2, it) \ + for (it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL), list2 = it ? ((EINA_INLIST_GET(it) ? EINA_INLIST_GET(it)->next : NULL)) : NULL; \ + it; \ + it = list2 ? _EINA_INLIST_CONTAINER(it, list2) : NULL, list2 = list2 ? list2->next : NULL) + /** * @def EINA_INLIST_REVERSE_FOREACH - * @param list The list to be reversed. - * @param l The auxiliar variable to be used. + * @param list The list to traversed in reverse order. + * @param it The pointer to the list item, i.e. a pointer to each item + * that is part of the list. */ -#define EINA_INLIST_REVERSE_FOREACH(list, l) \ - for (l = NULL, l = (list ? _EINA_INLIST_CONTAINER(l, list->last) : NULL); \ - l; l = (EINA_INLIST_GET(l)->prev ? _EINA_INLIST_CONTAINER(l, EINA_INLIST_GET(l)->prev) : NULL)) +#define EINA_INLIST_REVERSE_FOREACH(list, it) \ + for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list->last) : NULL); \ + it; it = (EINA_INLIST_GET(it)->prev ? _EINA_INLIST_CONTAINER(it, EINA_INLIST_GET(it)->prev) : NULL)) /** * @}