Adding elements to Eina_List

Creating an Eina_List and adding elements to it is very easy and can be understood from an example: First thing is always to include Eina.h, for this example we also include stdio.h so we can use printf.

#include <stdio.h>
#include <Eina.h>
Eina.h
Eina Utility library.

Just some boilerplate code, declaring some variables and initializing eina.

int
main(int argc, char **argv)
{
(void)argc;
(void)argv;
Eina_List *list = NULL;
Eina_List *l;
void *list_data;
eina_init();
Eina_List
struct _Eina_List Eina_List
Type for a generic double linked list.
Definition eina_list.h:304
eina_init
EINA_API int eina_init(void)
Initializes the Eina library.
Definition eina_main.c:291

Here we add a sequence of elements to our list. By using append we add elements to the end of the list, so the list will look like this:

list = eina_list_append(list, "tigh");
list = eina_list_append(list, "adar");
list = eina_list_append(list, "baltar");
list = eina_list_append(list, "roslin");
eina_list_append
EINA_API Eina_List * eina_list_append(Eina_List *list, const void *data)
Appends the given data to the given linked list.
Definition eina_list.c:584

There are a couple of interesting things happening here, first is that we are passing a NULL pointer to the first eina_list_append() call, when this is done a list is created. The other very important detail to notice is that the return value is attributed to the list variable, this needs to be done every time we use a a function that alters the contents of the list.

Now that we have a list with some elements in it we can look at its contents.

EINA_LIST_FOREACH(list, l, list_data)
printf("%s\n", (char*)list_data);
EINA_LIST_FOREACH
#define EINA_LIST_FOREACH(list, l, _data)
Definition for the macro to iterate over a list.
Definition eina_list.h:1415

There are many ways of accessing elements in the list, including by its index:

printf("\n");
l = eina_list_nth_list(list, 1);
eina_list_nth_list
EINA_API Eina_List * eina_list_nth_list(const Eina_List *list, unsigned int n)
Gets the nth member's list node in a list.
Definition eina_list.c:1006

Note
  It should be noted that the index starts at 0.

eina_list_append() is not the only way to add elements to a a list. A common requirement is to add an element in a specific position this can be accomplished using eina_list_append_relative() and eina_list_append_relative_list():

list = eina_list_append_relative_list(list, "cain", l);
list = eina_list_append_relative(list, "zarek", "cain");
eina_list_append_relative
EINA_API Eina_List * eina_list_append_relative(Eina_List *list, const void *data, const void *relative)
Inserts the given data into the given linked list after the specified data.
Definition eina_list.c:649
eina_list_append_relative_list
EINA_API Eina_List * eina_list_append_relative_list(Eina_List *list, const void *data, Eina_List *relative)
Appends a list node to a linked list after the specified member.
Definition eina_list.c:670

First "cain" is added after the second element (remember that indexes are 0 based) and then we add "zarek" after "cain".

Eina_List also has prepend analogs to append functions we have used so far:

list = eina_list_prepend(list, "adama");
list = eina_list_prepend_relative(list, "gaeta", "cain");
list = eina_list_prepend_relative_list(list, "lampkin", l);
eina_list_prepend
EINA_API Eina_List * eina_list_prepend(Eina_List *list, const void *data)
Prepends the given data to the given linked list.
Definition eina_list.c:618
eina_list_prepend_relative
EINA_API Eina_List * eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative)
Prepends a data pointer to a linked list before the specified member.
Definition eina_list.c:704
eina_list_prepend_relative_list
EINA_API Eina_List * eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *relative)
Prepends a list node to a linked list before the specified member.
Definition eina_list.c:724

With this additions our list now looks like this:

Once done using the list it needs to be freed, and since we are done with eina that also need to be shutdown:

EINA_LIST_FOREACH(list, l, list_data)
printf("%s\n", (char*)list_data);
eina_list_free(list);
eina_shutdown();
return 0;
}
eina_list_free
EINA_API Eina_List * eina_list_free(Eina_List *list)
Frees an entire list and all the nodes, ignoring the data contained.
Definition eina_list.c:823
eina_shutdown
EINA_API int eina_shutdown(void)
Shuts down the Eina library.
Definition eina_main.c:379

The full source code can be found on the examples folder on the eina_list_01.c file.