diff options
Diffstat (limited to 'array.h')
| -rw-r--r-- | array.h | 35 |
1 files changed, 30 insertions, 5 deletions
@@ -4,14 +4,36 @@ #include <stddef.h> #include <stdbool.h> -typedef struct { /* a dynamically growing array */ - void **items; /* NULL if empty */ - size_t len; /* number of currently stored items */ - size_t count; /* maximal capacity of the array */ +/* A dynamically growing array, there exist two typical ways to use it: + * + * 1) 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 function array_release_full + * must only be used with this type of array. + * + * 2) 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. array_{add,set} will copy + * the object into the array, array_get will return a pointer + * to the object stored within the array. + */ +typedef struct { /* a dynamically growing array */ + char *items; /* NULL if empty */ + size_t elem_size; /* size of one array element */ + size_t len; /* number of currently stored items */ + size_t count; /* maximal capacity of the array */ } Array; -/* initalize a (stack allocated) Array instance */ +/* initalize an already allocated Array instance, storing pointers + * (elem_size == sizeof(void*)) */ void array_init(Array*); +/* initalize an already allocated Array instance, storing arbitrary + * sized objects */ +void array_init_sized(Array*, size_t elem_size); /* release/free the storage space used to hold items, reset size to zero */ void array_release(Array*); /* like above but also call free(3) for each stored pointer */ @@ -22,9 +44,12 @@ void array_clear(Array*); bool array_reserve(Array*, size_t count); /* get/set the i-th (zero based) element of the array */ void *array_get(Array*, size_t idx); +void *array_get_ptr(Array*, size_t idx); bool array_set(Array*, size_t idx, void *item); +bool array_set_ptr(Array*, size_t idx, void *item); /* add a new element to the end of the array */ bool array_add(Array*, void *item); +bool array_add_ptr(Array*, void *item); /* return the number of elements currently stored in the array */ size_t array_length(Array*); |