These functions provide double linked list management. More...

Data Structures

struct  _Eina_List
 Type for a generic double linked list. More...
 
struct  _Eina_List_Accounting
 Cache used to store the last element of a list and the number of elements, for fast access. More...
 

Macros

#define EINA_LIST_FOREACH(list, l, data)
 Macro to iterate over a list. More...
 
#define EINA_LIST_REVERSE_FOREACH(list, l, data)
 Macro to iterate over a list in the reverse order. More...
 
#define EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
 Macro to iterate over a list with support for node deletion. More...
 
#define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data)
 Macro to iterate over a list in the reverse order with support for deletion. More...
 
#define EINA_LIST_FREE(list, data)
 Macro to remove each list node while having access to each node's data. More...
 

Typedefs

typedef struct _Eina_List Eina_List
 Type for a generic double linked list.
 
typedef struct
_Eina_List_Accounting 
Eina_List_Accounting
 Cache used to store the last element of a list and the number of elements, for fast access.
 

Functions

Eina_Listeina_list_append (Eina_List *list, const void *data)
 Append the given data to the given linked list. More...
 
Eina_Listeina_list_prepend (Eina_List *list, const void *data)
 Prepends the given data to the given linked list. More...
 
Eina_Listeina_list_append_relative (Eina_List *list, const void *data, const void *relative)
 Insert the given data into the given linked list after the specified data. More...
 
Eina_Listeina_list_append_relative_list (Eina_List *list, const void *data, Eina_List *relative)
 Append a list node to a linked list after the specified member. More...
 
Eina_Listeina_list_prepend_relative (Eina_List *list, const void *data, const void *relative)
 Prepend a data pointer to a linked list before the specified member. More...
 
Eina_Listeina_list_prepend_relative_list (Eina_List *list, const void *data, Eina_List *relative)
 Prepend a list node to a linked list before the specified member. More...
 
Eina_Listeina_list_sorted_insert (Eina_List *list, Eina_Compare_Cb func, const void *data)
 Insert a new node into a sorted list. More...
 
Eina_Listeina_list_remove (Eina_List *list, const void *data)
 Remove the first instance of the specified data from the given list. More...
 
Eina_Listeina_list_remove_list (Eina_List *list, Eina_List *remove_list)
 Remove the specified list node. More...
 
Eina_Listeina_list_promote_list (Eina_List *list, Eina_List *move_list)
 Move the specified data to the head of the list. More...
 
Eina_Listeina_list_demote_list (Eina_List *list, Eina_List *move_list)
 Move the specified data to the tail of the list. More...
 
void * eina_list_data_find (const Eina_List *list, const void *data)
 Find a member of a list and return the member. More...
 
Eina_Listeina_list_data_find_list (const Eina_List *list, const void *data)
 Find a member of a list and return the list node containing that member. More...
 
Eina_Bool eina_list_move (Eina_List **to, Eina_List **from, void *data)
 Move a data pointer from one list to another. More...
 
Eina_Bool eina_list_move_list (Eina_List **to, Eina_List **from, Eina_List *data)
 Move a list node from one list to another. More...
 
Eina_Listeina_list_free (Eina_List *list)
 Free an entire list and all the nodes, ignoring the data contained. More...
 
void * eina_list_nth (const Eina_List *list, unsigned int n)
 Get the nth member's data pointer in a list. More...
 
Eina_Listeina_list_nth_list (const Eina_List *list, unsigned int n)
 Get the nth member's list node in a list. More...
 
Eina_Listeina_list_reverse (Eina_List *list)
 Reverse all the elements in the list. More...
 
Eina_Listeina_list_reverse_clone (const Eina_List *list)
 Clone (copy) all the elements in the list in reverse order. More...
 
Eina_Listeina_list_clone (const Eina_List *list)
 Clone (copy) all the elements in the list in exactly same order. More...
 
Eina_Listeina_list_sort (Eina_List *list, unsigned int limit, Eina_Compare_Cb func)
 Sort a list according to the ordering func will return. More...
 
Eina_Listeina_list_merge (Eina_List *left, Eina_List *right)
 Merge two list. More...
 
Eina_Listeina_list_sorted_merge (Eina_List *left, Eina_List *right, Eina_Compare_Cb func)
 Merge two sorted list according to the ordering func will return. More...
 
Eina_Listeina_list_split_list (Eina_List *list, Eina_List *relative, Eina_List **right)
 Split a list into 2 lists. More...
 
Eina_Listeina_list_search_sorted_near_list (const Eina_List *list, Eina_Compare_Cb func, const void *data, int *result_cmp)
 Returns node nearest to data is in the sorted list. More...
 
Eina_Listeina_list_search_sorted_list (const Eina_List *list, Eina_Compare_Cb func, const void *data)
 Returns node if data is in the sorted list. More...
 
void * eina_list_search_sorted (const Eina_List *list, Eina_Compare_Cb func, const void *data)
 Returns node data if it is in the sorted list. More...
 
Eina_Listeina_list_search_unsorted_list (const Eina_List *list, Eina_Compare_Cb func, const void *data)
 Returns node if data is in the unsorted list. More...
 
void * eina_list_search_unsorted (const Eina_List *list, Eina_Compare_Cb func, const void *data)
 Returns node data if it is in the unsorted list. More...
 
static Eina_Listeina_list_last (const Eina_List *list)
 Get the last list node in the list. More...
 
static Eina_Listeina_list_next (const Eina_List *list)
 Get the next list node after the specified list node. More...
 
static Eina_Listeina_list_prev (const Eina_List *list)
 Get the previous list node before the specified list node. More...
 
static void * eina_list_data_get (const Eina_List *list)
 Get the list node data member. More...
 
static void * eina_list_data_set (Eina_List *list, const void *data)
 Set the list node data member. More...
 
static unsigned int eina_list_count (const Eina_List *list)
 Get the count of the number of items in a list. More...
 
Eina_Iteratoreina_list_iterator_new (const Eina_List *list)
 Returned a new iterator associated to a list. More...
 
Eina_Iteratoreina_list_iterator_reversed_new (const Eina_List *list)
 Returned a new reversed iterator associated to a list. More...
 
Eina_Accessoreina_list_accessor_new (const Eina_List *list)
 Returned a new accessor associated to a list. More...
 

Detailed Description

These functions provide double linked list management.

Eina_List is a doubly linked list. It can store data of any type in the form of void pointers. It has convenience functions to do all the common operations which means it should rarely if ever be necessary to directly access the struct's fields. Nevertheless it can be useful to understand the inner workings of the data structure being used.

Eina_List nodes keep references to the previous node, the next node, its data and to an accounting structure.

Full-size

Eina_List_Accounting is used to improve the performance of some functions. It is private and should not be modified. It contains a reference to the end of the list and the number of elements in the list.

Note
Every function that modifies the contents of the list returns a pointer to the head of the list and it is essential that this be pointer be used in any future references to the list.

Most functions have two versions that have the same effect but operate on different arguments, the plain functions operate over data(eg.: eina_list_append_relative, eina_list_remove, eina_list_data_find), the list versions of these functions operate on Eina_List nodes.

Warning
You must always use the pointer to the first element of the list as the list!
You must never use a pointer to an element in the middle of the list as the list!

Here are some examples of Eina_List usage:

Macro Definition Documentation

#define EINA_LIST_FOREACH (   list,
  l,
  data 
)
Value:
for (l = list, \
data = eina_list_data_get(l); \
l; \
l = eina_list_next(l), \
data = eina_list_data_get(l))
static void * eina_list_data_get(const Eina_List *list)
Get the list node data member.
static Eina_List * eina_list_next(const Eina_List *list)
Get the next list node after the specified list node.

Macro to iterate over a list.

Parameters
listThe list to iterate over.
lA list that is used as an iterator and points to the current node.
dataCurrent item's data.

This macro iterates over list from the first element to the last. data is the data related to the current element. l is an Eina_List used as the list iterator.

The following diagram ilustrates this macro iterating over a list of four elements("one", "two", "three" and "four"): Full-size

It can be used to free list data, as in the following example:

Eina_List *list;
char *data;
// list is already filled,
// its elements are just duplicated strings,
// EINA_LIST_FOREACH will be used to free those strings
EINA_LIST_FOREACH(list, l, data)
free(data);
Note
This is not the optimal way to release memory allocated to a list, since it iterates over the list twice. For an optimized algorithm, use EINA_LIST_FREE().
Warning
list must be a pointer to the first element of the list.
Be careful when deleting list nodes. If you remove the current node and continue iterating, the code will fail because the macro will not be able to get the next node. Notice that it's OK to remove any node if you stop the loop after that. For destructive operations such as this, consider using EINA_LIST_FOREACH_SAFE().
Examples:
eina_list_01.c.

Referenced by eina_list_append_relative(), eina_list_clone(), eina_list_data_find_list(), eina_list_prepend_relative(), eina_list_reverse_clone(), and eina_list_search_unsorted_list().

#define EINA_LIST_REVERSE_FOREACH (   list,
  l,
  data 
)
Value:
for (l = eina_list_last(list), \
data = eina_list_data_get(l); \
l; \
l = eina_list_prev(l), \
data = eina_list_data_get(l))
static void * eina_list_data_get(const Eina_List *list)
Get the list node data member.
static Eina_List * eina_list_last(const Eina_List *list)
Get the last list node in the list.
static Eina_List * eina_list_prev(const Eina_List *list)
Get the previous list node before the specified list node.

Macro to iterate over a list in the reverse order.

Parameters
listThe list to iterate over.
lA list that is used as an iterator and points to the current node.
dataCurrent item's data.

This macro works like EINA_LIST_FOREACH, but iterates from the last element of a list to the first. data is the data related to the current element, while l is an Eina_List that is used as the list iterator.

The following diagram ilustrates this macro iterating over a list of four elements("one", "two", "three" and "four"): Full-size

It can be used to free list data, as in the following example:

Eina_List *list;
char *data;
// list is already filled,
// its elements are just duplicated strings,
// EINA_LIST_REVERSE_FOREACH will be used to free those strings
free(data);
Note
This is not the optimal way to release memory allocated to a list, since it iterates over the list twice. For an optimized algorithm, use EINA_LIST_FREE().
Warning
list must be a pointer to the first element of the list.
Be careful when deleting list nodes. If you remove the current node and continue iterating, the code will fail because the macro will not be able to get the next node. Notice that it's OK to remove any node if you stop the loop after that. For destructive operations such as this, consider using EINA_LIST_REVERSE_FOREACH_SAFE().
#define EINA_LIST_FOREACH_SAFE (   list,
  l,
  l_next,
  data 
)
Value:
for (l = list, \
l_next = eina_list_next(l), \
data = eina_list_data_get(l); \
l; \
l = l_next, \
l_next = eina_list_next(l), \
data = eina_list_data_get(l))
static void * eina_list_data_get(const Eina_List *list)
Get the list node data member.
static Eina_List * eina_list_next(const Eina_List *list)
Get the next list node after the specified list node.

Macro to iterate over a list with support for node deletion.

Parameters
listThe list to iterate over.
lA list that is used as an iterator and points to the current node.
l_nextA list that is used as an iterator and points to the next node.
dataCurrent item's data.

This macro iterates over list from the first element to the last. data is the data related to the current element. l is an Eina_List used as the list iterator.

Since this macro stores a pointer to the next list node in l_next, deleting the current node and continuing looping is safe.

The following diagram ilustrates this macro iterating over a list of four elements("one", "two", "three" and "four"): Full-size

This macro can be used to free list nodes, as in the following example:

Eina_List *list;
Eina_List *l_next;
char *data;
// list is already filled,
// its elements are just duplicated strings,
// EINA_LIST_FOREACH_SAFE will be used to free elements that match "key".
EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
if (strcmp(data, "key") == 0) {
free(data);
list = eina_list_remove_list(list, l);
}
Warning
list must be a pointer to the first element of the list.
#define EINA_LIST_REVERSE_FOREACH_SAFE (   list,
  l,
  l_prev,
  data 
)
Value:
for (l = eina_list_last(list), \
l_prev = eina_list_prev(l), \
data = eina_list_data_get(l); \
l; \
l = l_prev, \
l_prev = eina_list_prev(l), \
data = eina_list_data_get(l))
static void * eina_list_data_get(const Eina_List *list)
Get the list node data member.
static Eina_List * eina_list_last(const Eina_List *list)
Get the last list node in the list.
static Eina_List * eina_list_prev(const Eina_List *list)
Get the previous list node before the specified list node.

Macro to iterate over a list in the reverse order with support for deletion.

Parameters
listThe list to iterate over.
lA list that is used as an iterator and points to the current node.
l_prevA list that is used as an iterator and points to the previous node.
dataCurrent item's data.

This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the last element of a list to the first. data is the data related to the current element, while l is an Eina_List that is used as the list iterator.

Since this macro stores a pointer to the previous list node in l_prev, deleting the current node and continuing looping is safe.

The following diagram ilustrates this macro iterating over a list of four elements("one", "two", "three" and "four"): Full-size

This macro can be used to free list nodes, as in the following example:

Eina_List *list;
Eina_List *l_prev;
char *data;
// list is already filled,
// its elements are just duplicated strings,
// EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that match "key".
EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data)
if (strcmp(data, "key") == 0) {
free(data);
list = eina_list_remove_list(list, l);
}
Warning
list must be a pointer to the first element of the list.
#define EINA_LIST_FREE (   list,
  data 
)
Value:
for (data = eina_list_data_get(list); \
list; \
list = eina_list_remove_list(list, list), \
data = eina_list_data_get(list))
static void * eina_list_data_get(const Eina_List *list)
Get the list node data member.
Eina_List * eina_list_remove_list(Eina_List *list, Eina_List *remove_list)
Remove the specified list node.
Definition: eina_list.c:720

Macro to remove each list node while having access to each node's data.

Parameters
listThe list that will be cleared.
dataCurrent node's data.

This macro will call eina_list_remove_list for each list node, and store the data contained in the current node in data.

The following diagram ilustrates this macro iterating over a list of four elements("one", "two", "three" and "four"): Full-size

If you do not need to release node data, it is easier to call eina_list_free().

Eina_List *list;
char *data;
// list is already filled,
// its elements are just duplicated strings,
EINA_LIST_FREE(list, data)
free(data);
Warning
list must be a pointer to the first element of the list.
See also
eina_list_free()
Examples:
eina_list_04.c, and eina_tiler_01.c.

Referenced by eina_benchmark_free().

Function Documentation

Eina_List* eina_list_append ( Eina_List list,
const void *  data 
)

Append the given data to the given linked list.

Parameters
listThe given list.
dataThe data to append.
Returns
A list pointer.

This function appends data to list. If list is NULL, a new list is returned. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

The following example code demonstrates how to ensure that the given data has been successfully appended.

Eina_List *list = NULL;
extern void *my_data;
list = eina_list_append(list, my_data);
{
fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
exit(-1);
}
Warning
list must be a pointer to the first element of the list(or NULL).
Examples:
eina_accessor_01.c, eina_iterator_01.c, eina_list_01.c, eina_list_02.c, eina_list_03.c, eina_list_04.c, and eina_tiler_01.c.

References _Eina_List::accounting, _Eina_List::data, eina_error_set(), _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by eina_benchmark_run(), eina_list_append_relative(), eina_list_append_relative_list(), eina_list_clone(), eina_list_move(), eina_list_move_list(), eina_list_sorted_insert(), and eina_rectangle_pool_new().

Eina_List* eina_list_prepend ( Eina_List list,
const void *  data 
)

Prepends the given data to the given linked list.

Parameters
listThe given list.
dataThe data to prepend.
Returns
A list pointer.

This function prepends data to list. If list is NULL, a new list is returned. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

The following example code demonstrates how to ensure that the given data has been successfully prepended.

Example:

Eina_List *list = NULL;
extern void *my_data;
list = eina_list_prepend(list, my_data);
{
fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
exit(-1);
}
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_01.c.

References _Eina_List::data, eina_error_set(), _Eina_List::next, and _Eina_List::prev.

Referenced by eina_list_prepend_relative(), eina_list_prepend_relative_list(), and eina_list_reverse_clone().

Eina_List* eina_list_append_relative ( Eina_List list,
const void *  data,
const void *  relative 
)

Insert the given data into the given linked list after the specified data.

Parameters
listThe given linked list.
dataThe data to insert.
relativeThe data to insert after.
Returns
A list pointer.

This function inserts data to list after relative. If relative is not in the list, data is appended to the end of the list. If list is NULL, a new list is returned. If there are multiple instances of relative in the list, data is inserted after the first instance.On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

The following example code demonstrates how to ensure that the given data has been successfully inserted.

Eina_List *list = NULL;
extern void *my_data;
extern void *relative_member;
list = eina_list_append(list, relative_member);
{
fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
exit(-1);
}
list = eina_list_append_relative(list, my_data, relative_member);
{
fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
exit(-1);
}
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_01.c.

References eina_list_append(), eina_list_append_relative_list(), and EINA_LIST_FOREACH.

Eina_List* eina_list_append_relative_list ( Eina_List list,
const void *  data,
Eina_List relative 
)

Append a list node to a linked list after the specified member.

Parameters
listThe given linked list.
dataThe data to insert.
relativeThe list node to insert after.
Returns
A list pointer.

This function inserts data to list after the list node relative. If list or relative are NULL, data is just appended to list using eina_list_append(). If list is NULL, a new list is returned. If there are multiple instances of relative in the list, data is inserted after the first instance. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_01.c, and eina_list_02.c.

References _Eina_List::accounting, _Eina_List::data, eina_error_set(), eina_list_append(), _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by eina_list_append_relative(), and eina_list_sorted_insert().

Eina_List* eina_list_prepend_relative ( Eina_List list,
const void *  data,
const void *  relative 
)

Prepend a data pointer to a linked list before the specified member.

Parameters
listThe given linked list.
dataThe data to insert.
relativeThe data to insert before.
Returns
A list pointer.

This function inserts data to list before relative. If relative is not in the list, data is prepended to the list with eina_list_prepend(). If list is NULL, a new list is returned. If there are multiple instances of relative in the list, data is inserted before the first instance. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

The following code example demonstrates how to ensure that the given data has been successfully inserted.

Eina_List *list = NULL;
extern void *my_data;
extern void *relative_member;
list = eina_list_append(list, relative_member);
if (eina_error_get_error())
{
fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
exit(-1);
}
list = eina_list_prepend_relative(list, my_data, relative_member);
{
fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
exit(-1);
}
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_01.c.

References EINA_LIST_FOREACH, eina_list_prepend(), and eina_list_prepend_relative_list().

Eina_List* eina_list_prepend_relative_list ( Eina_List list,
const void *  data,
Eina_List relative 
)

Prepend a list node to a linked list before the specified member.

Parameters
listThe given linked list.
dataThe data to insert.
relativeThe list node to insert before.
Returns
A list pointer.

This function inserts data to list before the list node relative. If list or relative are NULL, data is just prepended to list using eina_list_prepend(). If list is NULL, a new list is returned. If there are multiple instances of relative in the list, data is inserted before the first instance. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_01.c, and eina_list_02.c.

References _Eina_List::data, eina_error_set(), eina_list_prepend(), _Eina_List::next, and _Eina_List::prev.

Referenced by eina_list_prepend_relative(), and eina_list_sorted_insert().

Eina_List* eina_list_sorted_insert ( Eina_List list,
Eina_Compare_Cb  func,
const void *  data 
)

Insert a new node into a sorted list.

Parameters
listThe given linked list, must be sorted.
funcThe function called for the sort.
dataThe data to insert sorted.
Returns
A list pointer.

This function inserts values into a linked list assuming it was sorted and the result will be sorted. If list is NULLL, a new list is returned. On success, a new list pointer that should be used in place of the one given to this function is returned. Otherwise, the old pointer is returned. See eina_error_get().

Note
O(log2(n)) comparisons (calls to func) average/worst case performance as it uses eina_list_search_sorted_near_list() and thus is bounded to that. As said in eina_list_search_sorted_near_list(), lists do not have O(1) access time, so walking to the correct node can be costly, consider worst case to be almost O(n) pointer dereference (list walk).
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_02.c.

References eina_list_append(), eina_list_append_relative_list(), eina_list_prepend_relative_list(), and eina_list_search_sorted_near_list().

Eina_List* eina_list_remove ( Eina_List list,
const void *  data 
)

Remove the first instance of the specified data from the given list.

Parameters
listThe given list.
dataThe specified data.
Returns
A list pointer.

This function removes the first instance of data from list. If the specified data is not in the given list (tihis include the case where data is NULL), nothing is done. If list is NULL, NULL is returned, otherwise a new list pointer that should be used in place of the one passed to this function.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_03.c.

References eina_list_data_find_list(), and eina_list_remove_list().

Eina_List* eina_list_remove_list ( Eina_List list,
Eina_List remove_list 
)

Remove the specified list node.

Parameters
listThe given linked list.
remove_listThe list node which is to be removed.
Returns
A list pointer.

This function removes the list node remove_list from list and frees the list node structure remove_list. If list is NULL, this function returns NULL. If remove_list is NULL, it returns list, otherwise, a new list pointer that should be used in place of the one passed to this function.

The following code gives an example (notice we use EINA_LIST_FOREACH instead of EINA_LIST_FOREACH_SAFE because we stop the loop after removing the current node).

extern Eina_List *list;
extern void *my_data;
void *data
EINA_LIST_FOREACH(list, l, data)
{
if (data == my_data)
{
list = eina_list_remove_list(list, l);
break;
}
}
Warning
list must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by eina_list_move(), eina_list_move_list(), and eina_list_remove().

Eina_List* eina_list_promote_list ( Eina_List list,
Eina_List move_list 
)

Move the specified data to the head of the list.

Parameters
listThe list handle to move the data.
move_listThe list node to move.
Returns
A new list handle to replace the old one

This function move move_list to the front of list. If list is NULL, NULL is returned. If move_list is NULL, list is returned. Otherwise, a new list pointer that should be used in place of the one passed to this function.

Example:

extern Eina_List *list;
extern void *my_data;
void *data;
EINA_LIST_FOREACH(list, l, data)
{
if (data == my_data)
{
list = eina_list_promote_list(list, l);
break;
}
}
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_03.c.

References _Eina_List::accounting, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Eina_List* eina_list_demote_list ( Eina_List list,
Eina_List move_list 
)

Move the specified data to the tail of the list.

Parameters
listThe list handle to move the data.
move_listThe list node to move.
Returns
A new list handle to replace the old one

This function move move_list to the back of list. If list is NULL, NULL is returned. If move_list is NULL, list is returned. Otherwise, a new list pointer that should be used in place of the one passed to this function.

Example:

extern Eina_List *list;
extern void *my_data;
void *data;
EINA_LIST_FOREACH(list, l, data)
{
if (data == my_data)
{
list = eina_list_demote_list(list, l);
break;
}
}
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_03.c.

References _Eina_List::accounting, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

void* eina_list_data_find ( const Eina_List list,
const void *  data 
)

Find a member of a list and return the member.

Parameters
listThe list to search for a data.
dataThe data pointer to find in the list.
Returns
The found member data pointer if found, NULL otherwise.

This function searches in list from beginning to end for the first member whose data pointer is data. If it is found, data will be returned, otherwise NULL will be returned.

Example:

extern Eina_List *list;
extern void *my_data;
if (eina_list_data_find(list, my_data) == my_data)
{
printf("Found member %p\n", my_data);
}
Warning
list must be a pointer to the first element of the list.

References eina_list_data_find_list().

Eina_List* eina_list_data_find_list ( const Eina_List list,
const void *  data 
)

Find a member of a list and return the list node containing that member.

Parameters
listThe list to search for data.
dataThe data pointer to find in the list.
Returns
The found members list node on success, NULL otherwise.

This function searches in list from beginning to end for the first member whose data pointer is data. If it is found, the list node containing the specified member is returned, otherwise NULL is returned.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_03.c.

References EINA_LIST_FOREACH.

Referenced by eina_list_data_find(), eina_list_move(), and eina_list_remove().

Eina_Bool eina_list_move ( Eina_List **  to,
Eina_List **  from,
void *  data 
)

Move a data pointer from one list to another.

Parameters
toThe list to move the data to
fromThe list to move from
dataThe data to move
Returns
EINA_TRUE on success, else EINA_FALSE

This function is a shortcut for doing the following: to = eina_list_append(to, data); from = eina_list_remove(from, data);

Warning
list must be a pointer to the first element of the list.

References EINA_FALSE, eina_list_append(), eina_list_data_find_list(), eina_list_remove_list(), and EINA_TRUE.

Eina_Bool eina_list_move_list ( Eina_List **  to,
Eina_List **  from,
Eina_List data 
)

Move a list node from one list to another.

Parameters
toThe list to move the data to
fromThe list to move from
dataThe list node containing the data to move
Returns
EINA_TRUE on success, else EINA_FALSE

This function is a shortcut for doing the following: to = eina_list_append(to, data->data); from = eina_list_remove_list(from, data);

Warning
list must be a pointer to the first element of the list.

References _Eina_List::data, EINA_FALSE, eina_list_append(), eina_list_remove_list(), and EINA_TRUE.

Eina_List* eina_list_free ( Eina_List list)

Free an entire list and all the nodes, ignoring the data contained.

Parameters
listThe list to free
Returns
A NULL pointer

This function frees all the nodes of list. It does not free the data of the nodes. To free them, use EINA_LIST_FREE.

Examples:
eina_accessor_01.c, eina_iterator_01.c, eina_list_01.c, eina_list_02.c, eina_list_03.c, and eina_tiler_01.c.

References _Eina_List::next.

void* eina_list_nth ( const Eina_List list,
unsigned int  n 
)

Get the nth member's data pointer in a list.

Parameters
listThe list to get the specified member number from.
nThe number of the element (0 being the first).
Returns
The data pointer stored in the specified element.

This function returns the data pointer of element number n, in the list. The first element in the array is element number 0. If the element number n does not exist, NULL is returned. Otherwise, the data of the found element is returned.

Note
Worst case is O(n).
Warning
list must be a pointer to the first element of the list.

References _Eina_List::data, and eina_list_nth_list().

Eina_List* eina_list_nth_list ( const Eina_List list,
unsigned int  n 
)

Get the nth member's list node in a list.

Parameters
listThe list to get the specfied member number from.
nThe number of the element (0 being the first).
Returns
The list node stored in the numbered element.

This function returns the list node of element number n, in list. The first element in the array is element number 0. If the element number n does not exist or list is NULL or n is greater than the count of elements in list minus 1, NULL is returned. Otherwise the list node stored in the numbered element is returned.

Note
Worst case is O(n).
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_01.c, and eina_list_03.c.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by eina_list_nth(), and eina_list_sort().

Eina_List* eina_list_reverse ( Eina_List list)

Reverse all the elements in the list.

Parameters
listThe list to reverse.
Returns
The list head after it has been reversed.

This function reverses the order of all elements in list, so the last member is now first, and so on. If list is NULL, this functon returns NULL.

Note
in-place: this will change the given list, so you should now point to the new list head that is returned by this function.
Warning
list must be a pointer to the first element of the list.
See also
eina_list_reverse_clone()
eina_list_iterator_reversed_new()

References _Eina_List::accounting, _Eina_List::data, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Eina_List* eina_list_reverse_clone ( const Eina_List list)

Clone (copy) all the elements in the list in reverse order.

Parameters
listThe list to reverse.
Returns
The new list that has been reversed.

This function reverses the order of all elements in list, so the last member is now first, and so on. If list is NULL, this functon returns NULL. This returns a copy of the given list.

Note
copy: this will copy the list and you should then eina_list_free() when it is not required anymore.
Warning
list must be a pointer to the first element of the list.
See also
eina_list_reverse()
eina_list_clone()
Examples:
eina_list_03.c.

References EINA_LIST_FOREACH, and eina_list_prepend().

Eina_List* eina_list_clone ( const Eina_List list)

Clone (copy) all the elements in the list in exactly same order.

Parameters
listThe list to clone.
Returns
The new list that has been cloned.

This function clone in order of all elements in list. If list is NULL, this functon returns NULL. This returns a copy of the given list.

Note
copy: this will copy the list and you should then eina_list_free() when it is not required anymore.
Warning
list must be a pointer to the first element of the list.
See also
eina_list_reverse_clone()

References eina_list_append(), and EINA_LIST_FOREACH.

Eina_List* eina_list_sort ( Eina_List list,
unsigned int  limit,
Eina_Compare_Cb  func 
)

Sort a list according to the ordering func will return.

Parameters
listThe list handle to sort.
limitThe maximum number of list elements to sort.
funcA function pointer that can handle comparing the list data nodes.
Returns
the new head of list.

This function sorts list. size if the number of the first element to sort. If limit is 0 or greater than the number of elements in list, all the elements are sorted. func is used to compare two elements of list. If list or func are NULL, this function returns NULL.

Note
in-place: this will change the given list, so you should now point to the new list head that is returned by this function.
worst case is O(n * log2(n)) comparisons (calls to func()), O(n) comparisons average case. That means that for 1,000,000 list elements, sort will usually do 1,000,000 comparisons, but may do up to 20,000,000.

Example:

int
sort_cb(const void *d1, const void *d2)
{
const char *txt = d1;
const char *txt2 = d2;
if(!txt) return(1);
if(!txt2) return(-1);
return(strcmp(txt, txt2));
}
extern Eina_List *list;
list = eina_list_sort(list, eina_list_count(list), sort_cb);
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_02.c.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List::data, eina_list_nth_list(), _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Referenced by eina_rectangle_pool_request().

Eina_List* eina_list_merge ( Eina_List left,
Eina_List right 
)

Merge two list.

Parameters
leftHead list to merge.
rightTail list to merge.
Returns
A new merged list.

This function puts right at the end of left and returns the head.

Both left and right do not exist anymore after the merge.

Note
merge cost is O(n), being n the size of the smallest list. This is due the need to fix accounting of that segment, making count and last access O(1).
Warning
list must be a pointer to the first element of the list.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Eina_List* eina_list_sorted_merge ( Eina_List left,
Eina_List right,
Eina_Compare_Cb  func 
)

Merge two sorted list according to the ordering func will return.

Parameters
leftFirst list to merge.
rightSecond list to merge.
funcA function pointer that can handle comparing the list data nodes.
Returns
A new sorted list.

This function compares the head of left and right, and choose the smallest one to be head of the returned list. It will continue this process for all entry of both list.

Both left and right do not exist anymore after the merge. If func is NULL, it will return NULL.

Example:

int
sort_cb(void *d1, void *d2)
{
const char *txt = NULL;
const char *txt2 = NULL;
if(!d1) return(1);
if(!d2) return(-1);
return(strcmp((const char*)d1, (const char*)d2));
}
extern Eina_List *sorted1;
extern Eina_List *sorted2;
list = eina_list_sorted_merge(sorted1, sorted2, sort_cb);
Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_02.c.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List::data, _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Eina_List* eina_list_split_list ( Eina_List list,
Eina_List relative,
Eina_List **  right 
)

Split a list into 2 lists.

Parameters
listList to split.
relativeThe list will be split after relative.
rightThe head of the new right list.
Returns
The new left list

This function splits list into two lists ( left and right ) after the node relative. Relative will become the last node of the left list. If list or right are NULL list is returns. If relative is NULL right is set to list and NULL is returns. If relative is the last node of list list is returns and right is set to NULL.

list does not exist anymore after the split.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_02.c.

References _Eina_List::accounting, _Eina_List_Accounting::count, eina_list_last(), eina_list_next(), _Eina_List_Accounting::last, _Eina_List::next, and _Eina_List::prev.

Eina_List* eina_list_search_sorted_near_list ( const Eina_List list,
Eina_Compare_Cb  func,
const void *  data,
int *  result_cmp 
)

Returns node nearest to data is in the sorted list.

Parameters
listThe list to search for data, must be sorted.
funcA function pointer that can handle comparing the list data nodes.
datareference value to search.
result_cmpif provided returns the result of func(node->data, data) node being the last (returned) node. If node was found (exact match), then it is 0. If returned node is smaller than requested data, it is less than 0 and if it's bigger it's greater than 0. It is the last value returned by func().
Returns
the nearest node, NULL if not found.

This function searches for a node containing data as it's data in list, if such a node exists it will be returned and result_cmp will be 0. If the data of no node in list is equal to data, the node with the nearest value to that will be returned and result_cmp will be the return value of func with data and the returned node's data as arguments.

This function is useful for inserting an element in the list only in case it isn't already present in the list, the naive way of doing this would be:

void *ptr = eina_list_data_find(list, "my data");
if (!ptr)
eina_list_sorted_insert(list, "my data");

However this has the downside of walking through the list twice, once to check if the data is already present and another to insert the element in the corret position. This can be done more eficiently:

int cmp_result;
l = eina_list_search_sorted_near_list(list, cmp_func, "my data",
&cmp_result);
if (cmp_result > 0)
list = eina_list_prepend_relative_list(list, "my data", l);
else if (cmp_result < 0)
list = eina_list_append_relative_list(list, "my data", l);

If cmp_result is 0 the element is already in the list and we need not insert it, if cmp_result is greater than zero "my @a data" needs to come after l(the nearest node present), if less than zero before.

Note
O(log2(n)) average/worst case performance, for 1,000,000 elements it will do a maximum of 20 comparisons. This is much faster than the 1,000,000 comparisons made naively walking the list from head to tail, so depending on the number of searches and insertions, it may be worth to eina_list_sort() the list and do the searches later. As lists do not have O(1) access time, walking to the correct node can be costly, consider worst case to be almost O(n) pointer dereference (list walk).
Warning
list must be a pointer to the first element of the list.
See also
eina_list_search_sorted_list()
eina_list_sort()
eina_list_sorted_merge()
Examples:
eina_list_02.c.

References _Eina_List::accounting, _Eina_List_Accounting::count, _Eina_List::data, _Eina_List_Accounting::last, and _Eina_List::next.

Referenced by eina_list_search_sorted_list(), and eina_list_sorted_insert().

Eina_List* eina_list_search_sorted_list ( const Eina_List list,
Eina_Compare_Cb  func,
const void *  data 
)

Returns node if data is in the sorted list.

Parameters
listThe list to search for data, must be sorted.
funcA function pointer that can handle comparing the list data nodes.
datareference value to search.
Returns
the node if func(node->data, data) == 0, NULL if not found.

This can be used to check if some value is inside the list and get the container node in this case. It should be used when list is known to be sorted as it will do binary search for results.

Example: imagine user gives a string, you check if it's in the list before duplicating its contents.

Note
O(log2(n)) average/worst case performance, for 1,000,000 elements it will do a maximum of 20 comparisons. This is much faster than the 1,000,000 comparisons made by eina_list_search_unsorted_list(), so depending on the number of searches and insertions, it may be worth to eina_list_sort() the list and do the searches later. As said in eina_list_search_sorted_near_list(), lists do not have O(1) access time, so walking to the correct node can be costly, consider worst case to be almost O(n) pointer dereference (list walk).
Warning
list must be a pointer to the first element of the list.
See also
eina_list_search_sorted()
eina_list_sort()
eina_list_sorted_merge()
eina_list_search_unsorted_list()
eina_list_search_sorted_near_list()
Examples:
eina_list_02.c.

References eina_list_search_sorted_near_list().

Referenced by eina_list_search_sorted().

void* eina_list_search_sorted ( const Eina_List list,
Eina_Compare_Cb  func,
const void *  data 
)

Returns node data if it is in the sorted list.

Parameters
listThe list to search for data, must be sorted.
funcA function pointer that can handle comparing the list data nodes.
datareference value to search.
Returns
the node value (node->data) if func(node->data, data) == 0, NULL if not found.

This can be used to check if some value is inside the list and get the existing instance in this case. It should be used when list is known to be sorted as it will do binary search for results.

Example: imagine user gives a string, you check if it's in the list before duplicating its contents.

Note
O(log2(n)) average/worst case performance, for 1,000,000 elements it will do a maximum of 20 comparisons. This is much faster than the 1,000,000 comparisons made by eina_list_search_unsorted(), so depending on the number of searches and insertions, it may be worth to eina_list_sort() the list and do the searches later. As said in eina_list_search_sorted_near_list(), lists do not have O(1) access time, so walking to the correct node can be costly, consider worst case to be almost O(n) pointer dereference (list walk).
Warning
list must be a pointer to the first element of the list.
See also
eina_list_search_sorted_list()
eina_list_sort()
eina_list_sorted_merge()
eina_list_search_unsorted_list()
Examples:
eina_list_02.c.

References eina_list_data_get(), and eina_list_search_sorted_list().

Eina_List* eina_list_search_unsorted_list ( const Eina_List list,
Eina_Compare_Cb  func,
const void *  data 
)

Returns node if data is in the unsorted list.

Parameters
listThe list to search for data, may be unsorted.
funcA function pointer that can handle comparing the list data nodes.
datareference value to search.
Returns
the node if func(node->data, data) == 0, NULL if not found.

This can be used to check if some value is inside the list and get the container node in this case.

Example: imagine user gives a string, you check if it's in the list before duplicating its contents.

Note
this is expensive and may walk the whole list, it's order-N, that is for 1,000,000 elements list it may walk and compare 1,000,000 nodes.
Warning
list must be a pointer to the first element of the list.
See also
eina_list_search_sorted_list()
eina_list_search_unsorted()
Examples:
eina_list_02.c.

References EINA_LIST_FOREACH.

Referenced by eina_list_search_unsorted().

void* eina_list_search_unsorted ( const Eina_List list,
Eina_Compare_Cb  func,
const void *  data 
)

Returns node data if it is in the unsorted list.

Parameters
listThe list to search for data, may be unsorted.
funcA function pointer that can handle comparing the list data nodes.
datareference value to search.
Returns
the node value (node->data) if func(node->data, data) == 0, NULL if not found.

This can be used to check if some value is inside the list and get the existing instance in this case.

Example: imagine user gives a string, you check if it's in the list before duplicating its contents.

Note
this is expensive and may walk the whole list, it's order-N, that is for 1,000,000 elements list it may walk and compare 1,000,000 nodes.
Warning
list must be a pointer to the first element of the list.
See also
eina_list_search_sorted()
eina_list_search_unsorted_list()
Examples:
eina_list_02.c.

References eina_list_data_get(), and eina_list_search_unsorted_list().

static Eina_List* eina_list_last ( const Eina_List list)
inlinestatic

Get the last list node in the list.

Parameters
listThe list to get the last list node from.
Returns
The last list node in the list.

This function returns the last list node in the list list. If list is NULL or empty, NULL is returned.

This is a order-1 operation (it takes the same short time regardless of the length of the list).

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_04.c.

Referenced by eina_list_iterator_reversed_new(), and eina_list_split_list().

static Eina_List* eina_list_next ( const Eina_List list)
inlinestatic

Get the next list node after the specified list node.

Parameters
listThe list node to get the next list node from
Returns
The next list node on success, NULL otherwise.

This function returns the next list node after the current one in list. It is equivalent to list->next. If list is NULL or if no next list node exists, it returns NULL.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_04.c.

Referenced by eina_list_split_list().

static Eina_List* eina_list_prev ( const Eina_List list)
inlinestatic

Get the previous list node before the specified list node.

Parameters
listThe list node to get the previous list node from.
Returns
The previous list node o success, NULL otherwise. if no previous list node exists

This function returns the previous list node before the current one in list. It is equivalent to list->prev. If list is NULL or if no previous list node exists, it returns NULL.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_04.c.
static void* eina_list_data_get ( const Eina_List list)
inlinestatic

Get the list node data member.

Parameters
listThe list node to get the data member of.
Returns
The data member from the list node.

This function returns the data member of the specified list node list. It is equivalent to list->data. If list is NULL, this function returns NULL.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_04.c.

Referenced by eina_list_search_sorted(), and eina_list_search_unsorted().

static void* eina_list_data_set ( Eina_List list,
const void *  data 
)
inlinestatic

Set the list node data member.

Parameters
listThe list node to get the data member of.
dataThe data member to the list node.
Returns
The previous data value.

This function set the data member data of the specified list node list. It returns the previous data of the node. If list is NULL, this function returns NULL.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_03.c.
static unsigned int eina_list_count ( const Eina_List list)
inlinestatic

Get the count of the number of items in a list.

Parameters
listThe list whose count to return.
Returns
The number of members in the list.

This function returns how many members list contains. If the list is NULL, 0 is returned.

NB: This is an order-1 operation and takes the same time regardless of the length of the list.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_list_03.c.
Eina_Iterator* eina_list_iterator_new ( const Eina_List list)

Returned a new iterator associated to a list.

Parameters
listThe list.
Returns
A new iterator.

This function returns a newly allocated iterator associated to list. If list is NULL or the count member of 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
list must be a pointer to the first element of the list.
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!
Examples:
eina_iterator_01.c, and eina_list_03.c.

References EINA_ERROR_OUT_OF_MEMORY, eina_error_set(), EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

Eina_Iterator* eina_list_iterator_reversed_new ( const Eina_List list)

Returned a new reversed iterator associated to a list.

Parameters
listThe list.
Returns
A new iterator.

This function returns a newly allocated iterator associated to list. If list is NULL or the count member of 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.

Unlike eina_list_iterator_new(), this will walk the list backwards.

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
list must be a pointer to the first element of the list.
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!

References EINA_ERROR_OUT_OF_MEMORY, eina_error_set(), eina_list_last(), EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

Eina_Accessor* eina_list_accessor_new ( const Eina_List list)

Returned a new accessor associated to a list.

Parameters
listThe list.
Returns
A new accessor.

This function returns a newly allocated accessor associated to list. If list is NULL or the count member of 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.

Warning
list must be a pointer to the first element of the list.
Examples:
eina_accessor_01.c.

References EINA_ERROR_OUT_OF_MEMORY, eina_error_set(), EINA_MAGIC_SET, FUNC_ACCESSOR_FREE, FUNC_ACCESSOR_GET_AT, and FUNC_ACCESSOR_GET_CONTAINER.