vis: improve `:<` command implementation
[vis.git] / array.h
bloba01f19a6d69bc2c25ee29a1ce0d8ccff26245547
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 /** Release storage space. Reinitializes Array object. */
47 void array_release(Array*);
48 /**
49 * Release storage space and call `free(3)` for each stored pointer.
50 * @rst
51 * .. warning:: Assumes array elements to be pointers.
52 * @endrst
54 void array_release_full(Array*);
55 /** Empty array, keep allocated memory. */
56 void array_clear(Array*);
57 /** Reserve memory to store at least ``count`` elements. */
58 bool array_reserve(Array*, size_t count);
59 /**
60 * Get array element.
61 * @rst
62 * .. warning:: Returns a pointer to the allocated array region.
63 * Operations which might cause reallocations (e.g. the insertion
64 * of new elements) might invalidate the pointer.
65 * @endrst
67 void *array_get(Array*, size_t idx);
68 /**
69 * Set array element.
70 * @rst
71 * .. note:: Copies the ``item`` into the Array. If ``item`` is ``NULL``
72 * the corresponding memory region will be cleared.
73 * @endrst
75 bool array_set(Array*, size_t idx, void *item);
76 /** Dereference pointer stored in array element. */
77 void *array_get_ptr(Array*, size_t idx);
78 /** Store the address to which ``item`` points to into the array. */
79 bool array_set_ptr(Array*, size_t idx, void *item);
80 /** Add element to the end of the array. */
81 bool array_add(Array*, void *item);
82 /** Add pointer to the end of the array. */
83 bool array_add_ptr(Array*, void *item);
84 /**
85 * Remove an element by index.
86 * @rst
87 * .. note:: Might not shrink underlying memory region.
88 * @endrst
90 bool array_remove(Array*, size_t idx);
91 /** Number of elements currently stored in the array. */
92 size_t array_length(Array*);
93 /** Number of elements which can be stored without enlarging the array. */
94 size_t array_capacity(Array*);
95 /** Remove all elements with index greater or equal to ``length``, keep allocated memory. */
96 bool array_truncate(Array*, size_t length);
97 /**
98 * Change length.
99 * @rst
100 * .. note:: Has to be less or equal than the capacity.
101 * Newly accesible elements preserve their previous values.
102 * @endrst
104 bool array_resize(Array*, size_t length);
106 #endif