array.h

   1 #ifndef ARRAY_H
   2 #define ARRAY_H
   3
   4 #include <stddef.h>
   5 #include <stdbool.h>
   6
   7 /**
   8  * @file
   9  *
  10  * A dynamically growing array, there exist two typical ways to use it:
  11  *
  12  *  1. To hold pointers to externally allocated memory regions.
  13  *
  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.
  18  *
  19  *  2. To hold arbitrary sized objects.
  20  *
  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.
  26  */
  27 /** A dynamically growing array. */
  28 typedef struct {
  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. */
  33 } Array;
  34
  35 /**
  36  * Initalize an Array object to store pointers.
  37  * @rst
  38  * .. note:: Is equivalent to ``array_init_sized(arr, sizeof(void*))``.
  39  * @endrst
  40  */
  41 void array_init(Array*);
  42 /**
  43  * Initalize an Array object to store arbitrarily sized objects.
  44  */
  45 void array_init_sized(Array*, size_t elem_size);
  46 /** Initialize Array by using the same element size as in ``from``. */
  47 void array_init_from(Array*, const Array *from);
  48 /** Release storage space. Reinitializes Array object. */
  49 void array_release(Array*);
  50 /**
  51  * Release storage space and call `free(3)` for each stored pointer.
  52  * @rst
  53  * .. warning:: Assumes array elements to be pointers.
  54  * @endrst
  55  */
  56 void array_release_full(Array*);
  57 /** Empty array, keep allocated memory. */
  58 void array_clear(Array*);
  59 /** Reserve memory to store at least ``count`` elements. */
  60 bool array_reserve(Array*, size_t count);
  61 /**
  62  * Get array element.
  63  * @rst
  64  * .. warning:: Returns a pointer to the allocated array region.
  65  *              Operations which might cause reallocations (e.g. the insertion
  66  *              of new elements) might invalidate the pointer.
  67  * @endrst
  68  */
  69 void *array_get(const Array*, size_t idx);
  70 /**
  71  * Set array element.
  72  * @rst
  73  * .. note:: Copies the ``item`` into the Array. If ``item`` is ``NULL``
  74  *           the corresponding memory region will be cleared.
  75  * @endrst
  76  */
  77 bool array_set(Array*, size_t idx, void *item);
  78 /** Dereference pointer stored in array element. */
  79 void *array_get_ptr(const Array*, size_t idx);
  80 /** Store the address to which ``item`` points to into the array. */
  81 bool array_set_ptr(Array*, size_t idx, void *item);
  82 /** Add element to the end of the array. */
  83 bool array_add(Array*, void *item);
  84 /** Add pointer to the end of the array. */
  85 bool array_add_ptr(Array*, void *item);
  86 /**
  87  * Remove an element by index.
  88  * @rst
  89  * .. note:: Might not shrink underlying memory region.
  90  * @endrst
  91  */
  92 bool array_remove(Array*, size_t idx);
  93 /** Number of elements currently stored in the array. */
  94 size_t array_length(const Array*);
  95 /** Number of elements which can be stored without enlarging the array. */
  96 size_t array_capacity(const Array*);
  97 /** Remove all elements with index greater or equal to ``length``, keep allocated memory. */
  98 bool array_truncate(Array*, size_t length);
  99 /**
 100  * Change length.
 101  * @rst
 102  * .. note:: Has to be less or equal than the capacity.
 103  *           Newly accessible elements preserve their previous values.
 104  * @endrst
 105  */
 106 bool array_resize(Array*, size_t length);
 107 /**
 108  * Sort array, the comparision function works as for `qsort(3)`.
 109  */
 110 void array_sort(Array*, int (*compar)(const void*, const void*));
 111 /**
 112  * Push item onto the top of the stack.
 113  * @rst
 114  * .. note:: Is equivalent to ``array_add(arr, item)``.
 115  * @endrst
 116  */
 117 bool array_push(Array*, void *item);
 118 /**
 119  * Get and remove item at the top of the stack.
 120  * @rst
 121  * .. warning:: The same ownership rules as for ``array_get`` apply.
 122  * @endrst
 123  */
 124 void *array_pop(Array*);
 125 /**
 126  * Get item at the top of the stack without removing it.
 127  * @rst
 128  * .. warning:: The same ownership rules as for ``array_get`` apply.
 129  * @endrst
 130  */
 131 void *array_peek(const Array*);
 132
 133 #endif