Eina_Iterator usage

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

Eina_Iterator usage

As always when using eina we need to include it:

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

Here we a declare an unimpressive function that prints some data:

static Eina_Bool
print_one(const void *container EINA_UNUSED, void *data, void *fdata EINA_UNUSED)
{
printf("%s\n", (char*)data);
return EINA_TRUE;
}
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition: eina_types.h:527
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition: eina_types.h:339

Note
  Returning EINA_TRUE is important so we don't stop iterating over the container.

And here's a more interesting function, it uses an iterator to print the contents of a container. What's interesting about it is that it doesn't care the type of container, it works for anything that can provide an iterator:

static void
print_eina_container(Eina_Iterator *it)
{
eina_iterator_foreach(it, print_one, NULL);
printf("\n");
}
eina_iterator_foreach
EINA_API void eina_iterator_foreach(Eina_Iterator *iterator, Eina_Each_Cb cb, const void *fdata)
Iterates over the container and execute a callback on each element.
Definition: eina_iterator.c:130
_Eina_Iterator
structure of an iterator
Definition: eina_iterator.h:159

And on to our main function were we declare some variables and initialize eina, nothing too special:

int
main(int argc EINA_UNUSED, char **argv EINA_UNUSED)
{
const char *strings[] = {
"unintersting string", "husker", "starbuck", "husker"
};
const char *more_strings[] = {
"very unintersting string",
"what do your hear?",
"nothing but the rain",
"then grab your gun and bring the cat in"
};
Eina_Array *array;
Eina_List *list = NULL;
Eina_Iterator *it;
unsigned short int i;
char *uninteresting;
eina_init();
eina_init
EINA_API int eina_init(void)
Initializes the Eina library.
Definition: eina_main.c:291
_Eina_Array
Type for an array of data.
Definition: eina_array.h:229
_Eina_List
Type for a generic double linked list.
Definition: eina_list.h:318

Next we populate both an array and a list with our strings, for more details see Adding elements to Eina_List and Basic array usage :

array = eina_array_new(4);
for (i = 0; i < 4; i++)
{
eina_array_push(array, strings[i]);
list = eina_list_append(list, more_strings[i]);
}
eina_array_push
static Eina_Bool eina_array_push(Eina_Array *array, const void *data)
Appends a data item to an array.
eina_array_new
EINA_API Eina_Array * eina_array_new(unsigned int step)
Creates a new array.
Definition: eina_array.c:276
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

And now we create an array and because the first element of the container doesn't interest us we skip it:

it = eina_array_iterator_new(array);
if (!eina_iterator_next(it, (void **)&uninteresting))
eina_array_iterator_new
EINA_API Eina_Iterator * eina_array_iterator_new(const Eina_Array *array)
Gets a new iterator associated with an array.
Definition: eina_array.c:394
eina_iterator_next
EINA_API Eina_Bool eina_iterator_next(Eina_Iterator *iterator, void **data)
Returns the value of the current element and go to the next one.
Definition: eina_iterator.c:118

Having our iterator now pointing to interesting data we go ahead and print:

return -1;
print_eina_container(it);

As always once data with a structure we free it, but just because we can we do it by asking the iterator for it's container, and then of course free the iterator itself:

eina_array_free(eina_iterator_container_get(it));
eina_iterator_free(it);
eina_array_free
EINA_API void eina_array_free(Eina_Array *array)
Frees an array.
Definition: eina_array.c:295
eina_iterator_free
EINA_API void eina_iterator_free(Eina_Iterator *iterator)
Frees an iterator.
Definition: eina_iterator.c:98
eina_iterator_container_get
EINA_API void * eina_iterator_container_get(Eina_Iterator *iterator)
Returns the container of an iterator.
Definition: eina_iterator.c:109

But so far you're not impressed in Basic array usage an array is also printed, so now we go to the cool stuff and use an iterator to do same stuff to a list:

it = eina_list_iterator_new(list);
if (!eina_iterator_next(it, (void **)&uninteresting))
return -1;
print_eina_container(it);
eina_iterator_free(it);
eina_list_iterator_new
EINA_API Eina_Iterator * eina_list_iterator_new(const Eina_List *list)
Returns a new iterator associated with a list.
Definition: eina_list.c:1574

Note
  The only significant difference to the block above is in the function used to create the iterator.

And now we free the list and shut eina down:

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