diff options
Diffstat (limited to 'libraries/eina/src/include/eina_inarray.h')
-rw-r--r-- | libraries/eina/src/include/eina_inarray.h | 710 |
1 files changed, 0 insertions, 710 deletions
diff --git a/libraries/eina/src/include/eina_inarray.h b/libraries/eina/src/include/eina_inarray.h deleted file mode 100644 index 079f1e3..0000000 --- a/libraries/eina/src/include/eina_inarray.h +++ /dev/null | |||
@@ -1,710 +0,0 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2012 ProFUSION embedded systems | ||
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_INARRAY_H_ | ||
20 | #define EINA_INARRAY_H_ | ||
21 | |||
22 | #include "eina_types.h" | ||
23 | #include "eina_iterator.h" | ||
24 | #include "eina_accessor.h" | ||
25 | |||
26 | /** | ||
27 | * @page eina_inarray_example_01 Eina inline array usage | ||
28 | * @dontinclude eina_inarray_01.c | ||
29 | * | ||
30 | * This example will create an inline array of chars, add some elements, print | ||
31 | * it, re-purpose the array to store ints, add some elements and print that. | ||
32 | * | ||
33 | * We'll start with a function to compare ints we need this because the '>' | ||
34 | * operator is not a function and can't be used where Eina_Compare_Cb is needed. | ||
35 | * @skip int | ||
36 | * @until } | ||
37 | * | ||
38 | * And then move on to the code we actually care about, starting with variable | ||
39 | * declarations and eina initialization: | ||
40 | * @until eina_init | ||
41 | * | ||
42 | * Creating an inline array is very simple, we just need to know what type we | ||
43 | * want to store: | ||
44 | * @until inarray_new | ||
45 | * @note The second parameter(the step) is left at zero which means that eina | ||
46 | * will choose an appropriate value, this should @b only be changed if it's | ||
47 | * known, beforehand, how many elements the array will have. | ||
48 | * | ||
49 | * Once we have an array we can start adding elements to it. Because the | ||
50 | * insertion function expect a memory address we have to put the value we want | ||
51 | * to store in a variable(this should be no problem since in real world usage | ||
52 | * that's usually where the value will be anyways): | ||
53 | * @until append | ||
54 | * @note Because the inline array copies the value given to it we can later | ||
55 | * change @c ch, which we do, without affecting the contents of the array. | ||
56 | * | ||
57 | * So let's add some more elements: | ||
58 | * @until append | ||
59 | * @until append | ||
60 | * @until append | ||
61 | * | ||
62 | * We will then iterate over our array and print every position of it. The thing | ||
63 | * to note here is not so much the values which will be the expected 'a', 'b', | ||
64 | * 'c' and 'd', but rather the memory address of these values, they are | ||
65 | * sequential: | ||
66 | * @until printf | ||
67 | * @until printf | ||
68 | * | ||
69 | * We'll now use our array to store ints, so we need to first erase every member | ||
70 | * currently on the array: | ||
71 | * @until _flush | ||
72 | * | ||
73 | * And then to be able to store a different type on the same array we use the | ||
74 | * eina_array_setup() function, which is just like the eina_inarray_new() | ||
75 | * function except it receives already allocated memory. This time we're going | ||
76 | * to ask eina to use a step of size 4 because that's how many elements we'll be | ||
77 | * putting on the array: | ||
78 | * @until _setup | ||
79 | * @note Strictly speaking the reason to call eina_inarray_setup() is not | ||
80 | * because we're storing different type, but rather because our types have | ||
81 | * different sizes. Eina inline arrays don't actually know anything about types, | ||
82 | * they only deal in blocks of memory of a given size. | ||
83 | * @note Since eina_array_setup() receives already allocated memory you can(and | ||
84 | * it is in fact good practice) use inline arrays not declared as pointers: | ||
85 | * @code | ||
86 | * Eina_Inarray arr; | ||
87 | * eina_inarray_setup(&arr, sizeof(int), 4); | ||
88 | * @endcode | ||
89 | * | ||
90 | * And now to add our integer values to the array: | ||
91 | * @until append | ||
92 | * @until append | ||
93 | * @until append | ||
94 | * | ||
95 | * Just to change things up a bit we've left out the 99 value, but will still | ||
96 | * add it in such a way to keep the array ordered. There are many ways to do | ||
97 | * this, we could use eina_inarray_insert_at(), or we could change the value | ||
98 | * of the last member using eina_inarray_replace_at() and then append the values | ||
99 | * in the right order, but for no particular reason we're going to use | ||
100 | * eina_inarray_insert_sorted() instead: | ||
101 | * @until insert_sorted | ||
102 | * | ||
103 | * We then print the size of our array, and the array itself, much like last | ||
104 | * time the values are not surprising, and neither should it be that the memory | ||
105 | * addresses are contiguous: | ||
106 | * @until printf | ||
107 | * @until printf | ||
108 | * | ||
109 | * Once done we free our array and shutdown eina: | ||
110 | * @until } | ||
111 | * | ||
112 | * The source for this example: @ref eina_inarray_01_c | ||
113 | */ | ||
114 | |||
115 | /** | ||
116 | * @page eina_inarray_01_c eina_inarray_01.c | ||
117 | * @include eina_inarray_01.c | ||
118 | * @example eina_inarray_01.c | ||
119 | */ | ||
120 | |||
121 | /** | ||
122 | * @page eina_inarray_example_02 Eina inline array of strings | ||
123 | * @dontinclude eina_inarray_02.c | ||
124 | * | ||
125 | * This example will create an inline array of strings, add some elements and | ||
126 | * then print them. This example is based on @ref eina_array_01_example_page and | ||
127 | * @ref eina_inarray_example_01. | ||
128 | * | ||
129 | * We start with some variable declarations and eina initialization: | ||
130 | * @skip int | ||
131 | * @until eina_init | ||
132 | * | ||
133 | * We then create the array much like we did on @ref eina_inarray_example_01: | ||
134 | * @until inarray_new | ||
135 | * | ||
136 | * The point were this example significantly differs from the first eina inline | ||
137 | * array example. We'll not be adding the strings themselves to the array since | ||
138 | * their size varies, we'll store pointer to the strings instead. We therefore | ||
139 | * use @c char** to populate our inline array: | ||
140 | * @until } | ||
141 | * | ||
142 | * The source for this example: @ref eina_inarray_02_c | ||
143 | */ | ||
144 | |||
145 | /** | ||
146 | * @page eina_inarray_02_c eina_inarray_02.c | ||
147 | * @include eina_inarray_02.c | ||
148 | * @example eina_inarray_02.c | ||
149 | */ | ||
150 | |||
151 | /** | ||
152 | * @addtogroup Eina_Data_Types_Group Data Types | ||
153 | * | ||
154 | * @since 1.2 | ||
155 | * | ||
156 | * @{ | ||
157 | */ | ||
158 | |||
159 | /** | ||
160 | * @addtogroup Eina_Containers_Group Containers | ||
161 | * | ||
162 | * @{ | ||
163 | */ | ||
164 | |||
165 | /** | ||
166 | * @defgroup Eina_Inline_Array_Group Inline Array | ||
167 | * | ||
168 | * Inline array is a container that stores the data itself not pointers to data, | ||
169 | * this means there is no memory fragmentation, also for small data types(such | ||
170 | * as char, short, int, etc.) it's more memory efficient. | ||
171 | * | ||
172 | * Usage of the inline array is very similar to that of other | ||
173 | * @ref Eina_Containers_Group, like all arrays adding elements to the beginning | ||
174 | * of the array is a lot more costly than appending, so those operations should | ||
175 | * be minimized. | ||
176 | * | ||
177 | * Examples: | ||
178 | * @li @ref eina_inarray_example_01 | ||
179 | * @li @ref eina_inarray_example_02 | ||
180 | * | ||
181 | * @{ | ||
182 | */ | ||
183 | |||
184 | |||
185 | /** | ||
186 | * @typedef Eina_Inarray | ||
187 | * Inlined array type. | ||
188 | * | ||
189 | * @since 1.2 | ||
190 | */ | ||
191 | typedef struct _Eina_Inarray Eina_Inarray; | ||
192 | |||
193 | /** | ||
194 | * Inline array structure, use #Eina_Inarray typedef instead. | ||
195 | * | ||
196 | * Do not modify these fields directly, use eina_inarray_setup() or | ||
197 | * eina_inarray_new() instead. | ||
198 | * | ||
199 | * @since 1.2 | ||
200 | */ | ||
201 | struct _Eina_Inarray | ||
202 | { | ||
203 | unsigned int member_size; /**< byte size of each entry in members */ | ||
204 | unsigned int len; /**< number of elements used in members */ | ||
205 | unsigned int max; /**< number of elements allocated in members */ | ||
206 | unsigned int step; /**< amount to grow number of members allocated */ | ||
207 | void *members; /**< actual array of elements */ | ||
208 | EINA_MAGIC | ||
209 | }; | ||
210 | |||
211 | /** | ||
212 | * @brief Create new inline array. | ||
213 | * | ||
214 | * @param member_size size of each member in the array. | ||
215 | * @param step when resizing the array, do this using the following | ||
216 | * extra amount. | ||
217 | * @return The new inline array table or @c NULL on failure. | ||
218 | * | ||
219 | * Create a new array where members are inlined in a sequence. Each | ||
220 | * member has @a member_size bytes. | ||
221 | * | ||
222 | * If the @a step is 0, then a safe default is chosen. | ||
223 | * | ||
224 | * On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | ||
225 | * set. If @a member_size is zero, then @c NULL is returned. | ||
226 | * | ||
227 | * @see eina_inarray_free() | ||
228 | * | ||
229 | * @since 1.2 | ||
230 | */ | ||
231 | EAPI Eina_Inarray *eina_inarray_new(unsigned int member_size, | ||
232 | unsigned int step) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | ||
233 | |||
234 | /** | ||
235 | * @brief Free array and its members. | ||
236 | * @param array array object | ||
237 | * | ||
238 | * @see eina_inarray_flush() | ||
239 | * | ||
240 | * @since 1.2 | ||
241 | */ | ||
242 | EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1); | ||
243 | |||
244 | /** | ||
245 | * @brief Initialize inline array. | ||
246 | * @param array array object to initialize. | ||
247 | * @param member_size size of each member in the array. | ||
248 | * @param step when resizing the array, do this using the following | ||
249 | * extra amount. | ||
250 | * | ||
251 | * Initialize array. If the @a step is 0, then a safe default is | ||
252 | * chosen. | ||
253 | * | ||
254 | * This is useful for arrays inlined into other structures or | ||
255 | * allocated at stack. | ||
256 | * | ||
257 | * @see eina_inarray_flush() | ||
258 | * | ||
259 | * @since 1.2 | ||
260 | */ | ||
261 | EAPI void eina_inarray_setup(Eina_Inarray *array, | ||
262 | unsigned int member_size, | ||
263 | unsigned int step) EINA_ARG_NONNULL(1); | ||
264 | |||
265 | /** | ||
266 | * @brief Remove every member from array. | ||
267 | * @param array array object | ||
268 | * | ||
269 | * @since 1.2 | ||
270 | */ | ||
271 | EAPI void eina_inarray_flush(Eina_Inarray *array) EINA_ARG_NONNULL(1); | ||
272 | |||
273 | /** | ||
274 | * @brief Copy the data as the last member of the array. | ||
275 | * @param array array object | ||
276 | * @param data data to be copied at the end | ||
277 | * @return the index of the new member or -1 on errors. | ||
278 | * | ||
279 | * Copies the given pointer contents at the end of the array. The | ||
280 | * pointer is not referenced, instead it's contents is copied to the | ||
281 | * members array using the previously defined @c member_size. | ||
282 | * | ||
283 | * @see eina_inarray_insert_at(). | ||
284 | * | ||
285 | * @since 1.2 | ||
286 | */ | ||
287 | EAPI int eina_inarray_append(Eina_Inarray *array, | ||
288 | const void *data) EINA_ARG_NONNULL(1, 2); | ||
289 | |||
290 | /** | ||
291 | * @brief Copy the data to array at position found by comparison function | ||
292 | * @param array array object | ||
293 | * @param data data to be copied | ||
294 | * @param compare compare function | ||
295 | * @return the index of the new member or -1 on errors. | ||
296 | * | ||
297 | * Copies the given pointer contents at the array position defined by | ||
298 | * given @a compare function. The pointer is not referenced, instead | ||
299 | * it's contents is copied to the members array using the previously | ||
300 | * defined @c member_size. | ||
301 | * | ||
302 | * The data given to @a compare function are the pointer to member | ||
303 | * memory itself, do no change it. | ||
304 | * | ||
305 | * @see eina_inarray_insert_sorted() | ||
306 | * @see eina_inarray_insert_at() | ||
307 | * @see eina_inarray_append() | ||
308 | * | ||
309 | * @since 1.2 | ||
310 | */ | ||
311 | EAPI int eina_inarray_insert(Eina_Inarray *array, | ||
312 | const void *data, | ||
313 | Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3); | ||
314 | |||
315 | /** | ||
316 | * @brief Copy the data to array at position found by comparison function | ||
317 | * @param array array object | ||
318 | * @param data data to be copied | ||
319 | * @param compare compare function | ||
320 | * @return the index of the new member or -1 on errors. | ||
321 | * | ||
322 | * Copies the given pointer contents at the array position defined by | ||
323 | * given @a compare function. The pointer is not referenced, instead | ||
324 | * it's contents is copied to the members array using the previously | ||
325 | * defined @c member_size. | ||
326 | * | ||
327 | * The data given to @a compare function are the pointer to member | ||
328 | * memory itself, do no change it. | ||
329 | * | ||
330 | * This variation will optimize insertion position assuming the array | ||
331 | * is already sorted by doing binary search. | ||
332 | * | ||
333 | * @see eina_inarray_sort() | ||
334 | * | ||
335 | * @since 1.2 | ||
336 | */ | ||
337 | EAPI int eina_inarray_insert_sorted(Eina_Inarray *array, | ||
338 | const void *data, | ||
339 | Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3); | ||
340 | |||
341 | /** | ||
342 | * @brief Find data and remove matching member | ||
343 | * @param array array object | ||
344 | * @param data data to be found and removed | ||
345 | * @return the index of the removed member or -1 on errors. | ||
346 | * | ||
347 | * Find data in the array and remove it. Data may be an existing | ||
348 | * member of array (then optimized) or the contents will be matched | ||
349 | * using memcmp(). | ||
350 | * | ||
351 | * @see eina_inarray_pop() | ||
352 | * @see eina_inarray_remove_at() | ||
353 | * | ||
354 | * @since 1.2 | ||
355 | */ | ||
356 | EAPI int eina_inarray_remove(Eina_Inarray *array, | ||
357 | const void *data) EINA_ARG_NONNULL(1, 2); | ||
358 | |||
359 | /** | ||
360 | * @brief Removes the last member of the array | ||
361 | * @param array array object | ||
362 | * @return the index of the removed member or -1 on errors. | ||
363 | * | ||
364 | * @since 1.2 | ||
365 | */ | ||
366 | EAPI int eina_inarray_pop(Eina_Inarray *array) EINA_ARG_NONNULL(1); | ||
367 | |||
368 | /** | ||
369 | * @brief Get the member at given position | ||
370 | * @param array array object | ||
371 | * @param position member position | ||
372 | * @return pointer to current member memory. | ||
373 | * | ||
374 | * Gets the member given its position in the array. It is a pointer to | ||
375 | * its current memory, then it can be invalidated with functions that | ||
376 | * changes the array such as eina_inarray_append(), | ||
377 | * eina_inarray_insert_at() or eina_inarray_remove_at() or variants. | ||
378 | * | ||
379 | * See also eina_inarray_lookup() and eina_inarray_lookup_sorted(). | ||
380 | * | ||
381 | * @since 1.2 | ||
382 | */ | ||
383 | EAPI void *eina_inarray_nth(const Eina_Inarray *array, | ||
384 | unsigned int position) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
385 | |||
386 | /** | ||
387 | * @brief Copy the data at given position in the array | ||
388 | * @param array array object | ||
389 | * @param position where to insert the member | ||
390 | * @param data data to be copied at position | ||
391 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
392 | * | ||
393 | * Copies the given pointer contents at the given @a position in the | ||
394 | * array. The pointer is not referenced, instead it's contents is | ||
395 | * copied to the members array using the previously defined | ||
396 | * @c member_size. | ||
397 | * | ||
398 | * All the members from @a position to the end of the array are | ||
399 | * shifted to the end. | ||
400 | * | ||
401 | * If @a position is equal to the end of the array (equals to | ||
402 | * eina_inarray_count()), then the member is appended. | ||
403 | * | ||
404 | * If @a position is bigger than the array length, it will fail. | ||
405 | * | ||
406 | * @since 1.2 | ||
407 | */ | ||
408 | EAPI Eina_Bool eina_inarray_insert_at(Eina_Inarray *array, | ||
409 | unsigned int position, | ||
410 | const void *data) EINA_ARG_NONNULL(1, 3); | ||
411 | |||
412 | /** | ||
413 | * @brief Opens a space at given position, returning its pointer. | ||
414 | * @param array array object | ||
415 | * @param position where to insert first member (open/allocate space) | ||
416 | * @param member_count how many times member_size bytes will be allocated. | ||
417 | * @return pointer to first member memory allocated or @c NULL on errors. | ||
418 | * | ||
419 | * This is similar to eina_inarray_insert_at(), but useful if the | ||
420 | * members contents are still unknown or unallocated. It will make | ||
421 | * room for the required number of items and return the pointer to the | ||
422 | * first item, similar to malloc(member_count * member_size), with the | ||
423 | * guarantee all memory is within members array. | ||
424 | * | ||
425 | * The new member memory is undefined, it's not automatically zeroed. | ||
426 | * | ||
427 | * All the members from @a position to the end of the array are | ||
428 | * shifted to the end. | ||
429 | * | ||
430 | * If @a position is equal to the end of the array (equals to | ||
431 | * eina_inarray_count()), then the member is appended. | ||
432 | * | ||
433 | * If @a position is bigger than the array length, it will fail. | ||
434 | * | ||
435 | * @since 1.2 | ||
436 | */ | ||
437 | EAPI void *eina_inarray_alloc_at(Eina_Inarray *array, | ||
438 | unsigned int position, | ||
439 | unsigned int member_count) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
440 | |||
441 | /** | ||
442 | * @brief Copy the data over the given position. | ||
443 | * @param array array object | ||
444 | * @param position where to replace the member | ||
445 | * @param data data to be copied at position | ||
446 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
447 | * | ||
448 | * Copies the given pointer contents at the given @a position in the | ||
449 | * array. The pointer is not referenced, instead it's contents is | ||
450 | * copied to the members array using the previously defined | ||
451 | * @c member_size. | ||
452 | * | ||
453 | * If @a position does not exist, it will fail. | ||
454 | * | ||
455 | * @since 1.2 | ||
456 | */ | ||
457 | EAPI Eina_Bool eina_inarray_replace_at(Eina_Inarray *array, | ||
458 | unsigned int position, | ||
459 | const void *data) EINA_ARG_NONNULL(1, 3); | ||
460 | |||
461 | /** | ||
462 | * @brief Remove member at given position | ||
463 | * @param array array object | ||
464 | * @param position position to be removed | ||
465 | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | ||
466 | * | ||
467 | * The member is removed from array and any members after it are moved | ||
468 | * towards the array head. | ||
469 | * | ||
470 | * See also eina_inarray_pop() and eina_inarray_remove(). | ||
471 | * | ||
472 | * @since 1.2 | ||
473 | */ | ||
474 | EAPI Eina_Bool eina_inarray_remove_at(Eina_Inarray *array, | ||
475 | unsigned int position) EINA_ARG_NONNULL(1); | ||
476 | |||
477 | /** | ||
478 | * @brief Reverse members in the array. | ||
479 | * @param array array object | ||
480 | * | ||
481 | * If you do not want to change the array, just walk its elements | ||
482 | * backwards, then use EINA_INARRAY_REVERSE_FOREACH() macro. | ||
483 | * | ||
484 | * @see EINA_INARRAY_REVERSE_FOREACH() | ||
485 | * | ||
486 | * @since 1.2 | ||
487 | */ | ||
488 | EAPI void eina_inarray_reverse(Eina_Inarray *array) EINA_ARG_NONNULL(1); | ||
489 | |||
490 | /** | ||
491 | * @brief Applies quick sort to array | ||
492 | * @param array array object | ||
493 | * @param compare compare function | ||
494 | * | ||
495 | * Applies quick sort to the @a array. | ||
496 | * | ||
497 | * The data given to @a compare function are the pointer to member | ||
498 | * memory itself, do no change it. | ||
499 | * | ||
500 | * @see eina_inarray_insert_sorted() | ||
501 | * | ||
502 | * @since 1.2 | ||
503 | */ | ||
504 | EAPI void eina_inarray_sort(Eina_Inarray *array, | ||
505 | Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2); | ||
506 | |||
507 | /** | ||
508 | * @brief Search member (linear walk) | ||
509 | * @param array array object | ||
510 | * @param data member to search using @a compare function. | ||
511 | * @param compare compare function | ||
512 | * @return the member index or -1 if not found. | ||
513 | * | ||
514 | * Walks array linearly looking for given data as compared by | ||
515 | * @a compare function. | ||
516 | * | ||
517 | * The data given to @a compare function are the pointer to member | ||
518 | * memory itself, do no change it. | ||
519 | * | ||
520 | * See also eina_inarray_lookup_sorted(). | ||
521 | * | ||
522 | * @since 1.2 | ||
523 | */ | ||
524 | EAPI int eina_inarray_search(const Eina_Inarray *array, | ||
525 | const void *data, | ||
526 | Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3); | ||
527 | |||
528 | /** | ||
529 | * @brief Search member (binary search walk) | ||
530 | * @param array array object | ||
531 | * @param data member to search using @a compare function. | ||
532 | * @param compare compare function | ||
533 | * @return the member index or -1 if not found. | ||
534 | * | ||
535 | * Uses binary search for given data as compared by @a compare function. | ||
536 | * | ||
537 | * The data given to @a compare function are the pointer to member | ||
538 | * memory itself, do no change it. | ||
539 | * | ||
540 | * @since 1.2 | ||
541 | */ | ||
542 | EAPI int eina_inarray_search_sorted(const Eina_Inarray *array, | ||
543 | const void *data, | ||
544 | Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3); | ||
545 | |||
546 | /** | ||
547 | * @brief Call function for each array member | ||
548 | * @param array array object | ||
549 | * @param function callback function | ||
550 | * @param user_data user data given to callback @a function | ||
551 | * @return #EINA_TRUE if it successfully iterate all items of the array. | ||
552 | * | ||
553 | * Call @a function for every given data in @a array. | ||
554 | * | ||
555 | * Safe way to iterate over an array. @p function should return | ||
556 | * #EINA_TRUE as long as you want the function to continue iterating, | ||
557 | * by returning #EINA_FALSE it will stop and return #EINA_FALSE as a | ||
558 | * result. | ||
559 | * | ||
560 | * The data given to @a function are the pointer to member memory | ||
561 | * itself. | ||
562 | * | ||
563 | * @see EINA_INARRAY_FOREACH() | ||
564 | * | ||
565 | * @since 1.2 | ||
566 | */ | ||
567 | EAPI Eina_Bool eina_inarray_foreach(const Eina_Inarray *array, | ||
568 | Eina_Each_Cb function, | ||
569 | const void *user_data) EINA_ARG_NONNULL(1, 2); | ||
570 | |||
571 | /** | ||
572 | * @brief Remove all members that matched. | ||
573 | * @param array array object | ||
574 | * @param match match function | ||
575 | * @param user_data user data given to callback @a match. | ||
576 | * @return number of removed entries or -1 on error. | ||
577 | * | ||
578 | * Remove all entries in the @a array where @a match function | ||
579 | * returns #EINA_TRUE. | ||
580 | * | ||
581 | * @since 1.2 | ||
582 | */ | ||
583 | EAPI int eina_inarray_foreach_remove(Eina_Inarray *array, | ||
584 | Eina_Each_Cb match, | ||
585 | const void *user_data) EINA_ARG_NONNULL(1, 2); | ||
586 | |||
587 | /** | ||
588 | * @brief number of members in array. | ||
589 | * @param array array object | ||
590 | * @return number of members in array. | ||
591 | * | ||
592 | * @since 1.2 | ||
593 | */ | ||
594 | EAPI unsigned int eina_inarray_count(const Eina_Inarray *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | ||
595 | |||
596 | /** | ||
597 | * @brief Returned a new iterator associated to an array. | ||
598 | * @param array array object | ||
599 | * @return A new iterator. | ||
600 | * | ||
601 | * This function returns a newly allocated iterator associated to | ||
602 | * @p array. | ||
603 | * | ||
604 | * If the memory can not be allocated, NULL is returned and | ||
605 | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | ||
606 | * returned. | ||
607 | * | ||
608 | * @warning if the array structure changes then the iterator becomes | ||
609 | * invalid! That is, if you add or remove members this | ||
610 | * iterator behavior is undefined and your program may crash! | ||
611 | * | ||
612 | * @since 1.2 | ||
613 | */ | ||
614 | EAPI Eina_Iterator *eina_inarray_iterator_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | ||
615 | |||
616 | /** | ||
617 | * @brief Returned a new reversed iterator associated to an array. | ||
618 | * @param array array object | ||
619 | * @return A new iterator. | ||
620 | * | ||
621 | * This function returns a newly allocated iterator associated to | ||
622 | * @p array. | ||
623 | * | ||
624 | * Unlike eina_inarray_iterator_new(), this will walk the array backwards. | ||
625 | * | ||
626 | * If the memory can not be allocated, NULL is returned and | ||
627 | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | ||
628 | * returned. | ||
629 | * | ||
630 | * @warning if the array structure changes then the iterator becomes | ||
631 | * invalid! That is, if you add or remove nodes this iterator | ||
632 | * behavior is undefined and your program may crash! | ||
633 | * | ||
634 | * @since 1.2 | ||
635 | */ | ||
636 | EAPI Eina_Iterator *eina_inarray_iterator_reversed_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | ||
637 | |||
638 | /** | ||
639 | * @brief Returned a new accessor associated to an array. | ||
640 | * @param array array object | ||
641 | * @return A new accessor. | ||
642 | * | ||
643 | * This function returns a newly allocated accessor associated to | ||
644 | * @p array. | ||
645 | * | ||
646 | * If the memory can not be allocated, NULL is returned and | ||
647 | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid accessor is | ||
648 | * returned. | ||
649 | * | ||
650 | * @since 1.2 | ||
651 | */ | ||
652 | EAPI Eina_Accessor *eina_inarray_accessor_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | ||
653 | |||
654 | /** | ||
655 | * @def EINA_INARRAY_FOREACH | ||
656 | * @brief walks array linearly from head to tail | ||
657 | * @param array array object | ||
658 | * @param itr the iterator pointer | ||
659 | * | ||
660 | * @a itr must be a pointer with sizeof(itr*) == array->member_size. | ||
661 | * | ||
662 | * @warning This is fast as it does direct pointer access, but it will | ||
663 | * not check for @c NULL pointers or invalid array object! | ||
664 | * See eina_inarray_foreach() to do that. | ||
665 | * | ||
666 | * @warning Do not modify array as you walk it! If that is desired, | ||
667 | * then use eina_inarray_foreach_remove() | ||
668 | * | ||
669 | * @since 1.2 | ||
670 | */ | ||
671 | #define EINA_INARRAY_FOREACH(array, itr) \ | ||
672 | for ((itr) = (array)->members; \ | ||
673 | (itr) < (((typeof(*itr)*)(array)->members) + (array)->len); \ | ||
674 | (itr)++) | ||
675 | |||
676 | /** | ||
677 | * @def EINA_INARRAY_REVERSE_FOREACH | ||
678 | * @brief walks array linearly from tail to head | ||
679 | * @param array array object | ||
680 | * @param itr the iterator pointer | ||
681 | * | ||
682 | * @a itr must be a pointer with sizeof(itr*) == array->member_size. | ||
683 | * | ||
684 | * @warning This is fast as it does direct pointer access, but it will | ||
685 | * not check for @c NULL pointers or invalid array object! | ||
686 | * | ||
687 | * @warning Do not modify array as you walk it! If that is desired, | ||
688 | * then use eina_inarray_foreach_remove() | ||
689 | * | ||
690 | * @since 1.2 | ||
691 | */ | ||
692 | #define EINA_INARRAY_REVERSE_FOREACH(array, itr) \ | ||
693 | for ((itr) = ((((typeof(*(itr))*)(array)->members) + (array)->len) - 1); \ | ||
694 | (((itr) >= (typeof(*(itr))*)(array)->members) \ | ||
695 | && ((array)->members != NULL)); \ | ||
696 | (itr)--) | ||
697 | |||
698 | /** | ||
699 | * @} | ||
700 | */ | ||
701 | |||
702 | /** | ||
703 | * @} | ||
704 | */ | ||
705 | |||
706 | /** | ||
707 | * @} | ||
708 | */ | ||
709 | |||
710 | #endif /*EINA_INARRAY_H_*/ | ||