2008-08-11 09:30:16 -07:00
|
|
|
/* EINA - EFL data type library
|
|
|
|
* Copyright (C) 2008 Cedric Bail
|
|
|
|
*
|
|
|
|
* This library is free software; you can redistribute it and/or
|
|
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
|
|
* License as published by the Free Software Foundation; either
|
|
|
|
* version 2.1 of the License, or (at your option) any later version.
|
|
|
|
*
|
|
|
|
* This library is distributed in the hope that it will be useful,
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
|
* Lesser General Public License for more details.
|
|
|
|
*
|
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
|
|
* License along with this library;
|
|
|
|
* if not, see <http://www.gnu.org/licenses/>.
|
|
|
|
*/
|
|
|
|
|
|
|
|
#ifndef EINA_ITERATOR_H__
|
|
|
|
#define EINA_ITERATOR_H__
|
|
|
|
|
2008-12-08 02:51:51 -08:00
|
|
|
#include "eina_config.h"
|
|
|
|
|
2008-08-11 09:30:16 -07:00
|
|
|
#include "eina_types.h"
|
Make it possible to create iterators outside Eina.
Many places in EFL we just create walk something, create a list with
walked data, return, then the user walks it again and then deletes
(which will walk again). For such cases it's way better to define
iterators or accessors.
I'm not moving any EFL code to it now, but if people are interested,
things like evas_render_method_list(), evas_font_available_list(),
evas_objects_at_xy_get(), evas_objects_in_rectangle_get(),
evas_object_smart_members_get() are good candidates. If the subject is
already using Eina list, then you can just use
eina_list_iterator_new() and return it, otherwise you can define your
own iterator, which is very easy.
SVN revision: 37956
2008-12-05 19:41:03 -08:00
|
|
|
#include "eina_magic.h"
|
2008-08-11 09:30:16 -07:00
|
|
|
|
2011-06-10 06:42:19 -07:00
|
|
|
/**
|
2012-01-17 20:32:37 -08:00
|
|
|
* @page eina_iterator_example_page Eina_Iterator usage
|
2011-06-10 06:42:19 -07:00
|
|
|
* @dontinclude eina_iterator_01.c
|
|
|
|
*
|
|
|
|
* As always when using eina we need to include it:
|
|
|
|
* @skip #include
|
|
|
|
* @until Eina.h
|
|
|
|
*
|
|
|
|
* Here we a declare an unimpressive @ref Eina_Each_Cb "function" that prints
|
|
|
|
* some data:
|
|
|
|
* @until }
|
|
|
|
* @note Returning EINA_TRUE is important so we don't stop iterating over the
|
|
|
|
* container.
|
|
|
|
*
|
2017-10-31 04:31:24 -07:00
|
|
|
* And here's a more interesting function, it uses an iterator to print the
|
2011-06-10 06:42:19 -07:00
|
|
|
* contents of a container. What's interesting about it is that it doesn't care
|
|
|
|
* the type of container, it works for anything that can provide an iterator:
|
|
|
|
* @until }
|
|
|
|
*
|
|
|
|
* And on to our main function were we declare some variables and initialize
|
|
|
|
* eina, nothing too special:
|
|
|
|
* @until eina_init
|
|
|
|
*
|
|
|
|
* Next we populate both an array and a list with our strings, for more details
|
2012-01-17 20:32:37 -08:00
|
|
|
* see @ref eina_list_01_example_page and @ref eina_array_01_example_page :
|
2011-06-10 06:42:19 -07:00
|
|
|
* @until }
|
|
|
|
*
|
|
|
|
* And now we create an array and because the first element of the container
|
|
|
|
* doesn't interest us we skip it:
|
|
|
|
* @until iterator_next
|
|
|
|
*
|
|
|
|
* Having our iterator now pointing to interesting data we go ahead and print:
|
|
|
|
* @until print_eina_container
|
|
|
|
*
|
|
|
|
* As always once data with a structure we free it, but just because we can we
|
|
|
|
* do it by asking the iterator for it's container, and then of course free the
|
|
|
|
* iterator itself:
|
|
|
|
* @until eina_iterator_free
|
|
|
|
*
|
2012-01-17 20:32:37 -08:00
|
|
|
* But so far you're not impressed in @ref eina_array_01_example_page an array is
|
2011-06-10 06:42:19 -07:00
|
|
|
* also printed, so now we go to the cool stuff and use an iterator to do same
|
|
|
|
* stuff to a list:
|
|
|
|
* @until eina_iterator_free
|
2017-02-19 22:18:21 -08:00
|
|
|
* @note The only significant difference to the block above is in the
|
2011-06-10 06:42:19 -07:00
|
|
|
* function used to create the iterator.
|
|
|
|
*
|
|
|
|
* And now we free the list and shut eina down:
|
|
|
|
* @until }
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @page eina_iterator_01_c Eina_Iterator usage
|
|
|
|
* @page eina_iterator_01_c Eina_Iterator usage
|
|
|
|
*
|
|
|
|
* @include eina_iterator_01.c
|
|
|
|
* @example eina_iterator_01.c
|
|
|
|
*/
|
2011-04-07 05:23:22 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @addtogroup Eina_Iterator_Group Iterator Functions
|
|
|
|
*
|
|
|
|
* @brief These functions manage iterators on containers.
|
|
|
|
*
|
2017-10-31 04:31:24 -07:00
|
|
|
* These functions allow accessing elements of a container in a
|
2011-04-07 05:23:22 -07:00
|
|
|
* generic way, without knowing which container is used (a bit like
|
2017-10-31 04:31:24 -07:00
|
|
|
* iterators in the C++ STL). Iterators only allow sequential access
|
|
|
|
* (that is, from one element to the next one). For random access, see
|
2011-04-07 05:23:22 -07:00
|
|
|
* @ref Eina_Accessor_Group.
|
|
|
|
*
|
2012-07-17 10:51:10 -07:00
|
|
|
* 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
|
2017-10-31 04:31:24 -07:00
|
|
|
* means you won't find an iterator creation function here, those can be found with
|
2012-07-17 10:51:10 -07:00
|
|
|
* 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().
|
2015-04-09 22:13:11 -07:00
|
|
|
*
|
2012-01-17 20:32:37 -08:00
|
|
|
* Here an @ref eina_iterator_example_page "example"
|
2011-04-07 05:23:22 -07:00
|
|
|
*/
|
|
|
|
|
2009-06-22 13:03:58 -07:00
|
|
|
/**
|
|
|
|
* @addtogroup Eina_Content_Access_Group Content Access
|
|
|
|
*
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
2008-09-06 22:44:00 -07:00
|
|
|
/**
|
|
|
|
* @defgroup Eina_Iterator_Group Iterator Functions
|
|
|
|
*
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Iterator
|
2010-11-06 05:34:55 -07:00
|
|
|
* Abstract type for iterators.
|
2008-09-06 22:44:00 -07:00
|
|
|
*/
|
2008-08-11 09:30:16 -07:00
|
|
|
typedef struct _Eina_Iterator Eina_Iterator;
|
|
|
|
|
2010-11-06 05:34:55 -07:00
|
|
|
/**
|
|
|
|
* @typedef Eina_Iterator_Next_Callback
|
|
|
|
* Type for a callback that returns the next element in a container.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
typedef Eina_Bool (*Eina_Iterator_Next_Callback)(Eina_Iterator *it, void **data);
|
2010-11-06 05:34:55 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Iterator_Get_Container_Callback
|
|
|
|
* Type for a callback that returns the container.
|
|
|
|
*/
|
|
|
|
typedef void *(*Eina_Iterator_Get_Container_Callback)(Eina_Iterator *it);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Iterator_Free_Callback
|
|
|
|
* Type for a callback that frees the container.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
typedef void (*Eina_Iterator_Free_Callback)(Eina_Iterator *it);
|
2010-11-06 05:34:55 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Iterator_Lock_Callback
|
|
|
|
* Type for a callback that lock the container.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
typedef Eina_Bool (*Eina_Iterator_Lock_Callback)(Eina_Iterator *it);
|
Make it possible to create iterators outside Eina.
Many places in EFL we just create walk something, create a list with
walked data, return, then the user walks it again and then deletes
(which will walk again). For such cases it's way better to define
iterators or accessors.
I'm not moving any EFL code to it now, but if people are interested,
things like evas_render_method_list(), evas_font_available_list(),
evas_objects_at_xy_get(), evas_objects_in_rectangle_get(),
evas_object_smart_members_get() are good candidates. If the subject is
already using Eina list, then you can just use
eina_list_iterator_new() and return it, otherwise you can define your
own iterator, which is very easy.
SVN revision: 37956
2008-12-05 19:41:03 -08:00
|
|
|
|
2010-11-06 05:34:55 -07:00
|
|
|
/**
|
|
|
|
* @struct _Eina_Iterator
|
|
|
|
* structure of an iterator
|
2012-07-17 10:51:10 -07:00
|
|
|
*
|
|
|
|
* If creating an iterator remember to set the type using @ref EINA_MAGIC_SET.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
Make it possible to create iterators outside Eina.
Many places in EFL we just create walk something, create a list with
walked data, return, then the user walks it again and then deletes
(which will walk again). For such cases it's way better to define
iterators or accessors.
I'm not moving any EFL code to it now, but if people are interested,
things like evas_render_method_list(), evas_font_available_list(),
evas_objects_at_xy_get(), evas_objects_in_rectangle_get(),
evas_object_smart_members_get() are good candidates. If the subject is
already using Eina list, then you can just use
eina_list_iterator_new() and return it, otherwise you can define your
own iterator, which is very easy.
SVN revision: 37956
2008-12-05 19:41:03 -08:00
|
|
|
struct _Eina_Iterator
|
|
|
|
{
|
2010-08-19 05:02:28 -07:00
|
|
|
#define EINA_ITERATOR_VERSION 1
|
2010-11-06 05:34:55 -07:00
|
|
|
int version; /**< Version of the Iterator API. */
|
2010-08-19 05:02:28 -07:00
|
|
|
|
2010-11-06 05:34:55 -07:00
|
|
|
Eina_Iterator_Next_Callback next EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /**< Callback called when a next element is requested. */
|
|
|
|
Eina_Iterator_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested. */
|
|
|
|
Eina_Iterator_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed. */
|
2008-12-05 22:53:14 -08:00
|
|
|
|
2010-11-06 05:34:55 -07:00
|
|
|
Eina_Iterator_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */
|
|
|
|
Eina_Iterator_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked. */
|
2010-08-11 07:32:30 -07:00
|
|
|
|
2008-12-05 22:53:14 -08:00
|
|
|
#define EINA_MAGIC_ITERATOR 0x98761233
|
* eina/src/include/eina_array.h,
* eina/src/include/eina_f16p16.h,
* eina/src/include/eina_accessor.h,
* eina/src/include/eina_list.h,
* eina/src/include/eina_iterator.h,
* eina/src/lib/eina_rectangle.c,
* eina/src/lib/eina_list.c,
* eina/src/lib/eina_array.c,
* eina/src/lib/eina_hash.c,
* eina/src/lib/eina_module.c,
* eina/src/lib/eina_stringshare.c,
* eina/src/lib/eina_benchmark.c: Fix for windows compilation.
SVN revision: 38663
2009-01-20 07:56:48 -08:00
|
|
|
EINA_MAGIC
|
Make it possible to create iterators outside Eina.
Many places in EFL we just create walk something, create a list with
walked data, return, then the user walks it again and then deletes
(which will walk again). For such cases it's way better to define
iterators or accessors.
I'm not moving any EFL code to it now, but if people are interested,
things like evas_render_method_list(), evas_font_available_list(),
evas_objects_at_xy_get(), evas_objects_in_rectangle_get(),
evas_object_smart_members_get() are good candidates. If the subject is
already using Eina list, then you can just use
eina_list_iterator_new() and return it, otherwise you can define your
own iterator, which is very easy.
SVN revision: 37956
2008-12-05 19:41:03 -08:00
|
|
|
};
|
|
|
|
|
2010-11-06 05:34:55 -07:00
|
|
|
/**
|
|
|
|
* @def FUNC_ITERATOR_NEXT(Function)
|
|
|
|
* Helper macro to cast @p Function to a Eina_Iterator_Next_Callback.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
#define FUNC_ITERATOR_NEXT(Function) ((Eina_Iterator_Next_Callback)Function)
|
2010-11-06 05:34:55 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @def FUNC_ITERATOR_GET_CONTAINER(Function)
|
|
|
|
* Helper macro to cast @p Function to a Eina_Iterator_Get_Container_Callback.
|
|
|
|
*/
|
|
|
|
#define FUNC_ITERATOR_GET_CONTAINER(Function) ((Eina_Iterator_Get_Container_Callback)Function)
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @def FUNC_ITERATOR_FREE(Function)
|
|
|
|
* Helper macro to cast @p Function to a Eina_Iterator_Free_Callback.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
#define FUNC_ITERATOR_FREE(Function) ((Eina_Iterator_Free_Callback)Function)
|
2010-11-06 05:34:55 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @def FUNC_ITERATOR_LOCK(Function)
|
|
|
|
* Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
#define FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function)
|
Make it possible to create iterators outside Eina.
Many places in EFL we just create walk something, create a list with
walked data, return, then the user walks it again and then deletes
(which will walk again). For such cases it's way better to define
iterators or accessors.
I'm not moving any EFL code to it now, but if people are interested,
things like evas_render_method_list(), evas_font_available_list(),
evas_objects_at_xy_get(), evas_objects_in_rectangle_get(),
evas_object_smart_members_get() are good candidates. If the subject is
already using Eina list, then you can just use
eina_list_iterator_new() and return it, otherwise you can define your
own iterator, which is very easy.
SVN revision: 37956
2008-12-05 19:41:03 -08:00
|
|
|
|
2011-04-07 05:23:22 -07:00
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Frees an iterator.
|
2011-04-07 05:23:22 -07:00
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in,out] iterator The iterator to free.
|
2011-04-07 05:23:22 -07:00
|
|
|
*
|
|
|
|
* This function frees @p iterator if it is not @c NULL;
|
|
|
|
*/
|
2012-07-04 18:12:27 -07:00
|
|
|
EAPI void eina_iterator_free(Eina_Iterator *iterator);
|
2008-08-11 09:30:16 -07:00
|
|
|
|
2011-04-07 05:23:22 -07:00
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Returns the container of an iterator.
|
2011-04-07 05:23:22 -07:00
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in] iterator The iterator.
|
2011-04-07 05:23:22 -07:00
|
|
|
* @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.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI void *eina_iterator_container_get(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) EINA_PURE;
|
2011-04-07 05:23:22 -07:00
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Returns the value of the current element and go to the next one.
|
2011-04-07 05:23:22 -07:00
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in,out] iterator The iterator.
|
|
|
|
* @param[out] data The data of the element.
|
2011-04-07 05:23:22 -07:00
|
|
|
* @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.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator,
|
2012-07-04 18:12:27 -07:00
|
|
|
void **data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
|
2008-08-11 09:30:16 -07:00
|
|
|
|
2011-04-07 05:23:22 -07:00
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Iterates over the container and execute a callback on each element.
|
2011-04-07 05:23:22 -07:00
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in,out] iterator The iterator.
|
|
|
|
* @param[in] callback The callback called on each iteration.
|
|
|
|
* @param[in] fdata The data passed to the callback.
|
2011-04-07 05:23:22 -07:00
|
|
|
*
|
|
|
|
* This function iterates over the elements pointed by @p iterator,
|
2017-10-31 04:31:24 -07:00
|
|
|
* beginning with the current element. For each element, the callback
|
2011-04-07 05:23:22 -07:00
|
|
|
* @p cb is called with the data @p fdata. If @p iterator is @c NULL,
|
2012-05-29 23:55:31 -07:00
|
|
|
* the function returns immediately. Also, if @p cb returns #EINA_FALSE,
|
|
|
|
* the iteration stops at that point, if @p cb returns #EINA_TRUE
|
2011-07-06 07:50:12 -07:00
|
|
|
* the iteration continues.
|
2011-04-07 05:23:22 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
|
|
|
|
Eina_Each_Cb callback,
|
2012-07-04 18:12:27 -07:00
|
|
|
const void *fdata) EINA_ARG_NONNULL(2);
|
2008-08-11 09:30:16 -07:00
|
|
|
|
2011-04-07 05:23:22 -07:00
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Locks the container of the iterator.
|
2011-04-07 05:23:22 -07:00
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in,out] iterator The iterator.
|
2011-04-07 05:23:22 -07:00
|
|
|
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
|
|
|
|
*
|
2011-07-06 07:50:12 -07:00
|
|
|
* If the container of the @p iterator permits it, it will be locked. When a
|
|
|
|
* container is locked calling eina_iterator_foreach() on it will return
|
2011-07-15 07:31:31 -07:00
|
|
|
* immediately. If @p iterator is @c NULL or if a problem occurred, #EINA_FALSE
|
2011-07-06 07:50:12 -07:00
|
|
|
* is returned, otherwise #EINA_TRUE is returned. If the container isn't
|
2012-05-29 23:55:31 -07:00
|
|
|
* lockable, it will return #EINA_TRUE.
|
2011-07-06 07:50:12 -07:00
|
|
|
*
|
|
|
|
* @warning None of the existing eina data structures are lockable.
|
2011-04-07 05:23:22 -07:00
|
|
|
*/
|
2010-08-11 07:32:30 -07:00
|
|
|
EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
|
2011-04-07 05:23:22 -07:00
|
|
|
|
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Unlocks the container of the iterator.
|
2011-04-07 05:23:22 -07:00
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in,out] iterator The iterator.
|
2011-04-07 05:23:22 -07:00
|
|
|
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
|
|
|
|
*
|
2011-07-04 12:48:01 -07:00
|
|
|
* If the container of the @p iterator permits it and was previously
|
2011-04-07 05:23:22 -07:00
|
|
|
* locked, it will be unlocked. If @p iterator is @c NULL or if a
|
|
|
|
* problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE
|
2012-05-29 23:55:31 -07:00
|
|
|
* is returned. If the container is not lockable, it will
|
|
|
|
* return #EINA_TRUE.
|
2011-07-06 07:50:12 -07:00
|
|
|
*
|
|
|
|
* @warning None of the existing eina data structures are lockable.
|
2011-04-07 05:23:22 -07:00
|
|
|
*/
|
2010-08-11 07:32:30 -07:00
|
|
|
EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
|
|
|
|
|
2016-03-06 12:24:34 -08:00
|
|
|
/**
|
|
|
|
* @brief Creates an Eina_Iterator that iterates through a
|
|
|
|
* NUL-terminated C array.
|
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in] array The NUL-terminated array
|
2018-11-15 15:38:40 -08:00
|
|
|
* @return The iterator that will walk over the array.
|
2016-03-06 12:24:34 -08:00
|
|
|
*
|
|
|
|
* You can create it like this:
|
|
|
|
* int array[] = {1, 2, 3, 4};
|
|
|
|
* int* array2[] = {&array[0], &array[1], &array[2], &array[3], NULL};
|
|
|
|
*
|
2018-11-15 15:37:15 -08:00
|
|
|
* Eina_Iterator* iterator = eina_carray_iterator_new((void**)array2);
|
2016-03-06 12:24:34 -08:00
|
|
|
*
|
2016-08-12 06:13:44 -07:00
|
|
|
* @since 1.18
|
2016-03-06 12:24:34 -08:00
|
|
|
*/
|
2018-11-15 15:37:15 -08:00
|
|
|
EAPI Eina_Iterator *eina_carray_iterator_new(void** array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @brief Creates an Eina_Iterator that iterates through a
|
|
|
|
* C array of specified size.
|
|
|
|
*
|
|
|
|
* @param[in] array The array
|
2018-11-15 15:38:40 -08:00
|
|
|
* @return The iterator that will walk over the array.
|
2018-11-15 15:37:15 -08:00
|
|
|
*
|
|
|
|
* 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
|
|
|
|
*/
|
|
|
|
EAPI Eina_Iterator *eina_carray_length_iterator_new(void** array, unsigned int step, unsigned int length) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @def EINA_C_ARRAY_ITERATOR_NEW
|
|
|
|
* @brief Creates an Eina_Iterator that iterates through a
|
|
|
|
* NUL-terminated C array.
|
|
|
|
*
|
|
|
|
* @param[in] array The NUL-terminated array
|
2018-11-15 15:38:40 -08:00
|
|
|
* @return The iterator that will walk over the array.
|
2018-11-15 15:37:15 -08:00
|
|
|
*
|
|
|
|
* You can create it like this:
|
|
|
|
* int array[] = {1, 2, 3, 4};
|
|
|
|
*
|
|
|
|
* Eina_Iterator* iterator = EINA_C_ARRAY_ITERATOR_NEW(array);
|
|
|
|
*
|
|
|
|
* @since 1.22
|
|
|
|
*/
|
|
|
|
#define EINA_C_ARRAY_ITERATOR_NEW(Array) eina_carray_length_iterator_new((void**) Array, sizeof (Array[0]), EINA_C_ARRAY_LENGTH(Array))
|
2016-03-06 12:24:34 -08:00
|
|
|
|
2016-11-20 06:24:26 -08:00
|
|
|
/**
|
2017-10-31 04:31:24 -07:00
|
|
|
* @brief Creates a new iterator which which iterates through all elements with are accepted by the filter callback
|
2016-11-20 06:24:26 -08:00
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in] original the iterator the use as original set
|
|
|
|
* @param[in] filter if the callback returns true the element from the original set is taken into the the new set.
|
|
|
|
* @param[in] free_cb when the iterator is gone this callback will be called with data as argument
|
|
|
|
* @param[in] data the data which is passed to the filter callback
|
2016-11-20 06:24:26 -08:00
|
|
|
*
|
2017-10-31 04:31:24 -07:00
|
|
|
* The iterator is filtered while it is being iterated.
|
2016-11-20 06:24:26 -08:00
|
|
|
* 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
|
|
|
|
*/
|
2016-12-08 10:53:22 -08:00
|
|
|
EAPI Eina_Iterator* eina_iterator_filter_new(Eina_Iterator *original, Eina_Each_Cb filter, Eina_Free_Cb free_cb, void *data) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
2016-11-20 06:24:26 -08:00
|
|
|
|
2018-11-15 17:42:27 -08:00
|
|
|
/**
|
2019-01-28 04:14:20 -08:00
|
|
|
* @brief Creates an Eina_Iterator that iterates through a series
|
2018-11-15 17:42:27 -08:00
|
|
|
* of Eina_Iterator.
|
|
|
|
*
|
|
|
|
* @param[in] it The first Eina_Iterator to iterate over
|
|
|
|
* @return 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
|
|
|
|
*/
|
|
|
|
EAPI Eina_Iterator *eina_multi_iterator_internal_new(Eina_Iterator *it, ...) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @def eina_multi_iterator_new
|
2019-01-28 04:14:20 -08:00
|
|
|
* @brief Creates an Eina_Iterator that iterates through a series
|
2018-11-15 17:42:27 -08:00
|
|
|
* of Eina_Iterator.
|
|
|
|
*
|
|
|
|
* @param[in] it The first Eina_Iterator to iterate over
|
|
|
|
* @return 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
|
|
|
|
*/
|
|
|
|
#define eina_multi_iterator_new(It, ...) eina_multi_iterator_internal_new(It, ##__VA_ARGS__, NULL)
|
|
|
|
|
2009-02-27 08:32:22 -08:00
|
|
|
/**
|
|
|
|
* @def EINA_ITERATOR_FOREACH
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Definition for the macro to iterate over all elements easily.
|
2009-02-27 08:32:22 -08:00
|
|
|
*
|
2018-07-26 04:04:46 -07:00
|
|
|
* @param[in,out] itr The iterator to use.
|
|
|
|
* @param[out] data Where to store * data, must be a pointer support getting
|
2009-02-27 08:32:22 -08:00
|
|
|
* 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:
|
|
|
|
*
|
|
|
|
* @code
|
|
|
|
* 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);
|
|
|
|
* @endcode
|
|
|
|
*
|
2017-02-19 22:18:21 -08:00
|
|
|
* @note This example is not optimal algorithm to release a list since
|
2009-02-27 08:32:22 -08:00
|
|
|
* it will walk the list twice, but it serves as an example. For
|
|
|
|
* optimized version use EINA_LIST_FREE()
|
|
|
|
*
|
2011-07-06 07:50:12 -07:00
|
|
|
* @warning The order in which the elements will be traversed depends on the
|
|
|
|
* underlying container and @b shouldn't be relied upon.
|
|
|
|
*
|
2009-02-27 08:32:22 -08:00
|
|
|
* @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
|
2018-07-12 00:27:15 -07:00
|
|
|
* crash! This is not a limitation of iterators themselves,
|
2009-02-27 08:32:22 -08:00
|
|
|
* rather in the iterators implementations to keep them as simple
|
|
|
|
* and fast as possible.
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
#define EINA_ITERATOR_FOREACH(itr, \
|
2010-07-27 19:37:05 -07:00
|
|
|
data) while (eina_iterator_next((itr), \
|
2010-12-15 03:56:50 -08:00
|
|
|
(void **)(void *)&(data)))
|
2009-02-27 08:32:22 -08:00
|
|
|
|
2009-06-22 13:03:58 -07:00
|
|
|
/**
|
|
|
|
* @}
|
|
|
|
*/
|
|
|
|
|
2008-09-06 22:44:00 -07:00
|
|
|
/**
|
|
|
|
* @}
|
|
|
|
*/
|
|
|
|
|
2008-08-11 09:30:16 -07:00
|
|
|
#endif
|