Growable Memory Buffers for C99
This C99 header library provides a simple, portable interface to growable buffers of homogeneous values of any type, similar to a std::vector in C++. The user need not use any particular struct, and the buffer need only initialize to NULL.
Each "function" in the interface is actually a macro, and its usage is reflected by these hypothetical prototypes:
/* Returns the number of elements in the buffer (for push and pop).
*/
size_t buf_size(type *v);
/* Returns the total capacity of the buffer.
*/
size_t buf_capacity(type *v);
/* Destroy and free the buffer, effectively resetting it.
* Potentially assigns a new V pointer.
*/
void buf_free(type *v);
/* Append an element E to the end of the buffer, growing if necessary.
* Potentially increases the capacity and assigns a new V pointer.
*/
void buf_push(type *v, type e);
/* Remove an element E from the end of the buffer.
* Neither the capacity nor the V pointer will change. Popping when the
* size is zero has undefined results.
*/
type buf_pop(type *v);
/* Increase buffer capactity by N elements.
* Potentially assigns a new V pointer while also returning it.
*/
type *buf_grow(type *v, ptrdiff_t n);
/* Set buffer capactity to exactly N elements.
* Potentially assigns a new V pointer while also returning it. A
* negative capacity has undefined results.
*/
type *buf_trunc(type *v, ptrdiff_t n);
/* Set buffer size to zero.
* Only affects push and pop. The capacity and buffer contents are
* unchanged.
*/
void buf_clear(type *v);Note: buf_push(), buf_grow(), buf_trunc(), and buf_free() may
change the buffer pointer, and any previously-taken pointers should be
considered invalidated. This has important consequences that must be
considered.
The BUF_INIT_CAPACITY determines the initial capacity for buffers
receiving their first push.
The BUF_ABORT macro is evaluated when the system runs out of memory.
It defaults to abort(), but you may override it to run your own abort
code instead.
Example usage:
float *values = 0;
/* Append 25 values */
for (size_t i = 0; i < 25; i++)
buf_push(values, rand() / (float)RAND_MAX);
/* Access 25 values using the normal [] operator */
for (size_t i = 0; i < buf_size(values); i++)
printf("values[%zu] = %f\n", i, values[i]);
/* Destroy/reset the buffer */
buf_free(values);Purpose
This library is inspired by stb stretchy_buffer.h. The
difference is that it's written in C99 so that it doesn't need to rely
on undefined behavior. This does so by using a flexible array member and
the offsetof() macro. It also checks for integer overflows before
allocating any memory, making it safer.