2 * vim:ts=8:sw=3:sts=8:noexpandtab:cino=>5n-3f0^-2{2
4 /* EINA - EFL data type library
5 * Copyright (C) 2002-2008 Cedric Bail
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library;
19 * if not, see <http://www.gnu.org/licenses/>.
28 #include "eina_config.h"
29 #include "eina_private.h"
31 /* undefs EINA_ARG_NONULL() so NULL checks are not compiled out! */
32 #include "eina_safety_checks.h"
33 #include "eina_accessor.h"
35 /*============================================================================*
37 *============================================================================*/
43 #define EINA_MAGIC_CHECK_ACCESSOR(d) \
45 if (!EINA_MAGIC_CHECK(d, EINA_MAGIC_ACCESSOR)) \
46 EINA_MAGIC_FAIL(d, EINA_MAGIC_ACCESSOR); \
53 /*============================================================================*
55 *============================================================================*/
57 /*============================================================================*
59 *============================================================================*/
62 * @addtogroup Eina_Accessor_Group Accessor Functions
64 * @brief These functions manage accessor on containers.
66 * These functions allow to access elements of a container in a
67 * generic way, without knowing which container is used (a bit like
68 * iterators in the C++ STL). Accessors allows random access (that is, any
69 * element in the container). For sequential access, see
70 * @ref Eina_Iterator_Group.
72 * An accessor is created from container data types, so no creation
73 * function is available here. An accessor is deleted with
74 * eina_accessor_free(). To get the data of an element at a given
75 * position, use eina_accessor_data_get(). To call a function on
76 * chosen elements of a container, use eina_accessor_over().
82 * @brief Free an accessor.
84 * @param accessor The accessor to free.
86 * This function frees @p accessor if it is not @c NULL;
89 eina_accessor_free(Eina_Accessor *accessor)
91 EINA_MAGIC_CHECK_ACCESSOR(accessor);
92 EINA_SAFETY_ON_NULL_RETURN(accessor);
93 EINA_SAFETY_ON_NULL_RETURN(accessor->free);
94 accessor->free(accessor);
98 * @brief Return the container of an accessor.
100 * @param accessor The accessor.
101 * @return The container which created the accessor.
103 * This function returns the container which created @p accessor. If
104 * @p accessor is @c NULL, this function returns @c NULL.
107 eina_accessor_container_get(Eina_Accessor *accessor)
109 EINA_MAGIC_CHECK_ACCESSOR(accessor);
110 EINA_SAFETY_ON_NULL_RETURN_VAL(accessor, NULL);
111 EINA_SAFETY_ON_NULL_RETURN_VAL(accessor->get_container, NULL);
112 return accessor->get_container(accessor);
116 * @brief Retrieve the data of an accessor at a given position.
118 * @param accessor The accessor.
119 * @param position The position of the element.
120 * @param data The pointer that stores the data to retrieve.
121 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
123 * This function retrieves the data of the element pointed by
124 * @p accessor at the porition @p position, and stores it in
125 * @p data. If @p accessor is @c NULL or if an error occurred,
126 * #EINA_FALSE is returned, otherwise EINA_TRUE is returned.
129 eina_accessor_data_get(Eina_Accessor *accessor, unsigned int position, void **data)
131 EINA_MAGIC_CHECK_ACCESSOR(accessor);
132 EINA_SAFETY_ON_NULL_RETURN_VAL(accessor, EINA_FALSE);
133 EINA_SAFETY_ON_NULL_RETURN_VAL(accessor->get_at, EINA_FALSE);
134 EINA_SAFETY_ON_NULL_RETURN_VAL(data, EINA_FALSE);
135 return accessor->get_at(accessor, position, data);
139 * @brief Iterate over the container and execute a callback on chosen elements.
141 * @param accessor The accessor.
142 * @param cb The callback called on the chosen elements.
143 * @param start The position of the first element.
144 * @param end The position of the last element.
145 * @param fdata The data passed to the callback.
147 * This function iterates over the elements pointed by @p accessor,
148 * starting from the element at position @p start and ending to the
149 * element at position @p end. For Each element, the callback
150 * @p cb is called with the data @p fdata. If @p accessor is @c NULL
151 * or if @p start is greter or equal than @p end, the function returns
155 eina_accessor_over(Eina_Accessor *accessor,
161 const void *container;
165 EINA_MAGIC_CHECK_ACCESSOR(accessor);
166 EINA_SAFETY_ON_NULL_RETURN(accessor);
167 EINA_SAFETY_ON_NULL_RETURN(accessor->get_container);
168 EINA_SAFETY_ON_NULL_RETURN(accessor->get_at);
169 EINA_SAFETY_ON_NULL_RETURN(cb);
170 EINA_SAFETY_ON_FALSE_RETURN(start < end);
172 container = accessor->get_container(accessor);
173 for (i = start; i < end && accessor->get_at(accessor, i, &data) == EINA_TRUE; ++i)
174 if (cb(container, data, (void*) fdata) != EINA_TRUE) return ;