array.h

   1 #ifndef ARRAY_H
   2 #define ARRAY_H
   3
   4 #include <stddef.h>
   5 #include <stdbool.h>
   6
   7 /* A dynamically growing array, there exist two typical ways to use it:
   8  *
   9  *  1) to hold pointers to externally allocated memory regions
  10  *
  11  *     Use array_init(...) for initialization, an element has the
  12  *     size of a pointer. Use the functions suffixed with `_ptr'
  13  *     to manage your pointers. The cleanup function array_release_full
  14  *     must only be used with this type of array.
  15  *
  16  *  2) to hold arbitrary sized objects
  17  *
  18  *     Use array_init_sized(...) to specify the size of a single
  19  *     element. Use the regular (i.e. without the `_ptr' suffix)
  20  *     functions to manage your objects. array_{add,set} will copy
  21  *     the object into the array, array_get will return a pointer
  22  *     to the object stored within the array.
  23  */
  24 typedef struct {          /* a dynamically growing array */
  25         char *items;      /* NULL if empty */
  26         size_t elem_size; /* size of one array element */
  27         size_t len;       /* number of currently stored items */
  28         size_t count;     /* maximal capacity of the array */
  29 } Array;
  30
  31 /* initalize an already allocated Array instance, storing pointers
  32  * (elem_size == sizeof(void*)) */
  33 void array_init(Array*);
  34 /* initalize an already allocated Array instance, storing arbitrary
  35  * sized objects */
  36 void array_init_sized(Array*, size_t elem_size);
  37 /* release/free the storage space used to hold items, reset size to zero */
  38 void array_release(Array*);
  39 /* like above but also call free(3) for each stored pointer */
  40 void array_release_full(Array*);
  41 /* remove all elements, set array length to zero, keep allocated memory */
  42 void array_clear(Array*);
  43 /* reserve space to store at least `count' elements in this aray */
  44 bool array_reserve(Array*, size_t count);
  45 /* get/set the i-th (zero based) element of the array */
  46 void *array_get(Array*, size_t idx);
  47 void *array_get_ptr(Array*, size_t idx);
  48 bool array_set(Array*, size_t idx, void *item);
  49 bool array_set_ptr(Array*, size_t idx, void *item);
  50 /* add a new element to the end of the array */
  51 bool array_add(Array*, void *item);
  52 bool array_add_ptr(Array*, void *item);
  53 /* remove an element by index, might not shrink/release underlying memory */
  54 bool array_remove(Array*, size_t idx);
  55 /* return the number of elements currently stored in the array */
  56 size_t array_length(Array*);
  57
  58 #endif