burkey.co /docs/libflint/vector
index vector
~/docs/libflint/vector.md
libflint

Vector

libflint·Data Structures

A dynamic array of void * values. The caller owns the Vector handle. The vector stores pointers and does not copy payloads.

Usage#

Initialize a Vector with an optional payload destructor. Pass NULL when the payloads are borrowed.

Vector vec;
int first = 1;
int second = 2;
if (vec_init(&vec, NULL) == 0) {
    if (vec_push(&vec, &first) == 0 && vec_push(&vec, &second) == 0) {
        int *stored = vec_safe_at(&vec, 0);
        void *last = vec_pop(&vec);
        if (stored != NULL && last != NULL) {
            /* *stored == 1 && *(int *)last == 2 */
        }
    }
    vec_destroy(&vec);
}

vec_destroy frees elements and calls destroy on each remaining payload, in index order. It does not free the Vector handle. It zeros the handle, so a second call is a no-op. vec_remove and vec_pop return the payload and do not call destroy. Growth replaces elements. Payload pointers already stored remain valid.

Structs#

Vector#

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

length is the number of stored pointers. capacity is the number of allocated slots. elements is the backing array, or NULL when capacity is 0. The vector functions update these fields. Do not write them. destroy is the optional payload destructor set by init.

Functions#

vec_init#

Initializes length to 0 and allocates capacity 2. Returns 0 on success. Returns -1 if vec is NULL, and does not write the handle. Allocation failure returns -1 and leaves a destroyable empty vector: capacity == 0, length == 0, elements == NULL, and destroy set. Do not initialize a live vector; the previous array is not freed.

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

vec_init_with_capacity#

Initializes the vector with capacity cap. cap == 0 succeeds with elements == NULL; the first insert then grows from capacity 2. Returns 0 on success. Returns -1 if vec is NULL, and does not write the handle. Allocation failure returns -1 and leaves the same destroyable empty state as a failed vec_init, including the stored destructor. Do not initialize a live vector.

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

vec_clear#

Calls destroy on each stored pointer, in index order, when destroy is set, including a stored NULL. Sets length to 0, writes NULL into the existing slots, and keeps capacity and elements. Returns 0 on success. Returns -1 if vec is NULL, and leaves the handle unchanged.

int vec_clear(Vector *vec);

vec_destroy#

Calls destroy on each stored pointer, in index order, when destroy is set, including a stored NULL, then frees elements. Does not free the Vector handle. Zeros the handle, so a second call is a no-op. A NULL vec returns without crashing. Safe on the empty handle left by a failed init.

void vec_destroy(Vector *vec);

vec_grow_to#

Sets capacity to new_cap. Returns -1 if vec is NULL or new_cap is less than the current capacity. Returns 0 without reallocating when new_cap equals the current capacity. Returns -1 on allocation failure or a size overflow in lf_reallocarray. Failure leaves the vector unchanged.

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

vec_reserve#

Makes capacity at least n. Returns 0 when n is already within capacity, without reallocating. When n is greater, sets capacity to n rather than doubling. Returns -1 if vec is NULL, or on size overflow or allocation failure. Failure leaves the vector unchanged.

int vec_reserve(Vector *vec, size_t n);

vec_insert#

Inserts data at index, shifting the pointers at that index and after it up by one. index may be 0 through length, inclusive. When length == capacity, capacity doubles, or becomes 2 if it was 0. Returns 0 on success. Returns -1 if vec is NULL, index is greater than length, capacity cannot double without overflow, or allocation fails. Failure leaves the vector unchanged. A NULL payload is stored.

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

vec_push#

Inserts data at length. Growth is the same as vec_insert. Returns 0 on success and -1 if growth fails. Failure leaves the vector unchanged. vec must be non-NULL.

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

vec_safe_at#

Returns the payload at index. Returns NULL if index is outside length or the stored payload is NULL. vec must be non-NULL.

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

vec_remove#

Removes the pointer at index, shifts later pointers down, and returns the payload. Does not call destroy or change capacity. An index outside length returns NULL and leaves the vector unchanged. A stored NULL payload is removed and also returns NULL. vec must be non-NULL.

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

vec_shrink#

Sets capacity to length. Returns 0 without allocating when length already equals capacity. An empty vector with spare capacity frees elements and sets capacity to 0. Returns -1 on allocation failure and leaves the vector unchanged. vec must be non-NULL.

int vec_shrink(Vector *vec);

vec_min / vec_max#

Return the earliest payload that compares least, or greatest. cmp receives payload pointers and returns a positive value if a > b, a negative value if a < b, or 0 if equal. Equal payloads keep the earlier one. Returns NULL if length is 0 or the selected payload is NULL. vec and cmp must be non-NULL.

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

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

vec_pop#

Removes and returns the last payload. Does not call destroy or change capacity. An empty vector returns NULL and is unchanged. Popping a stored NULL returns NULL after removing it. vec must be non-NULL.

void *vec_pop(Vector *vec);

vec_reverse#

Reverses the pointers in place. A length below 2 does nothing. O(n) time, O(1) extra space. vec must be non-NULL.

void vec_reverse(Vector *vec);

vec_sort#

Sorts the pointers in place. The comparator is called with payload pointers, not pointers to slots, and returns negative if a < b, 0 if a == b, or positive if a > b. The sort is not stable: equal elements may change order. A comparator that returns nonzero for every distinct pair has only one sorted result. Fewer than two elements returns without calling cmp. vec must be non-NULL, and cmp must be non-NULL when length >= 2.

The implementation calls qsort_r. Under __APPLE__, __FreeBSD__, and __OpenBSD__ the call passes the thunk before the comparison wrapper. Otherwise it uses the GNU order, comparison wrapper then thunk.

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

vec_bsearch#

Binary-searches a vector sorted ascending by cmp. cmp is called as cmp(key, element). Returns a matching payload, or NULL if none compares equal. A stored NULL payload that compares equal also returns NULL. The vector is not checked for sortedness. An empty vector returns NULL without calling cmp. vec must be non-NULL. cmp must be non-NULL when length is nonzero.

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

vec_cmp_int / vec_cmp_char#

Compare the int or char values pointed to by a and b. vec_cmp_char compares one C char, which may be signed, not a string. Both return 1 if a > b, -1 if a < b, or 0 if equal. The pointers must be non-NULL. Other 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#

The payload at index i, with no bounds check. i must be less than length.

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

vec_len#

The number of stored pointers.

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

vec_cap#

The number of allocated slots.

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