10 * A dynamically growing array, there exist two typical ways to use it:
12 * 1. To hold pointers to externally allocated memory regions.
14 * Use `array_init` for initialization, an element has the size of a
15 * pointer. Use the functions suffixed with ``_ptr`` to manage your
16 * pointers. The cleanup function `array_release_full` must only be
17 * used with this type of array.
19 * 2. To hold arbitrary sized objects.
21 * Use `array_init_sized` to specify the size of a single element.
22 * Use the regular (i.e. without the ``_ptr`` suffix) functions to
23 * manage your objects. Functions like `array_add` and `array_set`
24 * will copy the object into the array, `array_get` will return a
25 * pointer to the object stored within the array.
27 /** A dynamically growing array. */
29 char *items
; /** Data pointer, NULL if empty. */
30 size_t elem_size
; /** Size of one array element. */
31 size_t len
; /** Number of currently stored items. */
32 size_t count
; /** Maximal capacity of the array. */
36 * Initalize an Array object to store pointers.
38 * .. note:: Is equivalent to ``array_init_sized(arr, sizeof(void*))``.
41 void array_init(Array
*);
43 * Initalize an Array object to store arbitrarily sized objects.
45 void array_init_sized(Array
*, size_t elem_size
);
46 /** Release storage space. Reinitializes Array object. */
47 void array_release(Array
*);
49 * Release storage space and call `free(3)` for each stored pointer.
51 * .. warning:: Assumes array elements to be pointers.
54 void array_release_full(Array
*);
55 /** Empty array, keep allocated memory. */
56 void array_clear(Array
*);
57 /** Reserve memory to store at least ``count`` elements. */
58 bool array_reserve(Array
*, size_t count
);
62 * .. warning:: Returns a pointer to the allocated array region.
63 * Operations which might cause reallocations (e.g. the insertion
64 * of new elements) might invalidate the pointer.
67 void *array_get(Array
*, size_t idx
);
71 * .. note:: Copies the ``item`` into the Array. If ``item`` is ``NULL``
72 * the corresponding memory region will be cleared.
75 bool array_set(Array
*, size_t idx
, void *item
);
76 /** Dereference pointer stored in array element. */
77 void *array_get_ptr(Array
*, size_t idx
);
78 /** Store the address to which ``item`` points to into the array. */
79 bool array_set_ptr(Array
*, size_t idx
, void *item
);
80 /** Add element to the end of the array. */
81 bool array_add(Array
*, void *item
);
82 /** Add pointer to the end of the array. */
83 bool array_add_ptr(Array
*, void *item
);
85 * Remove an element by index.
87 * .. note:: Might not shrink underlying memory region.
90 bool array_remove(Array
*, size_t idx
);
91 /** Number of elements currently stored in the array. */
92 size_t array_length(Array
*);
93 /** Number of elements which can be stored without enlarging the array. */
94 size_t array_capacity(Array
*);
95 /** Remove all elements with index greater or equal to ``length``, keep allocated memory. */
96 bool array_truncate(Array
*, size_t length
);
100 * .. note:: Has to be less or equal than the capacity.
101 * Newly accesible elements preserve their previous values.
104 bool array_resize(Array
*, size_t length
);