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_ACCESSOR_H__
|
|
|
|
#define EINA_ACCESSOR_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-13 09:42:25 -07:00
|
|
|
/**
|
|
|
|
* @page eina_accessor_example_01_page Eina_Accessor usage
|
|
|
|
* @dontinclude eina_accessor_01.c
|
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* We start by including necessary headers, declaring variables, and
|
2011-06-13 09:42:25 -07:00
|
|
|
* initializing eina:
|
|
|
|
* @skip #include
|
|
|
|
* @until eina_init
|
|
|
|
*
|
|
|
|
* Next we populate our array and list:
|
|
|
|
* @until }
|
|
|
|
*
|
|
|
|
* Now that we have two containers populated we can actually start the example
|
|
|
|
* and create an accessor:
|
|
|
|
* @until accessor_new
|
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* Once we have the accessor we can use it to access certain elements in the
|
2011-06-13 09:42:25 -07:00
|
|
|
* container:
|
|
|
|
* @until }
|
|
|
|
* @note Unlike iterators accessors allow us non-linear access, which allows us
|
|
|
|
* to print only the odd elements in the container.
|
|
|
|
*
|
|
|
|
* As with every other resource we allocate we need to free the accessor(and the
|
|
|
|
* array):
|
|
|
|
* @until array_free
|
|
|
|
*
|
|
|
|
* Now we create another accessor, this time for the list:
|
|
|
|
* @until accessor_new
|
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* And now the interesting part, we use the same code we used above, to print
|
|
|
|
* parts of the array, to print parts of the list:
|
2011-06-13 09:42:25 -07:00
|
|
|
* @until }
|
|
|
|
*
|
|
|
|
* And to free the list we use a gimmick, instead of freeing @a list, we ask the
|
2014-10-27 01:10:16 -07:00
|
|
|
* accessor for its container and we free that:
|
2011-06-13 09:42:25 -07:00
|
|
|
* @until list_free
|
|
|
|
*
|
|
|
|
* Finally we shut eina down and leave:
|
|
|
|
* @until }
|
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* The full source code can be found in the examples folder
|
|
|
|
* in the @ref eina_accessor_01_c "eina_accessor_01.c" file.
|
2011-06-13 09:42:25 -07:00
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @page eina_accessor_01_c Eina_Accessor usage example
|
|
|
|
*
|
|
|
|
* @include eina_accessor_01.c
|
|
|
|
* @example eina_accessor_01.c
|
|
|
|
*/
|
|
|
|
|
2011-04-07 03:38:25 -07:00
|
|
|
/**
|
2014-10-27 01:10:16 -07:00
|
|
|
* @defgroup Eina_Accessor_Group Accessor Functions
|
|
|
|
* @ingroup Eina_Content_Access_Group
|
2011-04-07 03:38:25 -07:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief This group discusses the functions to manage an accessor on containers.
|
2011-04-07 03:38:25 -07:00
|
|
|
*
|
|
|
|
* 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). Accessors allows random access (that is, any
|
|
|
|
* element in the container). For sequential access, see
|
|
|
|
* @ref Eina_Iterator_Group.
|
|
|
|
*
|
2012-07-17 10:51:10 -07:00
|
|
|
* Getting an accessor to access elements of a given container is done through
|
|
|
|
* the functions of that particular container. There is no function to create
|
|
|
|
* a generic accessor as accessors absolutely depend on the container. This
|
2014-10-27 01:10:16 -07:00
|
|
|
* means you won't find an accessor creation function here, those can be found on
|
2012-07-17 10:51:10 -07:00
|
|
|
* the documentation of the container type you're using. Though created with
|
2014-10-27 01:10:16 -07:00
|
|
|
* container specific functions, accessors are always deleted by the same
|
2012-07-17 10:51:10 -07:00
|
|
|
* function: eina_accessor_free().
|
|
|
|
*
|
|
|
|
* To get the data of an element at a given
|
2011-04-07 03:38:25 -07:00
|
|
|
* position, use eina_accessor_data_get(). To call a function on
|
|
|
|
* chosen elements of a container, use eina_accessor_over().
|
|
|
|
*
|
2011-06-17 07:20:59 -07:00
|
|
|
* See an example @ref eina_accessor_example_01_page "here".
|
2008-09-07 00:19:19 -07:00
|
|
|
*
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Accessor
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Type for a accessor structure.
|
2008-09-07 00:19:19 -07:00
|
|
|
*/
|
2008-08-11 09:30:16 -07:00
|
|
|
typedef struct _Eina_Accessor Eina_Accessor;
|
|
|
|
|
2010-11-06 05:34:55 -07:00
|
|
|
/**
|
|
|
|
* @typedef Eina_Accessor_Get_At_Callback
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Type for a callback that returns the data of a container as the given index.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
|
|
|
typedef Eina_Bool (*Eina_Accessor_Get_At_Callback)(Eina_Accessor *it,
|
2011-04-27 08:50:12 -07:00
|
|
|
unsigned int idx,
|
2010-11-06 05:34:55 -07:00
|
|
|
void **data);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Accessor_Get_Container_Callback
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Type for a callback to return the container of the accessor.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
|
|
|
typedef void *(*Eina_Accessor_Get_Container_Callback)(Eina_Accessor *it);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Accessor_Free_Callback
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Type for a callback to free the accessor.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
|
|
|
typedef void (*Eina_Accessor_Free_Callback)(Eina_Accessor *it);
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @typedef Eina_Accessor_Lock_Callback
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Type for a callback to lock the accessor.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
2010-08-11 07:32:30 -07:00
|
|
|
typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *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
|
|
|
|
2014-02-25 12:22:28 -08:00
|
|
|
/**
|
|
|
|
* @typedef Eina_Accessor_Clone_Callback
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Type for a callback to return a clone for the accessor.
|
2014-02-25 12:22:28 -08:00
|
|
|
* @since 1.10
|
|
|
|
*/
|
|
|
|
typedef Eina_Accessor* (*Eina_Accessor_Clone_Callback)(Eina_Accessor *it);
|
|
|
|
|
2011-07-15 07:07:03 -07:00
|
|
|
/**
|
|
|
|
* @struct _Eina_Accessor
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Structure to provide random access to data structures.
|
2012-07-17 10:51:10 -07:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @note When creating an accessor remember to set the type using #EINA_MAGIC_SET
|
2011-07-15 07:07:03 -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_Accessor
|
|
|
|
{
|
2014-02-25 12:22:28 -08:00
|
|
|
#define EINA_ACCESSOR_VERSION 2
|
2014-10-27 01:10:16 -07:00
|
|
|
int version; /**< Version of the Accessor API */
|
2010-08-19 05:02:28 -07:00
|
|
|
|
2014-10-27 01:10:16 -07:00
|
|
|
Eina_Accessor_Get_At_Callback get_at EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT; /**< Callback called when a data element is requested */
|
|
|
|
Eina_Accessor_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested */
|
|
|
|
Eina_Accessor_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed */
|
2008-12-05 22:53:14 -08:00
|
|
|
|
2014-10-27 01:10:16 -07:00
|
|
|
Eina_Accessor_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked */
|
|
|
|
Eina_Accessor_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_ACCESSOR 0x98761232
|
* 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
|
2014-02-25 12:22:28 -08:00
|
|
|
|
|
|
|
Eina_Accessor_Clone_Callback clone EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is to be cloned. @since 1.10 */
|
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_ACCESSOR_GET_AT(Function)
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Get_At_Callback.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
#define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function)
|
2010-11-06 05:34:55 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @def FUNC_ACCESSOR_GET_CONTAINER(Function)
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Get_Container_Callback.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
2010-08-12 23:36:33 -07:00
|
|
|
#define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function)
|
2010-11-06 05:34:55 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @def FUNC_ACCESSOR_FREE(Function)
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Free_Callback.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
#define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function)
|
2010-11-06 05:34:55 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @def FUNC_ACCESSOR_LOCK(Function)
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Definition for helper macro to cast @a Function to a Eina_Iterator_Lock_Callback.
|
2010-11-06 05:34:55 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
#define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_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
|
|
|
|
2014-02-25 12:22:28 -08:00
|
|
|
/**
|
|
|
|
* @def FUNC_ACCESSOR_CLONE(Function)
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Definition for helper macro to cast @p Function to a Eina_Iterator_Clone_Callback.
|
2014-02-25 12:22:28 -08:00
|
|
|
* @since 1.10
|
|
|
|
*/
|
|
|
|
#define FUNC_ACCESSOR_CLONE(Function) ((Eina_Accessor_Clone_Callback)Function)
|
|
|
|
|
2011-04-07 03:38:25 -07:00
|
|
|
|
|
|
|
/**
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Frees an accessor.
|
2017-02-19 22:18:21 -08:00
|
|
|
* @details This function frees @a accessor if it is not @c NULL.
|
2014-10-27 01:10:16 -07:00
|
|
|
* @param[in] accessor The accessor to free
|
2011-04-07 03:38:25 -07:00
|
|
|
*
|
|
|
|
*/
|
2012-07-04 18:12:27 -07:00
|
|
|
EAPI void eina_accessor_free(Eina_Accessor *accessor);
|
2011-04-07 04:01:26 -07:00
|
|
|
|
|
|
|
/**
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Gets the data of an accessor at the given position.
|
2017-02-19 22:18:21 -08:00
|
|
|
* @details This function retrieves the data of the element pointed by
|
|
|
|
* @p accessor at the position @p position, and stores it in
|
|
|
|
* @p data. If @p accessor is @c NULL or if an error occurs, @c EINA_FALSE
|
|
|
|
* is returned, otherwise @c EINA_TRUE is returned.
|
2014-10-27 01:10:16 -07:00
|
|
|
* @param[in] accessor The accessor
|
|
|
|
* @param[in] position The position of the element
|
|
|
|
* @param[in] data The pointer that stores the data to retrieve
|
|
|
|
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
|
|
|
|
*
|
2011-04-07 04:01:26 -07:00
|
|
|
*/
|
2010-08-16 08:02:37 -07:00
|
|
|
EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor,
|
2010-10-22 23:41:45 -07:00
|
|
|
unsigned int position,
|
|
|
|
void **data) EINA_ARG_NONNULL(1);
|
2011-04-07 04:01:26 -07:00
|
|
|
|
|
|
|
/**
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Gets the container of an accessor.
|
2017-02-19 22:18:21 -08:00
|
|
|
* @details This function returns the container that created @p accessor. If
|
|
|
|
* @p accessor is @c NULL, this function returns @c NULL.
|
2014-10-27 01:10:16 -07:00
|
|
|
* @param[in] accessor The accessor
|
|
|
|
* @return The container that created the accessor
|
2011-04-07 04:01:26 -07:00
|
|
|
*
|
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE;
|
2011-04-07 04:01:26 -07:00
|
|
|
|
|
|
|
/**
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Iterates over the container and executes a callback on the chosen elements.
|
2017-02-19 22:18:21 -08:00
|
|
|
* @details This function iterates over the elements pointed by @p accessor,
|
|
|
|
* starting from the element at position @p start and ending at the
|
|
|
|
* element at position @p end. For each element, the callback
|
|
|
|
* @p cb is called with the data @p fdata. If @p accessor is @c NULL
|
|
|
|
* or if @p start is greater than or equal to @p end, the function returns
|
|
|
|
* immediately.
|
2014-10-27 01:10:16 -07:00
|
|
|
*
|
|
|
|
* @param[in] accessor The accessor
|
|
|
|
* @param[in] cb The callback called on the chosen elements
|
|
|
|
* @param[in] start The position of the first element
|
|
|
|
* @param[in] end The position of the last element
|
|
|
|
* @param[in] fdata The data passed to the callback
|
|
|
|
*
|
2011-04-07 04:01:26 -07:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
EAPI void eina_accessor_over(Eina_Accessor *accessor,
|
|
|
|
Eina_Each_Cb cb,
|
|
|
|
unsigned int start,
|
|
|
|
unsigned int end,
|
2012-07-04 18:12:27 -07:00
|
|
|
const void *fdata) EINA_ARG_NONNULL(2);
|
2011-04-07 04:01:26 -07:00
|
|
|
|
|
|
|
/**
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Locks the container of the accessor.
|
2011-04-07 04:01:26 -07:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @param[in] accessor The accessor
|
|
|
|
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
|
2011-04-07 04:01:26 -07:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @note If the container of the @p accessor permits it, it is locked. When a
|
|
|
|
* container is locked by calling eina_accessor_over() on it, it returns
|
|
|
|
* immediately. If @p accessor is @c 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.
|
2011-07-06 07:50:46 -07:00
|
|
|
*
|
2016-03-06 03:35:13 -08:00
|
|
|
* @warning None of the existing eina data structures are lockable.
|
2011-04-07 04:01:26 -07:00
|
|
|
*/
|
2010-08-11 07:32:30 -07:00
|
|
|
EAPI Eina_Bool eina_accessor_lock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
|
2011-04-07 04:01:26 -07:00
|
|
|
|
2014-02-25 12:22:28 -08:00
|
|
|
/**
|
2014-10-27 01:10:16 -07:00
|
|
|
* @brief Clones the container of the accessor.
|
2014-02-25 12:22:28 -08:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @param[in] accessor The accessor.
|
2014-02-25 12:22:28 -08:00
|
|
|
* @return Another accessor
|
|
|
|
* @since 1.10
|
|
|
|
*/
|
|
|
|
EAPI Eina_Accessor* eina_accessor_clone(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
|
|
|
|
|
2011-04-07 04:01:26 -07:00
|
|
|
/**
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Unlocks the container of the accessor.
|
2011-04-07 04:01:26 -07:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @param[in] accessor The accessor
|
|
|
|
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
|
2011-04-07 04:01:26 -07:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @note If the container of the @p accessor permits it and is previously
|
|
|
|
* locked, it is unlocked. If @p accessor is @c 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.
|
2011-07-06 07:50:46 -07:00
|
|
|
*
|
|
|
|
* @warning None of the existing eina data structures are lockable.
|
2011-04-07 04:01:26 -07:00
|
|
|
*/
|
2010-08-11 07:32:30 -07:00
|
|
|
EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
|
|
|
|
|
2009-02-27 08:32:22 -08:00
|
|
|
/**
|
|
|
|
* @def EINA_ACCESSOR_FOREACH
|
2017-02-19 22:18:21 -08:00
|
|
|
* @brief Definition for helper macro to iterate over all the elements easily.
|
|
|
|
* @details This macro allows a convenient way to loop over all elements in an
|
|
|
|
* accessor, very similar to EINA_LIST_FOREACH().
|
2009-02-27 08:32:22 -08:00
|
|
|
*
|
2018-09-08 04:19:53 -07:00
|
|
|
* @param[in] accessor The accessor to use
|
|
|
|
* @param[out] counter A counter used by eina_accessor_data_get() when
|
|
|
|
* iterating over the container.
|
|
|
|
* @param[out] data A pointer to store the data \n
|
2014-10-27 01:10:16 -07:00
|
|
|
* It must be a pointer to support getting
|
|
|
|
* its address since eina_accessor_data_get() requires a pointer.
|
2009-02-27 08:32:22 -08:00
|
|
|
*
|
|
|
|
* 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 accessors:
|
|
|
|
*
|
|
|
|
* @code
|
|
|
|
* Eina_List *list;
|
|
|
|
* Eina_Accessor *accessor;
|
|
|
|
* unsigned int i;
|
|
|
|
* char *data;
|
|
|
|
*
|
|
|
|
* // list is already filled,
|
|
|
|
* // its elements are just duplicated strings
|
|
|
|
*
|
|
|
|
* accessor = eina_list_accessor_new(list);
|
|
|
|
* EINA_ACCESSOR_FOREACH(accessor, i, data)
|
|
|
|
* free(data);
|
|
|
|
* eina_accessor_free(accessor);
|
|
|
|
* eina_list_free(list);
|
|
|
|
* @endcode
|
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @note If the data type provides both iterators and accessors, prefer
|
|
|
|
* to use iterators to iterate over, as they're likely to be more
|
|
|
|
* optimized for such a task.
|
2009-02-27 08:32:22 -08:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @note 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().
|
2009-02-27 08:32:22 -08:00
|
|
|
*
|
2014-10-27 01:10:16 -07:00
|
|
|
* @warning Unless explicitly stated in the function's returning accessors,
|
|
|
|
* do not modify the accessed object while you walk through it. In this
|
|
|
|
* example using lists, do not remove list nodes or the program might
|
|
|
|
* crash. This is not a limitation of the accessors themselves,
|
|
|
|
* but a limitation in the accessors implementations to keep them as simple
|
|
|
|
* and fast as possible.
|
2009-02-27 08:32:22 -08:00
|
|
|
*/
|
2010-10-22 23:41:45 -07:00
|
|
|
#define EINA_ACCESSOR_FOREACH(accessor, counter, data) \
|
|
|
|
for ((counter) = 0; \
|
2010-12-15 03:56:50 -08:00
|
|
|
eina_accessor_data_get((accessor), (counter), (void **)(void *)&(data)); \
|
2010-08-16 08:02:37 -07:00
|
|
|
(counter)++)
|
2009-02-27 08:32:22 -08:00
|
|
|
|
2009-06-22 13:03:58 -07:00
|
|
|
/**
|
|
|
|
* @}
|
|
|
|
*/
|
|
|
|
|
2008-08-11 09:30:16 -07:00
|
|
|
#endif
|