Iterator Functions

Data Structures | Macros | Typedefs | Functions
Iterator Functions
Eina » Data Types » Content Access

These functions manage iterators on containers. More...

## Data Structures
struct | _Eina_Iterator
| structure of an iterator More...

## Macros
#define | FUNC_ITERATOR_NEXT(Function) ((Eina_Iterator_Next_Callback)Function)
| Helper macro to cast `Function` to a Eina_Iterator_Next_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_FREE(Function) ((Eina_Iterator_Free_Callback)Function)
| Helper macro to cast `Function` to a Eina_Iterator_Free_Callback.
#define | FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function)
| Helper macro to cast `Function` to a Eina_Iterator_Lock_Callback.
#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. More...
#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. More...
#define | EINA_ITERATOR_FOREACH(itr, data)
| Definition for the macro to iterate over all elements easily. More...

## Typedefs
typedef struct _Eina_Iterator | Eina_Iterator
| Abstract type for iterators.
typedef Eina_Bool(* | Eina_Iterator_Next_Callback) (Eina_Iterator *it, void **data)
| Type for a callback that returns the next element in a container.
typedef void *(* | Eina_Iterator_Get_Container_Callback) (Eina_Iterator *it)
| Type for a callback that returns the container.
typedef void(* | Eina_Iterator_Free_Callback) (Eina_Iterator *it)
| Type for a callback that frees the container.
typedef Eina_Bool(* | Eina_Iterator_Lock_Callback) (Eina_Iterator *it)
| Type for a callback that lock the container.

## Functions
EINA_API void | eina_iterator_free (Eina_Iterator *iterator)
| Frees an iterator. More...
EINA_API void * | eina_iterator_container_get (Eina_Iterator *iterator)
| Returns the container of an iterator. More...
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. More...
EINA_API 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. More...
EINA_API Eina_Bool | eina_iterator_lock (Eina_Iterator *iterator)
| Locks the container of the iterator. More...
EINA_API Eina_Bool | eina_iterator_unlock (Eina_Iterator *iterator)
| Unlocks the container of the iterator. More...
EINA_API Eina_Iterator * | eina_carray_iterator_new (void **array)
| Creates an Eina_Iterator that iterates through a NUL-terminated C array. More...
EINA_API 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. More...
EINA_API 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. More...
EINA_API Eina_Iterator * | eina_multi_iterator_internal_new (Eina_Iterator *it,...)
| Creates an Eina_Iterator that iterates through a series of Eina_Iterator. More...
EINA_API 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. More...

## Detailed Description

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

## Macro Definition Documentation

## ◆ EINA_C_ARRAY_ITERATOR_NEW

#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
  1.22

## ◆ eina_multi_iterator_new

#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
  1.22

## ◆ EINA_ITERATOR_FOREACH

#define EINA_ITERATOR_FOREACH | ( |  | itr,
|  |  | data
| ) |  |

Value:
while (eina_iterator_next((itr), \
(void **)(void *)&(data)))
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

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);
eina_iterator_free
EINA_API void eina_iterator_free(Eina_Iterator *iterator)
Frees an iterator.
Definition: eina_iterator.c:98
EINA_ITERATOR_FOREACH
#define EINA_ITERATOR_FOREACH(itr, data)
Definition for the macro to iterate over all elements easily.
Definition: eina_iterator.h:448
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_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
_Eina_Iterator
structure of an iterator
Definition: eina_iterator.h:159
_Eina_List
Type for a generic double linked list.
Definition: eina_list.h:318

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_con_client_example.c, ecore_thread_example.c, eet-data-file_descriptor_01.c, eina_file_01.c, eina_list_03.c, and eina_tiler_01.c.

## Function Documentation

## ◆ eina_iterator_free()

EINA_API 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`;

References EINA_SAFETY_ON_NULL_RETURN, and _Eina_Iterator::free.

Referenced by ecore_file_dir_is_empty(), ecore_file_ls(), ecore_file_recursive_rm(), ecore_wl_window_surface_find(), edje_available_modules_get(), edje_edit_clean_save_as(), edje_edit_data_list_get(), edje_edit_data_source_generate(), edje_edit_font_path_get(), edje_edit_fonts_list_get(), edje_edit_group_add(), edje_edit_group_aliased_get(), edje_edit_group_aliases_get(), edje_edit_group_copy(), edje_edit_group_data_list_get(), edje_edit_image_replace(), edje_edit_image_set_del(), edje_edit_set_usage_list_get(), edje_edit_vector_usage_list_get(), edje_mmap_collection_list(), edje_mmap_group_exists(), edje_object_access_part_list_get(), eina_cow_gc(), eina_file_dir_list(), eina_file_flush(), eina_hash_foreach(), eina_promise_all_iterator(), eina_tiler_equal(), eina_tiler_intersection(), eina_tiler_subtract(), eina_tiler_union(), eio_monitoring_interval_set(), elm_color_class_editor_add(), and elm_color_class_util_edje_file_list().

## ◆ eina_iterator_container_get()

EINA_API 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`.

References EINA_SAFETY_ON_NULL_RETURN_VAL, and _Eina_Iterator::get_container.

## ◆ 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.

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.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and _Eina_Iterator::next.

Referenced by ecore_wl_window_surface_find(), eina_cow_gc(), eina_promise_all_iterator(), eina_tiler_equal(), and eina_tiler_intersection().

## ◆ eina_iterator_foreach()

EINA_API 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.

References eina_iterator_lock(), eina_iterator_unlock(), EINA_SAFETY_ON_NULL_RETURN, EINA_TRUE, _Eina_Iterator::get_container, and _Eina_Iterator::next.

Referenced by eina_hash_foreach().

## ◆ eina_iterator_lock()

EINA_API 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.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and _Eina_Iterator::lock.

Referenced by eina_iterator_foreach().

## ◆ eina_iterator_unlock()

EINA_API 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.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and _Eina_Iterator::unlock.

Referenced by eina_iterator_foreach().

## ◆ eina_carray_iterator_new()

EINA_API 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
  1.18

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

## ◆ eina_carray_length_iterator_new()

EINA_API 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
  1.22

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

## ◆ eina_iterator_filter_new()

EINA_API 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
  1.19

References EINA_MAGIC_SET, EINA_SAFETY_ON_NULL_RETURN_VAL, _Eina_Iterator::free, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

## ◆ eina_multi_iterator_internal_new()

EINA_API 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
  1.22

References eina_list_append(), EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

## ◆ eina_iterator_processed_new()

EINA_API 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] | iterator | 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] | fdata | 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
  1.24

References EINA_MAGIC_SET, EINA_SAFETY_ON_NULL_RETURN_VAL, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.