forked from enlightenment/efl
parent
a6f46561e7
commit
a772d03b40
|
@ -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 <Eina.h>
|
||||
* #include <stdio.h>
|
||||
*
|
||||
* 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)
|
||||
{
|
||||
|
|
Loading…
Reference in New Issue