This group of functions manages 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 allow sequential access (that is, from one element to the next one). For random access, see Accessor Functions.

Getting an iterator to access elements of a given container is done through the functions of that particular container. There is no function to create a generic iterator as iterators absolutely depend on the container. This means you won't find a iterator creation function here, those can be found on the documentation of the container type you're using. Though created with container specific functions iterators are always deleted with the same function: eina_iterator_free().

To get data and iterate it, use eina_iterator_next(). To call a function on all the elements of a container, use eina_iterator_foreach().

Functions
void	eina_iterator_free (Eina_Iterator *iterator)
	Frees an iterator.
void *	eina_iterator_container_get (Eina_Iterator *iterator)
	Gets the container of an iterator.
Eina_Bool	eina_iterator_next (Eina_Iterator iterator, void *data)
	Returns the value of the current element and goes to the next one.
void	eina_iterator_foreach (Eina_Iterator iterator, Eina_Each_Cb callback, const void fdata)
	Iterates over the container and executes a callback on each element.
Eina_Bool	eina_iterator_lock (Eina_Iterator *iterator)
	Locks the container of the iterator.
Eina_Bool	eina_iterator_unlock (Eina_Iterator *iterator)
	Unlocks the container of the iterator.
Typedefs
typedef struct _Eina_Iterator	Eina_Iterator
	The structure type containing the abstract type for iterators.
typedef Eina_Bool(*	Eina_Iterator_Next_Callback )(Eina_Iterator it, void *data)
	The boolean type for a callback that returns the next element in a container.
typedef void (	Eina_Iterator_Get_Container_Callback )(Eina_Iterator *it)
	Called to return the container.
typedef void(*	Eina_Iterator_Free_Callback )(Eina_Iterator *it)
	Called to free the container.
typedef Eina_Bool(*	Eina_Iterator_Lock_Callback )(Eina_Iterator *it)
	Called to lock the container.
Defines
#define	FUNC_ITERATOR_NEXT(Function) ((Eina_Iterator_Next_Callback)Function)
	Definition of a helper macro to cast Function to a Eina_Iterator_Next_Callback.
#define	FUNC_ITERATOR_GET_CONTAINER(Function) ((Eina_Iterator_Get_Container_Callback)Function)
	Definition of a helper macro to cast Function to a Eina_Iterator_Get_Container_Callback.
#define	FUNC_ITERATOR_FREE(Function) ((Eina_Iterator_Free_Callback)Function)
	Definition of a helper macro to cast Function to a Eina_Iterator_Free_Callback.
#define	FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function)
	Definition of a helper macro to cast Function to a Eina_Iterator_Lock_Callback.
#define	EINA_ITERATOR_FOREACH(itr,data)
	Definition of the macro to iterate over all the elements easily.

Define Documentation

#define EINA_ITERATOR_FOREACH	(	itr,
		data
	)

Value:

while (eina_iterator_next((itr), \
                                                              (void **)(void *)&(data)))

Definition of the macro to iterate over all the elements easily.

Since :: 2.3.1

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

Remarks:: 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);

Remarks:: This example is not an optimal algorithm to release a list as it walks through the list twice, but it serves as an example. For an optimized version use EINA_LIST_FREE().; The order in which the elements are traversed depends on the underlying container and shouldn't be relied upon.; Unless explicitly stated in the function's returning iterators, do not modify the iterated object while you walk through it. In this example using lists, do not remove the list nodes or the program might crash. This is not a limitation of the iterators themselves, but a limitation in the iterators implementations to keep them as simple and fast as possible.

Parameters:

itr	The iterator to use
data	A pointer to store the data It must be a pointer to support getting its address since eina_iterator_next() requires a pointer.

Function Documentation

void* eina_iterator_container_get ( Eina_Iterator * iterator )

Gets the container of an iterator.

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

Since :: 2.3.1

Parameters:

[in] iterator The iterator

Returns:: The container that created the iterator

void eina_iterator_foreach	(	Eina_Iterator *	iterator,
		Eina_Each_Cb	callback,
		const void *	fdata
	)

Iterates over the container and executes a callback on each element.

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 immediately. Also, if cb returns EINA_FALSE, the iteration stops at that point. If cb returns EINA_TRUE the iteration continues.

Since :: 2.3.1

Parameters:

[in]	iterator	The iterator
[in]	callback	The callback called on each iteration
[in]	fdata	The data passed to the callback

void eina_iterator_free ( Eina_Iterator * iterator )

Frees an iterator.

This function frees iterator if it is not NULL.

Since :: 2.3.1

Parameters:

[in] iterator The iterator to free

Eina_Bool eina_iterator_lock ( Eina_Iterator * iterator )

Locks the container of the iterator.

Since :: 2.3.1

Remarks:: If the container of the iterator permits it, it is locked. When a container is locked by calling eina_iterator_foreach() on it, it returns immediately. If iterator is NULL or if a problem occurs, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container isn't lockable, it returns EINA_TRUE.; None of the existing eina data structures are lockable.

Parameters:

[in] iterator The iterator

Returns:: EINA_TRUE on success, otherwise EINA_FALSE

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

Returns the value of the current element and goes to the next one.

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

Since :: 2.3.1

Parameters:

[in]	iterator	The iterator
[in]	data	The data of the element

Returns:: EINA_TRUE on success, otherwise EINA_FALSE

Eina_Bool eina_iterator_unlock ( Eina_Iterator * iterator )

Unlocks the container of the iterator.

Since :: 2.3.1

Remarks:: If the container of the iterator permits it and is previously locked, it is unlocked. If iterator is NULL or if a problem occurs, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container is not lockable, it returns EINA_TRUE.; None of the existing eina data structures are lockable.

Parameters:

[in] iterator The iterator

Returns:: EINA_TRUE on success, otherwise EINA_FALSE

Functions

Typedefs

Defines

Define Documentation

Function Documentation