diff options
author | David Walter Seikel | 2012-01-04 18:41:13 +1000 |
---|---|---|
committer | David Walter Seikel | 2012-01-04 18:41:13 +1000 |
commit | dd7595a3475407a7fa96a97393bae8c5220e8762 (patch) | |
tree | e341e911d7eb911a51684a7412ef7f7c7605d28e /libraries/eina/src/include/eina_accessor.h | |
parent | Add the skeleton. (diff) | |
download | SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.zip SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.gz SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.bz2 SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.xz |
Add the base Enlightenment Foundation Libraries - eina, eet, evas, ecore, embryo, and edje.
Note that embryo wont be used, but I'm not sure yet if you can build edje without it.
Diffstat (limited to 'libraries/eina/src/include/eina_accessor.h')
-rw-r--r-- | libraries/eina/src/include/eina_accessor.h | 340 |
1 files changed, 340 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_accessor.h b/libraries/eina/src/include/eina_accessor.h new file mode 100644 index 0000000..cae7a5c --- /dev/null +++ b/libraries/eina/src/include/eina_accessor.h | |||
@@ -0,0 +1,340 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008 Cedric Bail | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_ACCESSOR_H__ | ||
20 | #define EINA_ACCESSOR_H__ | ||
21 | |||
22 | #include "eina_config.h" | ||
23 | |||
24 | #include "eina_types.h" | ||
25 | #include "eina_magic.h" | ||
26 | |||
27 | /** | ||
28 | * @page eina_accessor_example_01_page Eina_Accessor usage | ||
29 | * @dontinclude eina_accessor_01.c | ||
30 | * | ||
31 | * We start by including necessary headers, declaring variables and | ||
32 | * initializing eina: | ||
33 | * @skip #include | ||
34 | * @until eina_init | ||
35 | * | ||
36 | * Next we populate our array and list: | ||
37 | * @until } | ||
38 | * | ||
39 | * Now that we have two containers populated we can actually start the example | ||
40 | * and create an accessor: | ||
41 | * @until accessor_new | ||
42 | * | ||
43 | * Once having the accessor we can use it to access certain elements in the | ||
44 | * container: | ||
45 | * @until } | ||
46 | * @note Unlike iterators accessors allow us non-linear access, which allows us | ||
47 | * to print only the odd elements in the container. | ||
48 | * | ||
49 | * As with every other resource we allocate we need to free the accessor(and the | ||
50 | * array): | ||
51 | * @until array_free | ||
52 | * | ||
53 | * Now we create another accessor, this time for the list: | ||
54 | * @until accessor_new | ||
55 | * | ||
56 | * And now the interesting bit, we use the same code we used above to print | ||
57 | * parts of the array to print parts of the list: | ||
58 | * @until } | ||
59 | * | ||
60 | * And to free the list we use a gimmick, instead of freeing @a list, we ask the | ||
61 | * accessor for it's container and free that: | ||
62 | * @until list_free | ||
63 | * | ||
64 | * Finally we shut eina down and leave: | ||
65 | * @until } | ||
66 | * | ||
67 | * The full source code can be found on the examples folder | ||
68 | * on the @ref eina_accessor_01_c "eina_accessor_01.c" file. | ||
69 | */ | ||
70 | |||
71 | /** | ||
72 | * @page eina_accessor_01_c Eina_Accessor usage example | ||
73 | * | ||
74 | * @include eina_accessor_01.c | ||
75 | * @example eina_accessor_01.c | ||
76 | */ | ||
77 | |||
78 | /** | ||
79 | * @addtogroup Eina_Accessor_Group Accessor Functions | ||
80 | * | ||
81 | * @brief These functions manage accessor on containers. | ||
82 | * | ||
83 | * These functions allow to access elements of a container in a | ||
84 | * generic way, without knowing which container is used (a bit like | ||
85 | * iterators in the C++ STL). Accessors allows random access (that is, any | ||
86 | * element in the container). For sequential access, see | ||
87 | * @ref Eina_Iterator_Group. | ||
88 | * | ||
89 | * An accessor is created from container data types, so no creation | ||
90 | * function is available here. An accessor is deleted with | ||
91 | * eina_accessor_free(). To get the data of an element at a given | ||
92 | * position, use eina_accessor_data_get(). To call a function on | ||
93 | * chosen elements of a container, use eina_accessor_over(). | ||
94 | * | ||
95 | * See an example @ref eina_accessor_example_01_page "here". | ||
96 | */ | ||
97 | |||
98 | /** | ||
99 | * @addtogroup Eina_Content_Access_Group Content Access | ||
100 | * | ||
101 | * @{ | ||
102 | */ | ||
103 | |||
104 | /** | ||
105 | * @defgroup Eina_Accessor_Group Accessor Functions | ||
106 | * | ||
107 | * @{ | ||
108 | */ | ||
109 | |||
110 | /** | ||
111 | * @typedef Eina_Accessor | ||
112 | * Abstract type for accessors. | ||
113 | */ | ||
114 | typedef struct _Eina_Accessor Eina_Accessor; | ||
115 | |||
116 | /** | ||
117 | * @typedef Eina_Accessor_Get_At_Callback | ||
118 | * Type for a callback that returns the data of a container as the given index. | ||
119 | */ | ||
120 | typedef Eina_Bool (*Eina_Accessor_Get_At_Callback)(Eina_Accessor *it, | ||
121 | unsigned int idx, | ||
122 | void **data); | ||
123 | |||
124 | /** | ||
125 | * @typedef Eina_Accessor_Get_Container_Callback | ||
126 | * Type for a callback that returns the container. | ||
127 | */ | ||
128 | typedef void *(*Eina_Accessor_Get_Container_Callback)(Eina_Accessor *it); | ||
129 | |||
130 | /** | ||
131 | * @typedef Eina_Accessor_Free_Callback | ||
132 | * Type for a callback that frees the container. | ||
133 | */ | ||
134 | typedef void (*Eina_Accessor_Free_Callback)(Eina_Accessor *it); | ||
135 | |||
136 | /** | ||
137 | * @typedef Eina_Accessor_Lock_Callback | ||
138 | * Type for a callback that lock the container. | ||
139 | */ | ||
140 | typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it); | ||
141 | |||
142 | /** | ||
143 | * @struct _Eina_Accessor | ||
144 | * Type to provide random access to data structures. | ||
145 | */ | ||
146 | struct _Eina_Accessor | ||
147 | { | ||
148 | #define EINA_ACCESSOR_VERSION 1 | ||
149 | int version; /**< Version of the Accessor API. */ | ||
150 | |||
151 | Eina_Accessor_Get_At_Callback get_at EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT; /**< Callback called when a data element is requested. */ | ||
152 | Eina_Accessor_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested. */ | ||
153 | Eina_Accessor_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed. */ | ||
154 | |||
155 | Eina_Accessor_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */ | ||
156 | Eina_Accessor_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked. */ | ||
157 | |||
158 | #define EINA_MAGIC_ACCESSOR 0x98761232 | ||
159 | EINA_MAGIC | ||
160 | }; | ||
161 | |||
162 | /** | ||
163 | * @def FUNC_ACCESSOR_GET_AT(Function) | ||
164 | * Helper macro to cast @p Function to a Eina_Accessor_Get_At_Callback. | ||
165 | */ | ||
166 | #define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function) | ||
167 | |||
168 | /** | ||
169 | * @def FUNC_ACCESSOR_GET_CONTAINER(Function) | ||
170 | * Helper macro to cast @p Function to a Eina_Accessor_Get_Container_Callback. | ||
171 | */ | ||
172 | #define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function) | ||
173 | |||
174 | /** | ||
175 | * @def FUNC_ACCESSOR_FREE(Function) | ||
176 | * Helper macro to cast @p Function to a Eina_Accessor_Free_Callback. | ||
177 | */ | ||
178 | #define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function) | ||
179 | |||
180 | /** | ||
181 | * @def FUNC_ACCESSOR_LOCK(Function) | ||
182 | * Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback. | ||
183 | */ | ||
184 | #define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_Lock_Callback)Function) | ||
185 | |||
186 | |||
187 | /** | ||
188 | * @brief Free an accessor. | ||
189 | * | ||
190 | * @param accessor The accessor to free. | ||
191 | * | ||
192 | * This function frees @p accessor if it is not @c NULL; | ||
193 | */ | ||
194 | EAPI void eina_accessor_free(Eina_Accessor *accessor) EINA_ARG_NONNULL(1); | ||
195 | |||
196 | /** | ||
197 | * @brief Retrieve the data of an accessor at a given position. | ||
198 | * | ||
199 | * @param accessor The accessor. | ||
200 | * @param position The position of the element. | ||
201 | * @param data The pointer that stores the data to retrieve. | ||
202 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
203 | * | ||
204 | * This function retrieves the data of the element pointed by | ||
205 | * @p accessor at the porition @p position, and stores it in | ||
206 | * @p data. If @p accessor is @c NULL or if an error occurred, | ||
207 | * #EINA_FALSE is returned, otherwise EINA_TRUE is returned. | ||
208 | */ | ||
209 | EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor, | ||
210 | unsigned int position, | ||
211 | void **data) EINA_ARG_NONNULL(1); | ||
212 | |||
213 | /** | ||
214 | * @brief Return the container of an accessor. | ||
215 | * | ||
216 | * @param accessor The accessor. | ||
217 | * @return The container which created the accessor. | ||
218 | * | ||
219 | * This function returns the container which created @p accessor. If | ||
220 | * @p accessor is @c NULL, this function returns @c NULL. | ||
221 | */ | ||
222 | EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE; | ||
223 | |||
224 | /** | ||
225 | * @brief Iterate over the container and execute a callback on chosen elements. | ||
226 | * | ||
227 | * @param accessor The accessor. | ||
228 | * @param cb The callback called on the chosen elements. | ||
229 | * @param start The position of the first element. | ||
230 | * @param end The position of the last element. | ||
231 | * @param fdata The data passed to the callback. | ||
232 | * | ||
233 | * This function iterates over the elements pointed by @p accessor, | ||
234 | * starting from the element at position @p start and ending to the | ||
235 | * element at position @p end. For Each element, the callback | ||
236 | * @p cb is called with the data @p fdata. If @p accessor is @c NULL | ||
237 | * or if @p start is greter or equal than @p end, the function returns | ||
238 | * immediately. | ||
239 | */ | ||
240 | EAPI void eina_accessor_over(Eina_Accessor *accessor, | ||
241 | Eina_Each_Cb cb, | ||
242 | unsigned int start, | ||
243 | unsigned int end, | ||
244 | const void *fdata) EINA_ARG_NONNULL(1, 2); | ||
245 | |||
246 | /** | ||
247 | * @brief Lock the container of the accessor. | ||
248 | * | ||
249 | * @param accessor The accessor. | ||
250 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
251 | * | ||
252 | * If the container of the @p accessor permits it, it will be locked. When a | ||
253 | * container is locked calling eina_accessor_over() on it will return | ||
254 | * immediately. If @p accessor is @c NULL or if a problem occurred, #EINA_FALSE | ||
255 | * is returned, otherwise #EINA_TRUE is returned. If the container isn't | ||
256 | * lockable, it will return EINA_TRUE. | ||
257 | * | ||
258 | * @warning None of the existing eina data structures are lockable. | ||
259 | */ | ||
260 | EAPI Eina_Bool eina_accessor_lock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1); | ||
261 | |||
262 | /** | ||
263 | * @brief Unlock the container of the accessor. | ||
264 | * | ||
265 | * @param accessor The accessor. | ||
266 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
267 | * | ||
268 | * If the container of the @p accessor permits it and was previously | ||
269 | * locked, it will be unlocked. If @p accessor is @c NULL or if a | ||
270 | * problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE | ||
271 | * is returned. If the container is not lockable, it will return | ||
272 | * EINA_TRUE. | ||
273 | * | ||
274 | * @warning None of the existing eina data structures are lockable. | ||
275 | */ | ||
276 | EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1); | ||
277 | |||
278 | /** | ||
279 | * @def EINA_ACCESSOR_FOREACH | ||
280 | * @brief Macro to iterate over all elements easily. | ||
281 | * | ||
282 | * @param accessor The accessor to use. | ||
283 | * @param counter A counter used by eina_accessor_data_get() when | ||
284 | * iterating over the container. | ||
285 | * @param data Where to store * data, must be a pointer support getting | ||
286 | * its address since * eina_accessor_data_get() requires a pointer to | ||
287 | * pointer! | ||
288 | * | ||
289 | * This macro allows a convenient way to loop over all elements in an | ||
290 | * accessor, very similar to EINA_LIST_FOREACH(). | ||
291 | * | ||
292 | * This macro can be used for freeing the data of a list, like in the | ||
293 | * following example. It has the same goal as the one documented in | ||
294 | * EINA_LIST_FOREACH(), but using accessors: | ||
295 | * | ||
296 | * @code | ||
297 | * Eina_List *list; | ||
298 | * Eina_Accessor *accessor; | ||
299 | * unsigned int i; | ||
300 | * char *data; | ||
301 | * | ||
302 | * // list is already filled, | ||
303 | * // its elements are just duplicated strings | ||
304 | * | ||
305 | * accessor = eina_list_accessor_new(list); | ||
306 | * EINA_ACCESSOR_FOREACH(accessor, i, data) | ||
307 | * free(data); | ||
308 | * eina_accessor_free(accessor); | ||
309 | * eina_list_free(list); | ||
310 | * @endcode | ||
311 | * | ||
312 | * @note if the datatype provides both iterators and accessors prefer | ||
313 | * to use iterators to iterate over, as they're likely to be more | ||
314 | * optimized for such task. | ||
315 | * | ||
316 | * @note this example is not optimal algorithm to release a list since | ||
317 | * it will walk the list twice, but it serves as an example. For | ||
318 | * optimized version use EINA_LIST_FREE() | ||
319 | * | ||
320 | * @warning unless explicitly stated in functions returning accessors, | ||
321 | * do not modify the accessed object while you walk it, in this | ||
322 | * example using lists, do not remove list nodes or you might | ||
323 | * crash! This is not a limitiation of accessors themselves, | ||
324 | * rather in the accessors implementations to keep them as simple | ||
325 | * and fast as possible. | ||
326 | */ | ||
327 | #define EINA_ACCESSOR_FOREACH(accessor, counter, data) \ | ||
328 | for ((counter) = 0; \ | ||
329 | eina_accessor_data_get((accessor), (counter), (void **)(void *)&(data)); \ | ||
330 | (counter)++) | ||
331 | |||
332 | /** | ||
333 | * @} | ||
334 | */ | ||
335 | |||
336 | /** | ||
337 | * @} | ||
338 | */ | ||
339 | |||
340 | #endif | ||