Vector

A dynamic array of void * values.

Usage#

Initialize a Vector with an optional payload destructor. Pass NULL for stack allocated data. The vector stores pointers without copying the payloads.

Vector vec;
if (vec_init(&vec, NULL) == 0) {
    int value = 42;
    if (vec_push(&vec, &value) == 0) {
        int *stored = vec_safe_at(&vec, 0);
        /* stored points to value. */
        (void)stored;
    }
    vec_destroy(&vec);
}

vec_destroy frees the backing array and calls the destructor on remaining payloads. The Vector handle is yours to free if you allocated it. Removing or popping a payload transfers it to the caller without running the destructor.

Structs#

Vector#

Vector struct

typedef struct Vector {
    size_t capacity;
    size_t length;
    void **elements;
    void (*destroy)(void *data);
} Vector;

Members:

• capacity: The number of pointer slots allocated in elements
• length: The number of real elements stored in the backing elements array
• elements: The dynamic array of void * that holds the vector's members
• destroy: Optional deallocation function for each stored payload. Typical usage is NULL for stack allocated data and free() for data created with malloc()

Functions#

vec_init#

Initialize the vector with a default capacity of 2. Call vec_destroy() when finished. Returns 0 on success, -1 on error.

int vec_init(Vector *vec, void (*destroy)(void *data));

vec_init_with_capacity#

Initialize the vector with a user-specified capacity. capacity == 0 is allowed: elements is NULL and the first insert grows from the default capacity. Failed init leaves a destroyable empty vector (capacity == 0, elements == NULL). Returns 0 on success, -1 on error.

int vec_init_with_capacity(Vector *vec, void (*destroy)(void *data), size_t cap);

vec_destroy#

Frees the underlying array inside a Vector. If destroy was provided when creating the vector, then it is called against each element in the array before the array is freed. Does not destroy the vector itself, that is left up to the user. Zeros the handle so a second vec_destroy is a no-op.

void vec_destroy(Vector *vec);

/* Usage */
vec_destroy(vec);
free(vec);

vec_clear#

Destroys all elements in the vector (calling destroy on each if provided) and sets length to 0. Capacity and the backing array are kept. Returns 0 on success, -1 on error.

int vec_clear(Vector *vec);

vec_grow_to#

Grows the capacity of the vector to new_cap. Returns -1 if new_cap is less than the current capacity. Returns 0 without reallocating when new_cap equals the current capacity. Returns -1 on allocation failure, overflow, or a NULL vector. Failure leaves the vector unchanged.

int vec_grow_to(Vector *vec, const size_t new_cap);

vec_reserve#

Ensure the vector can hold at least n elements. Returns 0 when n is already within capacity or growth succeeds, -1 on a NULL vector, overflow, or allocation failure. Failure leaves the vector unchanged.

int vec_reserve(Vector *vec, size_t n);

vec_insert#

Insert data into the vector at a specified index. The index may range from 0 through the current length, inclusive. Elements at that index and beyond move up to make room. Returns 0 on success, -1 on invalid arguments or allocation failure.

int vec_insert(Vector *vec, void *data, size_t index);

/* Usage */

// vec: 1 2 3 4
int i = 99;
vec_insert(vec, &i, 2);
// vec: 1 2 99 3 4

vec_push#

Insert data at the end of the vector. Returns 0 on success, -1 on error.

int vec_push(Vector *vec, void *data);

/* Usage */

// vec: 1 2 3
int i = 4;
vec_push(vec, &i); /* Keep i alive while stored; use a NULL destructor. */
// vec: 1 2 3 4

vec_safe_at#

Gets the stored data at a specified index. Uses safety checks to make sure index is not out of bounds. Returns NULL if the index is out of bounds or the stored payload is NULL. The vector must be non-NULL.

void *vec_safe_at(Vector *vec, size_t index);

vec_remove#

Removes an element from the array and returns the pointer, then shifts later elements down to close the gap. Does not call the destructor or change capacity. Returns NULL if the index is not valid or the removed payload is NULL.

void *vec_remove(Vector *vec, size_t index);

/* Usage */
// vec: 1 2 3 4
int *t = NULL;
t = (int*)vec_remove(vec, 2);
assert(*t == 3);
// vec: 1 2 4

vec_shrink#

Shrinks capacity to the current length. An empty vector releases its backing array. Returns 0 on success, -1 on allocation failure.

int vec_shrink(Vector *vec);

vec_min#

Finds the smallest value in the vector and returns a void pointer to the underlying data. Returns NULL if the vector is empty. Requires a comparison function to compare the data in the vector. The comparator receives payload pointers directly and must return a positive value if a > b, a negative value if a < b, or 0 if equal. See the supplied comparison functions below for reference.

const void *vec_min(const Vector *vec, int(*cmp)(const void *a, const void *b));

vec_max#

Finds the largest value in the vector and returns a void pointer to the underlying data. Returns NULL if the vector is empty. Requires a comparison function to compare the data in the vector. The comparator receives payload pointers directly and must return a positive value if a > b, a negative value if a < b, or 0 if equal. See the supplied comparison functions below for reference.

const void *vec_max(const Vector *vec, int(*cmp)(const void *a, const void *b));

vec_pop#

Removes and returns the last element of the vector. Does not call the destructor. Returns NULL if the vector is empty or the removed payload is NULL.

void *vec_pop(Vector *vec);

/* Usage */
// vec: 1 2 3
int *t = (int *)vec_pop(vec);
assert(*t == 3);
// vec: 1 2

vec_reverse#

Reverses the order of elements in the vector in-place. O(n) time, O(1) space.

void vec_reverse(Vector *vec);

vec_sort#

Sorts the vector in-place using qsort_r. The comparator receives payload pointers directly, not pointers to array slots. Concurrent mutation of the same vector is not supported. Requires a comparator function that returns a negative value if a < b, 0 if a == b, or a positive value if a > b. See the supplied comparison functions below for reference.

void vec_sort(Vector *vec, int (*cmp)(const void *a, const void *b));

/* Usage */
vec_sort(vec, vec_cmp_int);

vec_bsearch#

Binary search on a sorted vector. Returns a pointer to the matching element's data, or NULL if not found. The vector must be sorted by the same comparator before calling this function.

void *vec_bsearch(Vector *vec, const void *key, int (*cmp)(const void *a, const void *b));

/* Usage */
vec_sort(vec, vec_cmp_int);
int key = 3;
int *found = (int *)vec_bsearch(vec, &key, vec_cmp_int);

Comparison Functions#

Comparison functions to compare data in a vector. The supplied functions return 1 if a > b, -1 if a < b, or 0 if equal. Custom comparators may return any positive or negative value.

int vec_cmp_int(const void *a, const void *b);
int vec_cmp_char(const void *a, const void *b);

Macros#

vec_at#

Grabs the element at index i without safety checks for better performance. Use with caution

#define vec_at(v, i) (v)->elements[(i)]

vec_len#

Returns the length of the vector

#define vec_len(v) (v)->length

vec_cap#

Returns the capacity of the vector

#define vec_cap(v) (v)->capacity