These functions manage iterators on containers.

These functions allow accessing 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 an iterator creation function here, those can be found with 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 the data and iterate, use eina_iterator_next(). To call a function on all the elements of a container, use eina_iterator_foreach().

Here an example

Functions
void	eina_iterator_free (Eina_Iterator *iterator)
	Frees an iterator.
void *	eina_iterator_container_get (Eina_Iterator *iterator)
	Returns the container of an iterator.
Eina_Bool	eina_iterator_next (Eina_Iterator iterator, void *data)
	Returns the value of the current element and go to the next one.
void	eina_iterator_foreach (Eina_Iterator iterator, Eina_Each_Cb callback, const void fdata)
	Iterates over the container and execute 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.
Eina_Iterator *	eina_carray_iterator_new (void **array)
	Creates an Eina_Iterator that iterates through a NUL-terminated C array.
Eina_Iterator *	eina_carray_length_iterator_new (void **array, unsigned int step, unsigned int length)
	Creates an Eina_Iterator that iterates through a C array of specified size.
Eina_Iterator *	eina_iterator_filter_new (Eina_Iterator original, Eina_Each_Cb filter, Eina_Free_Cb free_cb, void data)
	Creates a new iterator which which iterates through all elements with are accepted by the filter callback.
Eina_Iterator *	eina_multi_iterator_internal_new (Eina_Iterator *it,...)
	Creates an Eina_Iterator that iterates through a series of Eina_Iterator.
Eina_Iterator *	eina_iterator_processed_new (Eina_Iterator iterator, Eina_Process_Cb process, Eina_Free_Cb free_cb, void fdata)
	Calls the process method on each node of iterator, producing new "processed" nodes and returning a new iterator which contains them.
Typedefs
typedef struct _Eina_Iterator	Eina_Iterator
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)
typedef Eina_Bool(*	Eina_Iterator_Lock_Callback )(Eina_Iterator *it)
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	FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function)
#define	EINA_C_ARRAY_ITERATOR_NEW(Array) eina_carray_length_iterator_new((void**) Array, sizeof (Array[0]), EINA_C_ARRAY_LENGTH(Array))
	Creates an Eina_Iterator that iterates through a NUL-terminated C array.
#define	eina_multi_iterator_new(It,...) eina_multi_iterator_internal_new(It, ##__VA_ARGS__, NULL)
	Creates an Eina_Iterator that iterates through a series of Eina_Iterator.
#define	EINA_ITERATOR_FOREACH(itr,data)
	Definition for the macro to iterate over all elements easily.

Define Documentation

#define EINA_C_ARRAY_ITERATOR_NEW ( Array ) eina_carray_length_iterator_new((void**) Array, sizeof (Array[0]), EINA_C_ARRAY_LENGTH(Array))

Creates an Eina_Iterator that iterates through a NUL-terminated C array.

Parameters:

[in] array The NUL-terminated array

Returns:: The iterator that will walk over the array.

You can create it like this: int array[] = {1, 2, 3, 4};

Eina_Iterator* iterator = EINA_C_ARRAY_ITERATOR_NEW(array);

Since (EFL) :: 1.22

#define EINA_ITERATOR_FOREACH	(	itr,
		data
	)

Value:

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

Definition for the macro to iterate over all elements easily.

Parameters:

[in,out]	itr	The iterator to use.
[out]	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:: The order in which the elements will be traversed depends on the underlying container and shouldn't be relied upon.; 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 limitation of iterators themselves, rather in the iterators implementations to keep them as simple and fast as possible.

Examples:: ecore_thread_example.c, eina_file_01.c, eina_list_03.c, and eina_tiler_01.c.

#define eina_multi_iterator_new	(	It,
		...
	)	eina_multi_iterator_internal_new(It, ##__VA_ARGS__, NULL)

Creates an Eina_Iterator that iterates through a series of Eina_Iterator.

Parameters:

[in] it The first Eina_Iterator to iterate over

Returns:: The iterator that will walk all the other iterator

Eina_Iterator* iterator = eina_multi_iterator_new(it1, it2, it3);

Note:: The returned array will destroy iterator given to it once they are not necessary anymore. Taking ownership of those iterator.

Since (EFL) :: 1.22

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

Helper macro to cast Function to a Eina_Iterator_Free_Callback.

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

Helper macro to cast Function to a Eina_Iterator_Get_Container_Callback.

#define FUNC_ITERATOR_LOCK ( Function ) ((Eina_Iterator_Lock_Callback)Function)

Helper macro to cast Function to a Eina_Iterator_Lock_Callback.

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

Helper macro to cast Function to a Eina_Iterator_Next_Callback.

Typedef Documentation

Eina_Iterator

Abstract type for iterators.

Eina_Iterator_Free_Callback

Type for a callback that frees the container.

Eina_Iterator_Get_Container_Callback

Type for a callback that returns the container.

Eina_Iterator_Lock_Callback

Type for a callback that lock the container.

Eina_Iterator_Next_Callback

Type for a callback that returns the next element in a container.

Function Documentation

Eina_Iterator* eina_carray_iterator_new ( void ** array )

Creates an Eina_Iterator that iterates through a NUL-terminated C array.

Parameters:

[in] array The NUL-terminated array

Returns:: The iterator that will walk over the array.

You can create it like this: int array[] = {1, 2, 3, 4}; int* array2[] = {&array[0], &array[1], &array[2], &array[3], NULL};

Eina_Iterator* iterator = eina_carray_iterator_new((void**)array2);

Since (EFL) :: 1.18

Eina_Iterator* eina_carray_length_iterator_new	(	void **	array,
		unsigned int	step,
		unsigned int	length
	)

Creates an Eina_Iterator that iterates through a C array of specified size.

Parameters:

[in] array The array

Returns:: The iterator that will walk over the array.

You can create it like this: int array[] = {1, 2, 3, 4};

Eina_Iterator* iterator = eina_carray_length_iterator_new((void**)array, sizeof (array[0]), (EINA_C_ARRAY_LENGTH(array));

Since (EFL) :: 1.22

void* eina_iterator_container_get ( Eina_Iterator * iterator )

Returns the container of an iterator.

Parameters:

[in] 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.

Since :: 2.3

Examples:: eina_iterator_01.c.

Eina_Iterator* eina_iterator_filter_new	(	Eina_Iterator *	original,
		Eina_Each_Cb	filter,
		Eina_Free_Cb	free_cb,
		void *	data
	)

Creates a new iterator which which iterates through all elements with are accepted by the filter callback.

Parameters:

[in]	original	the iterator the use as original set
[in]	filter	if the callback returns true the element from the original set is taken into the the new set.
[in]	free_cb	when the iterator is gone this callback will be called with data as argument
[in]	data	the data which is passed to the filter callback

The iterator is filtered while it is being iterated. The original iterator you pass in here is is then owned and will be freed once the the new iterator is freed.

Since (EFL) :: 1.19

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

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

Parameters:

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

This function iterates over the elements pointed by iterator, beginning with 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

Examples:: eina_iterator_01.c.

void eina_iterator_free ( Eina_Iterator * iterator )

Frees an iterator.

Parameters:

[in,out] iterator The iterator to free.

This function frees iterator if it is not NULL;

Since :: 2.3

Examples:: ecore_thread_example.c, eina_file_01.c, eina_hash_01.c, eina_hash_03.c, eina_hash_04.c, eina_hash_05.c, eina_hash_06.c, eina_hash_07.c, eina_iterator_01.c, eina_list_03.c, and eina_tiler_01.c.

Eina_Bool eina_iterator_lock ( Eina_Iterator * iterator )

Locks the container of the iterator.

Parameters:

[in,out] iterator The iterator.

Returns:: EINA_TRUE on success, EINA_FALSE otherwise.

If the container of the iterator permits it, it will be locked. When a container is locked calling eina_iterator_foreach() on it will return immediately. If iterator is NULL or if a problem occurred, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container isn't lockable, it will return EINA_TRUE.

Warning:: None of the existing eina data structures are lockable.

Since :: 2.3

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

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

Parameters:

[in,out]	iterator	The iterator.
[out]	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 occurred, EINA_FALSE is returned, otherwise EINA_TRUE is returned.

Since :: 2.3

Examples:: eina_hash_01.c, eina_hash_03.c, eina_hash_04.c, eina_hash_05.c, eina_hash_06.c, eina_hash_07.c, and eina_iterator_01.c.

Eina_Iterator* eina_iterator_processed_new	(	Eina_Iterator *	iterator,
		Eina_Process_Cb	process,
		Eina_Free_Cb	free_cb,
		void *	fdata
	)

Calls the process method on each node of iterator, producing new "processed" nodes and returning a new iterator which contains them.

Parameters:

[in]	original	Iterator containing the nodes to process.
[in]	process	Method to call on each node.
[in]	free_cb	Method called when all nodes have been processed. It receives "data" as a parameter.
[in]	data	Additional data passed to the process method.

Processes every node in the input iterator and returns a new iterator containing the processed nodes. This is akin to a Map function: https://en.wikipedia.org/wiki/Map_(higher-order_function)

Since (EFL) :: 1.24

Eina_Bool eina_iterator_unlock ( Eina_Iterator * iterator )

Unlocks the container of the iterator.

Parameters:

[in,out] iterator The iterator.

Returns:: EINA_TRUE on success, EINA_FALSE otherwise.

If the container of the iterator permits it and was previously locked, it will be unlocked. If iterator is NULL or if a problem occurred, EINA_FALSE is returned, otherwise EINA_TRUE is returned. If the container is not lockable, it will return EINA_TRUE.

Warning:: None of the existing eina data structures are lockable.

Since :: 2.3

Eina_Iterator* eina_multi_iterator_internal_new	(	Eina_Iterator *	it,
			...
	)

Creates an Eina_Iterator that iterates through a series of Eina_Iterator.

Parameters:

[in] it The first Eina_Iterator to iterate over

Returns:: The iterator that will walk all the other iterator

Eina_Iterator* iterator = eina_multi_iterator_new(it1, it2, it3, NULL);

Note:: The returned array will destroy iterator given to it once they are not necessary anymore. Taking ownership of those iterator.

Since (EFL) :: 1.22

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Function Documentation