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_array.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_array.h')
-rw-r--r-- | libraries/eina/src/include/eina_array.h | 449 |
1 files changed, 449 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_array.h b/libraries/eina/src/include/eina_array.h new file mode 100644 index 0000000..d33f5e9 --- /dev/null +++ b/libraries/eina/src/include/eina_array.h | |||
@@ -0,0 +1,449 @@ | |||
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_ARRAY_H_ | ||
20 | #define EINA_ARRAY_H_ | ||
21 | |||
22 | #include <stdlib.h> | ||
23 | |||
24 | #include "eina_config.h" | ||
25 | |||
26 | #include "eina_types.h" | ||
27 | #include "eina_error.h" | ||
28 | #include "eina_iterator.h" | ||
29 | #include "eina_accessor.h" | ||
30 | #include "eina_magic.h" | ||
31 | |||
32 | |||
33 | /** | ||
34 | * @page array_01_example_page Basic array usage | ||
35 | * @dontinclude eina_array_01.c | ||
36 | * | ||
37 | * For this example we add stdlib.h, stdio.h and string.h for some | ||
38 | * convenience functions. The first thing to do to be able to use an | ||
39 | * @ref Eina_Array is to include Eina.h: | ||
40 | * @skip #include | ||
41 | * @until Eina.h | ||
42 | * | ||
43 | * Here we have a callback that prints the element given to it: | ||
44 | * @until } | ||
45 | * | ||
46 | * Now we create our entry point and declare some variables, nothing especial: | ||
47 | * @until unsigned | ||
48 | * | ||
49 | * Before we can start using any array function we need to initialize eina: | ||
50 | * @until eina_init | ||
51 | * | ||
52 | * So now to actually creating our array. The only interesting thing here is the | ||
53 | * argument given to the eina_array_new() function, this argument sets how fast | ||
54 | * the array grows. | ||
55 | * @until array_new | ||
56 | * | ||
57 | * If you know before hand how big the array will need to be you should set the | ||
58 | * step to that. In our case we can set it to the number of string we have and | ||
59 | * since we didn't do that in the eina_array_new() we can do it now: | ||
60 | * @until array_step_set | ||
61 | * | ||
62 | * Now let us populate our array with some strings: | ||
63 | * @until push | ||
64 | * @note Notice we use strdup, so we will have to free that memory later on. | ||
65 | * | ||
66 | * Now lets check the size of the array: | ||
67 | * @until printf | ||
68 | * | ||
69 | * And now we call a function on every member of our array to print it: | ||
70 | * @until foreach | ||
71 | * | ||
72 | * One of the strenghts of @ref Eina_Array over @ref Eina_List is that it has | ||
73 | * very fast random access to elements, so this is very efficient: | ||
74 | * @until printf | ||
75 | * | ||
76 | * And now we free up the memory allocated with the strdup()s: | ||
77 | * @until free | ||
78 | * | ||
79 | * And the array memory itself: | ||
80 | * @until array_free | ||
81 | * | ||
82 | * And finally shutdown eina and exit: | ||
83 | * @until } | ||
84 | * | ||
85 | * The full source code can be found on the examples folder | ||
86 | * on the @ref eina_array_01_c "eina_array_01.c" file. | ||
87 | */ | ||
88 | |||
89 | /** | ||
90 | * @page eina_array_01_c Basic array usage example | ||
91 | * | ||
92 | * @include eina_array_01.c | ||
93 | * @example eina_array_01.c | ||
94 | */ | ||
95 | |||
96 | /** | ||
97 | * @page array_02_example_page Removing array elements | ||
98 | * @dontinclude eina_array_02.c | ||
99 | * | ||
100 | * Just the usual includes: | ||
101 | * @skip #include | ||
102 | * @until Eina.h | ||
103 | * | ||
104 | * This the callback we are going to use to decide which strings stay on the | ||
105 | * array and which will be removed, we use something simple, but this can be as | ||
106 | * complex as you like: | ||
107 | * @until } | ||
108 | * | ||
109 | * This is the same code we used before to populate the list with the slight | ||
110 | * difference of not using strdup: | ||
111 | * @until array_push | ||
112 | * | ||
113 | * So we have added all our elements to the array, but it turns out that is not | ||
114 | * the elements we wanted, so let's empty the array and add the correct strings: | ||
115 | * @until array_push | ||
116 | * | ||
117 | * It seems we made a little mistake in one of our strings so we need to replace | ||
118 | * it, here is how: | ||
119 | * @until data_set | ||
120 | * | ||
121 | * Now that there is a populated array we can remove elements from it easily: | ||
122 | * @until array_remove | ||
123 | * | ||
124 | * And check that the elements were actually removed: | ||
125 | * @until printf | ||
126 | * | ||
127 | * Since this time we didn't use strdup we don't need to free each string: | ||
128 | * @until } | ||
129 | * | ||
130 | * The full source code can be found on the examples folder | ||
131 | * on the @ref eina_array_02_c "eina_array_02.c" file. | ||
132 | */ | ||
133 | |||
134 | /** | ||
135 | * @page eina_array_02_c Basic array usage example | ||
136 | * | ||
137 | * @include eina_array_02.c | ||
138 | * @example eina_array_02.c | ||
139 | */ | ||
140 | |||
141 | /** | ||
142 | * @addtogroup Eina_Array_Group Array | ||
143 | * | ||
144 | * @brief These functions provide array management. | ||
145 | * | ||
146 | * The Array data type in Eina is designed to have very fast access to | ||
147 | * its data (compared to the Eina @ref Eina_List_Group). On the other hand, | ||
148 | * data can be added or removed only at the end of the array. To insert | ||
149 | * data at any place, the Eina @ref Eina_List_Group is the correct container | ||
150 | * to use. | ||
151 | * | ||
152 | * To use the array data type, eina_init() must be called before any | ||
153 | * other array functions. When no more eina array functions are used, | ||
154 | * eina_shutdown() must be called to free all the resources. | ||
155 | * | ||
156 | * An array must be created with eina_array_new(). It allocates all | ||
157 | * the necessary data for an array. When not needed anymore, an array | ||
158 | * is freed with eina_array_free(). This function does not free any | ||
159 | * allocated memory used to store the data of each element. For that, | ||
160 | * just iterate over the array to free them. A convenient way to do | ||
161 | * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given | ||
162 | * in the description of this macro. | ||
163 | * | ||
164 | * @warning Functions do not check if the used array is valid or not. It's up to | ||
165 | * the user to be sure of that. It is designed like that for performance | ||
166 | * reasons. | ||
167 | * | ||
168 | * The usual features of an array are classic ones: to append an | ||
169 | * element, use eina_array_push() and to remove the last element, use | ||
170 | * eina_array_pop(). To retrieve the element at a given position, use | ||
171 | * eina_array_data_get(). The number of elements can be retrieved with | ||
172 | * eina_array_count_get(). | ||
173 | * | ||
174 | * Eina_Array is different from a conventional C array in a number of ways, most | ||
175 | * importantly they grow and shrink dynamically, this means that if you add an | ||
176 | * element to a full array it grows and that when you remove an element from an | ||
177 | * array it @b may shrink. | ||
178 | * | ||
179 | * When the array needs to grow it allocates memory not just for the element | ||
180 | * currently being added since that would mean allocating memory(which is | ||
181 | * computationally expensive) often, instead it grows to be able to hold @p step | ||
182 | * more elements. Similarly if you remove elements in such a way that that the | ||
183 | * array is left holding its capacity - @p step elements it will shrink. | ||
184 | * | ||
185 | * The following image illustrates how an Eina_Array grows: | ||
186 | * | ||
187 | * @image html eina_array-growth.png | ||
188 | * @image latex eina_array-growth.eps width=\textwidth | ||
189 | * | ||
190 | * Eina_Array only stores pointers but it can store data of any type in the form | ||
191 | * of void pointers. | ||
192 | * | ||
193 | * See here some examples: | ||
194 | * @li @ref array_01_example_page | ||
195 | * @li @ref array_02_example_page | ||
196 | */ | ||
197 | |||
198 | /** | ||
199 | * @addtogroup Eina_Data_Types_Group Data Types | ||
200 | * | ||
201 | * @{ | ||
202 | */ | ||
203 | |||
204 | /** | ||
205 | * @addtogroup Eina_Containers_Group Containers | ||
206 | * | ||
207 | * @{ | ||
208 | */ | ||
209 | |||
210 | /** | ||
211 | * @defgroup Eina_Array_Group Array | ||
212 | * | ||
213 | * @{ | ||
214 | */ | ||
215 | |||
216 | /** | ||
217 | * @typedef Eina_Array | ||
218 | * Type for a generic vector. | ||
219 | */ | ||
220 | typedef struct _Eina_Array Eina_Array; | ||
221 | |||
222 | /** | ||
223 | * @typedef Eina_Array_Iterator | ||
224 | * Type for an iterator on arrays, used with #EINA_ARRAY_ITER_NEXT. | ||
225 | */ | ||
226 | typedef void **Eina_Array_Iterator; | ||
227 | |||
228 | /** | ||
229 | * @struct _Eina_Array | ||
230 | * Type for an array of data. | ||
231 | */ | ||
232 | struct _Eina_Array | ||
233 | { | ||
234 | #define EINA_ARRAY_VERSION 1 | ||
235 | int version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */ | ||
236 | |||
237 | void **data; /**< Pointer to a vector of pointer to payload */ | ||
238 | unsigned int total; /**< Total number of slots in the vector */ | ||
239 | unsigned int count; /**< Number of active slots in the vector */ | ||
240 | unsigned int step; /**< How much must we grow the vector when it is full */ | ||
241 | EINA_MAGIC | ||
242 | }; | ||
243 | |||
244 | |||
245 | /** | ||
246 | * @brief Create a new array. | ||
247 | * | ||
248 | * @param step The count of pointers to add when increasing the array size. | ||
249 | * @return @c NULL on failure, non @c NULL otherwise. | ||
250 | * | ||
251 | * This function creates a new array. When adding an element, the array | ||
252 | * allocates @p step elements. When that buffer is full, then adding | ||
253 | * another element will increase the buffer by @p step elements again. | ||
254 | * | ||
255 | * This function return a valid array on success, or @c NULL if memory | ||
256 | * allocation fails. In that case, the error is set to | ||
257 | * #EINA_ERROR_OUT_OF_MEMORY. | ||
258 | */ | ||
259 | EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
260 | |||
261 | /** | ||
262 | * @brief Free an array. | ||
263 | * | ||
264 | * @param array The array to free. | ||
265 | * | ||
266 | * This function frees @p array. It calls first eina_array_flush() then | ||
267 | * free the memory of the pointer. It does not free the memory | ||
268 | * allocated for the elements of @p array. To free them, use | ||
269 | * #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check | ||
270 | * of @p array. | ||
271 | */ | ||
272 | EAPI void eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1); | ||
273 | |||
274 | /** | ||
275 | * @brief Set the step of an array. | ||
276 | * | ||
277 | * @param array The array. | ||
278 | * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array). | ||
279 | * @param step The count of pointers to add when increasing the array size. | ||
280 | * | ||
281 | * This function sets the step of @p array to @p step. For performance | ||
282 | * reasons, there is no check of @p array. If it is @c NULL or | ||
283 | * invalid, the program may crash. | ||
284 | * | ||
285 | * @warning This function can @b only be called on uninitialized arrays. | ||
286 | */ | ||
287 | EAPI void eina_array_step_set(Eina_Array *array, | ||
288 | unsigned int sizeof_eina_array, | ||
289 | unsigned int step) EINA_ARG_NONNULL(1); | ||
290 | /** | ||
291 | * @brief Clean an array. | ||
292 | * | ||
293 | * @param array The array to clean. | ||
294 | * | ||
295 | * This function sets the count member of @p array to 0, however it doesn't free | ||
296 | * any space. This is particularly useful if you need to empty the array and | ||
297 | * add lots of elements quickly. For performance reasons, there is no check of | ||
298 | * @p array. If it is @c NULL or invalid, the program may crash. | ||
299 | */ | ||
300 | static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1); | ||
301 | |||
302 | /** | ||
303 | * @brief Flush an array. | ||
304 | * | ||
305 | * @param array The array to flush. | ||
306 | * | ||
307 | * This function sets the count and total members of @p array to 0, | ||
308 | * frees and set to NULL its data member. For performance reasons, | ||
309 | * there is no check of @p array. If it is @c NULL or invalid, the | ||
310 | * program may crash. | ||
311 | */ | ||
312 | EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1); | ||
313 | |||
314 | /** | ||
315 | * @brief Rebuild an array by specifying the data to keep. | ||
316 | * | ||
317 | * @param array The array. | ||
318 | * @param keep The functions which selects the data to keep. | ||
319 | * @param gdata The data to pass to the function keep. | ||
320 | * @return #EINA_TRUE on success, #EINA_FALSE oterwise. | ||
321 | * | ||
322 | * This function rebuilds @p array be specifying the elements to keep with the | ||
323 | * function @p keep. No empty/invalid fields are left in the array. @p gdata is | ||
324 | * an additional data to pass to @p keep. For performance reasons, there is no | ||
325 | * check of @p array. If it is @c NULL or invalid, the program may crash. | ||
326 | * | ||
327 | * If it wasn't able to remove items due to an allocation failure, it will | ||
328 | * return #EINA_FALSE and the error is set to #EINA_ERROR_OUT_OF_MEMORY. | ||
329 | */ | ||
330 | EAPI Eina_Bool eina_array_remove(Eina_Array * array, | ||
331 | Eina_Bool (*keep)(void *data, void *gdata), | ||
332 | void *gdata) EINA_ARG_NONNULL(1, 2); | ||
333 | static inline Eina_Bool eina_array_push(Eina_Array *array, | ||
334 | const void *data) EINA_ARG_NONNULL(1, 2); | ||
335 | static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1); | ||
336 | static inline void *eina_array_data_get(const Eina_Array *array, | ||
337 | unsigned int idx) EINA_ARG_NONNULL(1); | ||
338 | /** | ||
339 | * @brief Set the data at a given position in an array. | ||
340 | * | ||
341 | * @param array The array. | ||
342 | * @param idx The potition of the data to set. | ||
343 | * @param data The data to set. | ||
344 | * | ||
345 | * This function sets the data at the position @p idx in @p | ||
346 | * array to @p data, this effectively replaces the previously held data, you | ||
347 | * must therefore get a pointer to it first if you need to free it. For | ||
348 | * performance reasons, there is no check of @p array or @p idx. If it is @c | ||
349 | * NULL or invalid, the program may crash. | ||
350 | */ | ||
351 | static inline void eina_array_data_set(const Eina_Array *array, | ||
352 | unsigned int idx, | ||
353 | const void *data) EINA_ARG_NONNULL(1); | ||
354 | static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1); | ||
355 | |||
356 | /** | ||
357 | * @brief Returned a new iterator associated to an array. | ||
358 | * | ||
359 | * @param array The array. | ||
360 | * @return A new iterator. | ||
361 | * | ||
362 | * This function returns a newly allocated iterator associated to | ||
363 | * @p array. If @p array is @c NULL or the count member of @p array is | ||
364 | * less or equal than 0, this function returns NULL. If the memory can | ||
365 | * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | ||
366 | * set. Otherwise, a valid iterator is returned. | ||
367 | */ | ||
368 | EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
369 | |||
370 | /** | ||
371 | * @brief Returned a new accessor associated to an array. | ||
372 | * | ||
373 | * @param array The array. | ||
374 | * @return A new accessor. | ||
375 | * | ||
376 | * This function returns a newly allocated accessor associated to | ||
377 | * @p array. If @p array is @c NULL or the count member of @p array is | ||
378 | * less or equal than 0, this function returns NULL. If the memory can | ||
379 | * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | ||
380 | * set. Otherwise, a valid accessor is returned. | ||
381 | */ | ||
382 | EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
383 | /** | ||
384 | * @brief Provide a safe way to iterate over an array | ||
385 | * | ||
386 | * @param array The array to iterate over. | ||
387 | * @param cb The callback to call for each item. | ||
388 | * @param fdata The user data to pass to the callback. | ||
389 | * @return EINA_TRUE if it successfully iterate all items of the array. | ||
390 | * | ||
391 | * This function provide a safe way to iterate over an array. @p cb should | ||
392 | * return EINA_TRUE as long as you want the function to continue iterating, | ||
393 | * by returning EINA_FALSE it will stop and return EINA_FALSE as a result. | ||
394 | */ | ||
395 | static inline Eina_Bool eina_array_foreach(Eina_Array *array, | ||
396 | Eina_Each_Cb cb, | ||
397 | void *data); | ||
398 | /** | ||
399 | * @def EINA_ARRAY_ITER_NEXT | ||
400 | * @brief Macro to iterate over an array easily. | ||
401 | * | ||
402 | * @param array The array to iterate over. | ||
403 | * @param index The integer number that is increased while itareting. | ||
404 | * @param item The data | ||
405 | * @param iterator The iterator | ||
406 | * | ||
407 | * This macro allows the iteration over @p array in an easy way. It | ||
408 | * iterates from the first element to the last one. @p index is an | ||
409 | * integer that increases from 0 to the number of elements. @p item is | ||
410 | * the data of each element of @p array, so it is a pointer to a type | ||
411 | * chosen by the user. @p iterator is of type #Eina_Array_Iterator. | ||
412 | * | ||
413 | * This macro can be used for freeing the data of an array, like in | ||
414 | * the following example: | ||
415 | * | ||
416 | * @code | ||
417 | * Eina_Array *array; | ||
418 | * char *item; | ||
419 | * Eina_Array_Iterator iterator; | ||
420 | * unsigned int i; | ||
421 | * | ||
422 | * // array is already filled, | ||
423 | * // its elements are just duplicated strings, | ||
424 | * // EINA_ARRAY_ITER_NEXT will be used to free those strings | ||
425 | * | ||
426 | * EINA_ARRAY_ITER_NEXT(array, i, item, iterator) | ||
427 | * free(item); | ||
428 | * @endcode | ||
429 | */ | ||
430 | #define EINA_ARRAY_ITER_NEXT(array, index, item, iterator) \ | ||
431 | for (index = 0, iterator = (array)->data; \ | ||
432 | (index < eina_array_count_get(array)) && ((item = *((iterator)++))); \ | ||
433 | ++(index)) | ||
434 | |||
435 | #include "eina_inline_array.x" | ||
436 | |||
437 | /** | ||
438 | * @} | ||
439 | */ | ||
440 | |||
441 | /** | ||
442 | * @} | ||
443 | */ | ||
444 | |||
445 | /** | ||
446 | * @} | ||
447 | */ | ||
448 | |||
449 | #endif | ||