From a772d03b40d7783afd3f86f414d52fb9834cf043 Mon Sep 17 00:00:00 2001 From: Gustavo Sverzut Barbieri Date: Tue, 14 Jul 2009 15:32:21 +0000 Subject: [PATCH] inlist: docs, docs docs SVN revision: 41328 --- legacy/eina/src/lib/eina_inlist.c | 232 ++++++++++++++++++++++++++++++ 1 file changed, 232 insertions(+) diff --git a/legacy/eina/src/lib/eina_inlist.c b/legacy/eina/src/lib/eina_inlist.c index 488b3e020c..8d922bc5e0 100644 --- a/legacy/eina/src/lib/eina_inlist.c +++ b/legacy/eina/src/lib/eina_inlist.c @@ -148,9 +148,91 @@ eina_inlist_accessor_free(Eina_Accessor_Inlist *it) { * * @brief These functions provide inline list management. * + * Inline lists mean its nodes pointers are part of same memory as + * data. This has the benefit of framenting memory less and avoiding + * @c node->data indirection, but has the drawback of elements only + * being able to be part of one single inlist at same time. But it is + * possible to have inlist nodes to be part of regular lists created + * with eina_list_append() or eina_list_prepend(). + * + * Inline lists have its purposes, but if you don't know them go with + * regular lists instead. + * + * @code + * #include + * #include + * + * int + * main(void) + * { + * struct my_struct { + * EINA_INLIST; + * int a, b; + * } *d, *cur; + * Eina_Inlist *list, *itr; + * + * eina_init(); + * + * d = malloc(sizeof(*d)); + * d->a = 1; + * d->b = 10; + * list = eina_inlist_append(NULL, EINA_INLIST_GET(d)); + * + * d = malloc(sizeof(*d)); + * d->a = 2; + * d->b = 20; + * list = eina_inlist_append(list, EINA_INLIST_GET(d)); + * + * d = malloc(sizeof(*d)); + * d->a = 3; + * d->b = 30; + * list = eina_inlist_prepend(list, EINA_INLIST_GET(d)); + * + * printf("list=%p\n", list); + * EINA_INLIST_FOREACH(list, cur) + * printf("\ta=%d, b=%d\n", cur->a, cur->b); + * + * list = eina_inlist_remove(list, EINA_INLIST_GET(d)); + * free(d); + * printf("list=%p\n", list); + * for (itr = list; itr != NULL; itr = itr->next) + * { + * cur = EINA_INLIST_CONTAINER_GET(itr, struct my_struct); + * printf("\ta=%d, b=%d\n", cur->a, cur->b); + * } + * + * while (list) + * { + * Eina_Inlist *aux = list; + * list = eina_inlist_remove(list, list); + * free(aux); + * } + * + * eina_shutdown(); + * + * return 0; + * } + * @endcode + * * @{ */ +/** + * Add a new node to end of list. + * + * @note this code is meant to be fast, appends are O(1) and do not + * walk @a list anyhow. + * + * @note @a new_l is considered to be in no list. If it was in another + * list before, please eina_inlist_remove() it before adding. No + * check of @a new_l prev and next pointers is done, so it' safe + * to have them uninitialized. + * + * @param list existing list head or NULL to create a new list. + * @param new_l new list node, must not be NULL. + * + * @return the new list head. Use it and not given @a list anymore. + */ EAPI Eina_Inlist * eina_inlist_append(Eina_Inlist *list, Eina_Inlist *new_l) { @@ -175,6 +257,22 @@ eina_inlist_append(Eina_Inlist *list, Eina_Inlist *new_l) return list; } +/** + * Add a new node to beginning of list. + * + * @note this code is meant to be fast, prepends are O(1) and do not + * walk @a list anyhow. + * + * @note @a new_l is considered to be in no list. If it was in another + * list before, please eina_inlist_remove() it before adding. No + * check of @a new_l prev and next pointers is done, so it' safe + * to have them uninitialized. + * + * @param list existing list head or NULL to create a new list. + * @param new_l new list node, must not be NULL. + * + * @return the new list head. Use it and not given @a list anymore. + */ EAPI Eina_Inlist * eina_inlist_prepend(Eina_Inlist *list, Eina_Inlist *new_l) { @@ -193,6 +291,28 @@ eina_inlist_prepend(Eina_Inlist *list, Eina_Inlist *new_l) return new_l; } +/** + * Add a new node after the given relative item in list. + * + * @note this code is meant to be fast, appends are O(1) and do not + * walk @a list anyhow. + * + * @note @a new_l is considered to be in no list. If it was in another + * list before, please eina_inlist_remove() it before adding. No + * check of @a new_l prev and next pointers is done, so it' safe + * to have them uninitialized. + * + * @note @a relative is considered to be inside @a list, no checks are + * done to confirm that and giving nodes from different lists + * will lead to problems. Giving NULL @a relative is the same as + * eina_list_append(). + * + * @param list existing list head or NULL to create a new list. + * @param new_l new list node, must not be NULL. + * @param relative reference node, @a new_l will be added after it. + * + * @return the new list head. Use it and not given @a list anymore. + */ EAPI Eina_Inlist * eina_inlist_append_relative(Eina_Inlist *list, Eina_Inlist *new_l, @@ -215,6 +335,28 @@ eina_inlist_append_relative(Eina_Inlist *list, return eina_inlist_append(list, new_l); } +/** + * Add a new node before the given relative item in list. + * + * @note this code is meant to be fast, prepends are O(1) and do not + * walk @a list anyhow. + * + * @note @a new_l is considered to be in no list. If it was in another + * list before, please eina_inlist_remove() it before adding. No + * check of @a new_l prev and next pointers is done, so it' safe + * to have them uninitialized. + * + * @note @a relative is considered to be inside @a list, no checks are + * done to confirm that and giving nodes from different lists + * will lead to problems. Giving NULL @a relative is the same as + * eina_list_prepend(). + * + * @param list existing list head or NULL to create a new list. + * @param new_l new list node, must not be NULL. + * @param relative reference node, @a new_l will be added before it. + * + * @return the new list head. Use it and not given @a list anymore. + */ EAPI Eina_Inlist * eina_inlist_prepend_relative(Eina_Inlist *list, Eina_Inlist *new_l, @@ -243,6 +385,23 @@ eina_inlist_prepend_relative(Eina_Inlist *list, return eina_inlist_prepend(list, new_l); } +/** + * Remove node from list. + * + * @note this code is meant to be fast, removals are O(1) and do not + * walk @a list anyhow. + * + * @note @a item is considered to be inside @a list, no checks are + * done to confirm that and giving nodes from different lists + * will lead to problems, specially if @a item is the head since + * it will be different from @a list and the wrong new head will + * be returned. + * + * @param list existing list head, must not be NULL. + * @param item existing list node, must not be NULL. + * + * @return the new list head. Use it and not given @a list anymore. + */ EAPI Eina_Inlist * eina_inlist_remove(Eina_Inlist *list, Eina_Inlist *item) { @@ -272,6 +431,21 @@ eina_inlist_remove(Eina_Inlist *list, Eina_Inlist *item) return return_l; } +/** + * Move existing node to beginning of list. + * + * @note this code is meant to be fast, promotion is O(1) and do not + * walk @a list anyhow. + * + * @note @a item is considered to be inside @a list, no checks are + * done to confirm that and giving nodes from different lists + * will lead to problems. + * + * @param list existing list head or NULL to create a new list. + * @param item list node to move to beginning (head), must not be NULL. + * + * @return the new list head. Use it and not given @a list anymore. + */ EAPI Eina_Inlist * eina_inlist_promote(Eina_Inlist *list, Eina_Inlist *item) { @@ -297,6 +471,21 @@ eina_inlist_promote(Eina_Inlist *list, Eina_Inlist *item) return item; } +/** + * Move existing node to end of list. + * + * @note this code is meant to be fast, demoting is O(1) and do not + * walk @a list anyhow. + * + * @note @a item is considered to be inside @a list, no checks are + * done to confirm that and giving nodes from different lists + * will lead to problems. + * + * @param list existing list head or NULL to create a new list. + * @param item list node to move to end (tail), must not be NULL. + * + * @return the new list head. Use it and not given @a list anymore. + */ EAPI Eina_Inlist * eina_inlist_demote(Eina_Inlist *list, Eina_Inlist *item) { @@ -329,6 +518,17 @@ eina_inlist_demote(Eina_Inlist *list, Eina_Inlist *item) return l; } +/** + * Find given node in list, returns itself if found, NULL if not. + * + * @warning this is an expensive call and have O(n) cost, possibly + * walking the whole list. + * + * @param list existing list to search @a item in, must not be NULL. + * @param item what to search for, must not be NULL. + * + * @return @a item if found, NULL if not. + */ EAPI Eina_Inlist * eina_inlist_find(Eina_Inlist *list, Eina_Inlist *item) { @@ -366,6 +566,26 @@ eina_inlist_count(const Eina_Inlist *list) return i; } +/** + * @brief Returned a new iterator asociated to a list. + * + * @param list The list. + * @return A new iterator. + * + * This function returns a newly allocated iterator associated to @p + * list. If @p list is @c NULL or the count member of @p list is less + * or equal than 0, this function still returns a valid iterator that + * will always return false on eina_iterator_next(), thus keeping API + * sane. + * + * If the memory can not be allocated, NULL is returned and + * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is + * returned. + * + * @warning if the list structure changes then the iterator becomes + * invalid! That is, if you add or remove nodes this iterator + * behavior is undefined and your program may crash! + */ EAPI Eina_Iterator * eina_inlist_iterator_new(const Eina_Inlist *list) { @@ -390,6 +610,18 @@ eina_inlist_iterator_new(const Eina_Inlist *list) return &it->iterator; } +/** + * @brief Returned a new accessor asociated to a list. + * + * @param list The list. + * @return A new accessor. + * + * This function returns a newly allocated accessor associated to + * @p list. If @p list is @c NULL or the count member of @p list is + * less or equal than 0, this function returns NULL. If the memory can + * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is + * set. Otherwise, a valid accessor is returned. + */ EAPI Eina_Accessor * eina_inlist_accessor_new(const Eina_Inlist *list) {