Array¶
A dynamically growing array, there exist two typical ways to use it:
To hold pointers to externally allocated memory regions.
Use
array_init
for initialization, an element has the size of a pointer. Use the functions suffixed with_ptr
to manage your pointers. The cleanup functionarray_release_full
must only be used with this type of array.To hold arbitrary sized objects.
Use
array_init_sized
to specify the size of a single element. Use the regular (i.e. without the_ptr
suffix) functions to manage your objects. Functions likearray_add
andarray_set
will copy the object into the array,array_get
will return a pointer to the object stored within the array.
Functions
-
void array_init(Array*)¶
Initialize an Array object to store pointers.
Note
Is equivalent to
array_init_sized(arr, sizeof(void*))
.
-
void array_init_sized(Array*, size_t elem_size)¶
Initialize an Array object to store arbitrarily sized objects.
-
void array_init_from(Array*, const Array *from)¶
Initialize Array by using the same element size as in
from
.
-
void array_release_full(Array*)¶
Release storage space and call
free(3)
for each stored pointer.Warning
Assumes array elements to be pointers.
-
void *array_get(const Array*, size_t idx)¶
Get array element.
Warning
Returns a pointer to the allocated array region. Operations which might cause reallocations (e.g. the insertion of new elements) might invalidate the pointer.
-
bool array_set(Array*, size_t idx, void *item)¶
Set array element.
Note
Copies the
item
into the Array. Ifitem
isNULL
the corresponding memory region will be cleared.
-
bool array_set_ptr(Array*, size_t idx, void *item)¶
Store the address to which
item
points to into the array.
-
bool array_remove(Array*, size_t idx)¶
Remove an element by index.
Note
Might not shrink underlying memory region.
-
size_t array_capacity(const Array*)¶
Number of elements which can be stored without enlarging the array.
-
bool array_truncate(Array*, size_t length)¶
Remove all elements with index greater or equal to
length
, keep allocated memory.
-
bool array_resize(Array*, size_t length)¶
Change length.
Note
Has to be less or equal than the capacity. Newly accessible elements preserve their previous values.
-
void array_sort(Array*, int (*compar)(const void*, const void*))¶
Sort array, the comparision function works as for
qsort(3)
.
-
bool array_push(Array*, void *item)¶
Push item onto the top of the stack.
Note
Is equivalent to
array_add(arr, item)
.
-
struct Array¶
- #include <array.h>
A dynamically growing array.