aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_inarray.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_inarray.h')
-rw-r--r--libraries/eina/src/include/eina_inarray.h710
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 */
191typedef 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 */
201struct _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 */
231EAPI 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 */
242EAPI 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 */
261EAPI 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 */
271EAPI 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 */
287EAPI 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 */
311EAPI 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 */
337EAPI 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 */
356EAPI 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 */
366EAPI 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 */
383EAPI 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 */
408EAPI 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 */
437EAPI 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 */
457EAPI 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 */
474EAPI 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 */
488EAPI 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 */
504EAPI 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 */
524EAPI 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 */
542EAPI 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 */
567EAPI 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 */
583EAPI 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 */
594EAPI 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 */
614EAPI 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 */
636EAPI 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 */
652EAPI 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_*/