Linux Certif

Toute la documentation sur la certification Linux LPI

Eina_Iterator_Group

NAME

Iterator Functions -

These functions manage iterators on containers.

Data Structures

struct _Eina_Iterator

Defines

#define FUNC_ITERATOR_NEXT(Function) ((Eina_Iterator_Next_Callback)Function)

#define FUNC_ITERATOR_GET_CONTAINER(Function) ((Eina_Iterator_Get_Container_Callback)Function)

#define FUNC_ITERATOR_FREE(Function) ((Eina_Iterator_Free_Callback)Function)

#define EINA_ITERATOR_FOREACH(itr, data) while (eina_iterator_next((itr), (void **)&(data)))
Macro to iterate over all elements easily.

Typedefs

typedef struct _Eina_Iterator Eina_Iterator
Type for iterators.
typedef Eina_Bool(* Eina_Iterator_Next_Callback )(Eina_Iterator *it, void **data)

typedef void *(* Eina_Iterator_Get_Container_Callback )(Eina_Iterator *it)

typedef void(* Eina_Iterator_Free_Callback )(Eina_Iterator *it)

Functions

EAPI void eina_iterator_free (Eina_Iterator *iterator)
Free an iterator.
EAPI void * eina_iterator_container_get (Eina_Iterator *iterator)
Return the container of an iterator.
EAPI Eina_Bool eina_iterator_next (Eina_Iterator *iterator, void **data)
Return the value of the current element and go to the next one.
EAPI void eina_iterator_foreach (Eina_Iterator *iterator, Eina_Each cb, const void *fdata)
Iterate over the container and execute a callback on each element.

Variables

EAPI Eina_Bool EINA_WARN_UNUSED_RESULT

Detailed Description

These functions manage iterators on containers.

These functions allow to access elements of a container in a generic way, without knowing which container is used (a bit like iterators in the C++ STL). Iterators only allows sequential access (that is, from an element to the next one). For random access, see Accessor Functions.

An iterator is created from container data types, so no creation function is available here. An iterator is deleted with eina_iterator_free(). To get the data and iterate, use eina_iterator_next(). To call a function on all the elements of a container, use eina_iterator_foreach().

Define Documentation

#define EINA_ITERATOR_FOREACH(itr, data) while (eina_iterator_next((itr), (void **)&(data)))

Macro to iterate over all elements easily. Parameters:

itr The iterator to use.
data Where to store * data, must be a pointer support getting its address since * eina_iterator_next() requires a pointer to pointer!

This macro is a convenient way to use iterators, very similar to EINA_LIST_FOREACH().

This macro can be used for freeing the data of a list, like in the following example. It has the same goal as the one documented in EINA_LIST_FOREACH(), but using iterators:

  Eina_List     *list;
  Eina_Iterator *itr;
  char          *data;
 
  // list is already filled,
  // its elements are just duplicated strings
 
  itr = eina_list_iterator_new(list);
  EINA_ITERATOR_FOREACH(itr, data)
    free(data);
  eina_iterator_free(itr);
  eina_list_free(list);
 

Note:

this example is not optimal algorithm to release a list since it will walk the list twice, but it serves as an example. For optimized version use EINA_LIST_FREE()

Warning:

unless explicitly stated in functions returning iterators, do not modify the iterated object while you walk it, in this example using lists, do not remove list nodes or you might crash! This is not a limitiation of iterators themselves, rather in the iterators implementations to keep them as simple and fast as possible.

Function Documentation

EAPI void eina_iterator_free (Eina_Iterator * iterator)

Free an iterator. Parameters:

iterator The iterator to free.

This function frees iterator if it is not NULL;

EAPI void * eina_iterator_container_get (Eina_Iterator * iterator)

Return the container of an iterator. Parameters:

iterator The iterator.

Returns:

The container which created the iterator.

This function returns the container which created iterator. If iterator is NULL, this function returns NULL.

EAPI Eina_Bool eina_iterator_next (Eina_Iterator * iterator, void ** data)

Return the value of the current element and go to the next one. Parameters:

iterator The iterator.
data The data of the element.

Returns:

EINA_TRUE on success, EINA_FALSE otherwise.

This function returns the value of the current element pointed by iterator in data, then goes to the next element. If iterator is NULL or if a problem occured, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

EAPI void eina_iterator_foreach (Eina_Iterator * iterator, Eina_Each cb, const void * fdata)

Iterate over the container and execute a callback on each element. Parameters:

iterator The iterator.
cb The callback called on each iteration.
fdata The data passed to the callback.

This function iterates over the elements pointed by iterator, beginning from the current element. For Each element, the callback cb is called with the data fdata.If iterator is NULL, the function returns immediatly.

Author

Generated automatically by Doxygen for Eina from the source code.