filetype: Set "groovy" for Jenkinsfile
[vis.git] / array.h
blob5eb8daa31b8dd21ae1602eb8dca61875f0d36794
1 #ifndef ARRAY_H
2 #define ARRAY_H
4 #include <stddef.h>
5 #include <stdbool.h>
7 /**
8 * @file
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. */
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;
35 /**
36 * Initalize an Array object to store pointers.
37 * @rst
38 * .. note:: Is equivalent to ``array_init_sized(arr, sizeof(void*))``.
39 * @endrst
41 void array_init(Array*);
42 /**
43 * Initalize an Array object to store arbitrarily sized objects.
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
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
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
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
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
106 bool array_resize(Array*, size_t length);
108 * Sort array, the comparision function works as for `qsort(3)`.
110 void array_sort(Array*, int (*compar)(const void*, const void*));
112 * Push item onto the top of the stack.
113 * @rst
114 * .. note:: Is equivalent to ``array_add(arr, item)``.
115 * @endrst
117 bool array_push(Array*, void *item);
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
124 void *array_pop(Array*);
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
131 void *array_peek(const Array*);
133 #endif