#include "eina_types.h"
#include "eina_magic.h"
+
+/**
+ * @addtogroup Eina_Iterator_Group Iterator Functions
+ *
+ * @brief 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
+ * @ref Eina_Accessor_Group.
+ *
+ * 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().
+ *
+ * @{
+ */
+
/**
* @addtogroup Eina_Content_Access_Group Content Access
*
*/
#define FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function)
+
+/**
+ * @brief Free an iterator.
+ *
+ * @param iterator The iterator to free.
+ *
+ * This function frees @p iterator if it is not @c NULL;
+ */
EAPI void eina_iterator_free(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Return the container of an iterator.
+ *
+ * @param iterator The iterator.
+ * @return The container which created the iterator.
+ *
+ * This function returns the container which created @p iterator. If
+ * @p iterator is @c NULL, this function returns @c NULL.
+ */
EAPI void *eina_iterator_container_get(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) EINA_PURE;
+
+/**
+ * @brief Return the value of the current element and go to the next one.
+ *
+ * @param iterator The iterator.
+ * @param data The data of the element.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
+ * This function returns the value of the current element pointed by
+ * @p iterator in @p data, then goes to the next element. If @p
+ * iterator is @c NULL or if a problem occurred, #EINA_FALSE is
+ * returned, otherwise #EINA_TRUE is returned.
+ */
EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator,
void **data) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @brief Iterate over the container and execute a callback on each element.
+ *
+ * @param iterator The iterator.
+ * @param cb The callback called on each iteration.
+ * @param fdata The data passed to the callback.
+ *
+ * This function iterates over the elements pointed by @p iterator,
+ * beginning from the current element. For Each element, the callback
+ * @p cb is called with the data @p fdata. If @p iterator is @c NULL,
+ * the function returns immediately. Also, if @p cb returns @c
+ * EINA_FALSE, the iteration stops at that point.
+ */
EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
Eina_Each_Cb callback,
const void *fdata) EINA_ARG_NONNULL(1, 2);
+
+/**
+ * @brief Lock the container of the iterator.
+ *
+ * @param iterator The iterator.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
+ * If the container of the @p iterator permit it, it will be locked.
+ * If @p iterator is @c 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.
+ */
EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
+
+/**
+ * @brief Unlock the container of the iterator.
+ *
+ * @param iterator The iterator.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ *
+ * If the container of the @p iterator permit it and was previously
+ * locked, it will be unlocked. If @p iterator is @c 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.
+ */
EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
/**
* @}
*/
+/**
+ * @}
+ */
+
#endif
* API *
*============================================================================*/
-/**
- * @addtogroup Eina_Iterator_Group Iterator Functions
- *
- * @brief 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
- * @ref Eina_Accessor_Group.
- *
- * 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().
- *
- * @{
- */
-
-/**
- * @brief Free an iterator.
- *
- * @param iterator The iterator to free.
- *
- * This function frees @p iterator if it is not @c NULL;
- */
EAPI void
eina_iterator_free(Eina_Iterator *iterator)
{
iterator->free(iterator);
}
-/**
- * @brief Return the container of an iterator.
- *
- * @param iterator The iterator.
- * @return The container which created the iterator.
- *
- * This function returns the container which created @p iterator. If
- * @p iterator is @c NULL, this function returns @c NULL.
- */
EAPI void *
eina_iterator_container_get(Eina_Iterator *iterator)
{
return iterator->get_container(iterator);
}
-/**
- * @brief Return the value of the current element and go to the next one.
- *
- * @param iterator The iterator.
- * @param data The data of the element.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- *
- * This function returns the value of the current element pointed by
- * @p iterator in @p data, then goes to the next element. If @p
- * iterator is @c NULL or if a problem occurred, #EINA_FALSE is
- * returned, otherwise #EINA_TRUE is returned.
- */
EAPI Eina_Bool
eina_iterator_next(Eina_Iterator *iterator, void **data)
{
return iterator->next(iterator, data);
}
-/**
- * @brief Iterate over the container and execute a callback on each element.
- *
- * @param iterator The iterator.
- * @param cb The callback called on each iteration.
- * @param fdata The data passed to the callback.
- *
- * This function iterates over the elements pointed by @p iterator,
- * beginning from the current element. For Each element, the callback
- * @p cb is called with the data @p fdata. If @p iterator is @c NULL,
- * the function returns immediately. Also, if @p cb returns @c
- * EINA_FALSE, the iteration stops at that point.
- */
EAPI void
eina_iterator_foreach(Eina_Iterator *iterator,
Eina_Each_Cb cb,
(void) eina_iterator_unlock(iterator);
}
-/**
- * @brief Lock the container of the iterator.
- *
- * @param iterator The iterator.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- *
- * If the container of the @p iterator permit it, it will be locked.
- * If @p iterator is @c 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.
- */
EAPI Eina_Bool
eina_iterator_lock(Eina_Iterator *iterator)
{
return EINA_TRUE;
}
-/**
- * @brief Unlock the container of the iterator.
- *
- * @param iterator The iterator.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- *
- * If the container of the @p iterator permit it and was previously
- * locked, it will be unlocked. If @p iterator is @c 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.
- */
EAPI Eina_Bool
eina_iterator_unlock(Eina_Iterator *iterator)
{
return iterator->unlock(iterator);
return EINA_TRUE;
}
-
-/**
- * @}
- */
projects / framework / uifw / eina.git / commitdiff