aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_array.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_array.h')
-rw-r--r--libraries/eina/src/include/eina_array.h450
1 files changed, 0 insertions, 450 deletions
diff --git a/libraries/eina/src/include/eina_array.h b/libraries/eina/src/include/eina_array.h
deleted file mode 100644
index 4ab3b50..0000000
--- a/libraries/eina/src/include/eina_array.h
+++ /dev/null
@@ -1,450 +0,0 @@
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 eina_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 eina_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().
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 eina_array_01_example_page
195 * @li @ref eina_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 */
220typedef 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 */
226typedef void **Eina_Array_Iterator;
227
228/**
229 * @struct _Eina_Array
230 * Type for an array of data.
231 */
232struct _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 */
259EAPI 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 */
272EAPI 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 */
287EAPI 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 */
300static 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 */
312EAPI 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 */
330EAPI Eina_Bool eina_array_remove(Eina_Array * array,
331 Eina_Bool (*keep)(void *data, void *gdata),
332 void *gdata) EINA_ARG_NONNULL(1, 2);
333static inline Eina_Bool eina_array_push(Eina_Array *array,
334 const void *data) EINA_ARG_NONNULL(1, 2);
335static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
336static 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*/
351static inline void eina_array_data_set(const Eina_Array *array,
352 unsigned int idx,
353 const void *data) EINA_ARG_NONNULL(1);
354static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
355static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
356
357/**
358 * @brief Returned a new iterator associated to an array.
359 *
360 * @param array The array.
361 * @return A new iterator.
362 *
363 * This function returns a newly allocated iterator associated to
364 * @p array. If @p array is @c NULL or the count member of @p array is
365 * less or equal than 0, this function returns NULL. If the memory can
366 * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
367 * set. Otherwise, a valid iterator is returned.
368 */
369EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
370
371/**
372 * @brief Returned a new accessor associated to an array.
373 *
374 * @param array The array.
375 * @return A new accessor.
376 *
377 * This function returns a newly allocated accessor associated to
378 * @p array. If @p array is @c NULL or the count member of @p array is
379 * less or equal than 0, this function returns NULL. If the memory can
380 * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
381 * set. Otherwise, a valid accessor is returned.
382 */
383EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
384/**
385 * @brief Provide a safe way to iterate over an array
386 *
387 * @param array The array to iterate over.
388 * @param cb The callback to call for each item.
389 * @param fdata The user data to pass to the callback.
390 * @return EINA_TRUE if it successfully iterate all items of the array.
391 *
392 * This function provide a safe way to iterate over an array. @p cb should
393 * return EINA_TRUE as long as you want the function to continue iterating,
394 * by returning EINA_FALSE it will stop and return EINA_FALSE as a result.
395 */
396static inline Eina_Bool eina_array_foreach(Eina_Array *array,
397 Eina_Each_Cb cb,
398 void *fdata);
399/**
400 * @def EINA_ARRAY_ITER_NEXT
401 * @brief Macro to iterate over an array easily.
402 *
403 * @param array The array to iterate over.
404 * @param index The integer number that is increased while itareting.
405 * @param item The data
406 * @param iterator The iterator
407 *
408 * This macro allows the iteration over @p array in an easy way. It
409 * iterates from the first element to the last one. @p index is an
410 * integer that increases from 0 to the number of elements. @p item is
411 * the data of each element of @p array, so it is a pointer to a type
412 * chosen by the user. @p iterator is of type #Eina_Array_Iterator.
413 *
414 * This macro can be used for freeing the data of an array, like in
415 * the following example:
416 *
417 * @code
418 * Eina_Array *array;
419 * char *item;
420 * Eina_Array_Iterator iterator;
421 * unsigned int i;
422 *
423 * // array is already filled,
424 * // its elements are just duplicated strings,
425 * // EINA_ARRAY_ITER_NEXT will be used to free those strings
426 *
427 * EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
428 * free(item);
429 * @endcode
430 */
431#define EINA_ARRAY_ITER_NEXT(array, index, item, iterator) \
432 for (index = 0, iterator = (array)->data; \
433 (index < eina_array_count(array)) && ((item = *((iterator)++))); \
434 ++(index))
435
436#include "eina_inline_array.x"
437
438/**
439 * @}
440 */
441
442/**
443 * @}
444 */
445
446/**
447 * @}
448 */
449
450#endif