Array Utility

Functions for querying and managing array size and capacity. More...

Functions
DA_DEF int	da_length (da_array arr)
	Gets the current number of elements in the array.
DA_DEF int	da_capacity (da_array arr)
	Gets the current allocated capacity of the array.
DA_DEF void	da_reserve (da_array arr, int new_capacity)
	Ensures the array has at least the specified capacity.
DA_DEF void	da_resize (da_array arr, int new_length)
	Changes the array length, growing or shrinking as needed.
DA_DEF void	da_trim (da_array arr, int new_capacity)
	Reduces the array's allocated capacity to a specific size.
DA_DEF void	da_append_array (da_array dest, da_array src)
	Appends all elements from source array to destination array.
DA_DEF da_array	da_concat (da_array arr1, da_array arr2)
	Creates a new array by concatenating two arrays.
DA_DEF void	da_append_raw (da_array arr, const void *data, int count)
	Appends raw C array data to the dynamic array.
DA_DEF void	da_fill (da_array arr, const void *element, int count)
	Fills the array with multiple copies of an element.
DA_DEF da_array	da_slice (da_array arr, int start, int end)
	Creates a new array containing elements from a range [start, end)
DA_DEF da_array	da_copy (da_array arr)
	Creates a complete copy of an existing array.
DA_DEF da_array	da_filter (da_array arr, int(*predicate)(const void *element, void *context), void *context)
	Creates a new array containing elements that pass a predicate test.
DA_DEF da_array	da_map (da_array arr, void(*mapper)(const void *src, void *dst, void *context), void *context)
	Creates a new array by transforming each element using a mapper function.
DA_DEF void	da_reduce (da_array arr, const void *initial, void *result, void(*reducer)(void *accumulator, const void *element, void *context), void *context)
	Reduces array to single value using accumulator function.
DA_DEF void	da_remove_range (da_array arr, int start, int count)
	Removes multiple consecutive elements from the array.
DA_DEF void	da_reverse (da_array arr)
	Reverses all elements in the array in place.
DA_DEF void	da_swap (da_array arr, int i, int j)
	Swaps two elements at the specified indices.
DA_DEF int	da_is_empty (da_array arr)
	Checks if the array is empty.
DA_DEF int	da_find_index (da_array arr, int(*predicate)(const void *element, void *context), void *context)
	Find index of first element matching predicate.
DA_DEF int	da_contains (da_array arr, int(*predicate)(const void *element, void *context), void *context)
	Check if array contains element matching predicate.
DA_DEF void	da_sort (da_array arr, int(*compare)(const void *a, const void *b, void *context), void *context)
	Sort array elements using comparison function.

Detailed Description

Functions for querying and managing array size and capacity.

Function Documentation

da_append_array()

DA_DEF void da_append_array	(	da_array	dest,
		da_array	src
	)

Appends all elements from source array to destination array.

Parameters

dest	Destination array to append to (must not be NULL)
src	Source array to read from (must not be NULL)

Note

Automatically grows dest capacity if needed

Source array is unchanged

Arrays must have the same element_size

Asserts on allocation failure or mismatched element sizes

da_array arr1 = DA_CREATE(int, 2);  // [10, 20]
da_array arr2 = DA_CREATE(int, 2);  // [30, 40]
da_append_array(arr1, arr2);        // arr1 = [10, 20, 30, 40]

da_append_raw()

DA_DEF void da_append_raw	(	da_array	arr,
		const void *	data,
		int	count
	)

Appends raw C array data to the dynamic array.

Parameters

arr	Array to modify (must not be NULL)
data	Pointer to raw data array (must not be NULL)
count	Number of elements to append (must be >= 0)

Note

Automatically grows array capacity if needed

More efficient than multiple da_push() calls

Asserts on allocation failure or NULL parameters

int raw_data[] = {10, 20, 30, 40};
da_append_raw(arr, raw_data, 4);  // Append all 4 elements at once

da_capacity()

DA_DEF int da_capacity

(

da_array

arr

)

Gets the current allocated capacity of the array.

Parameters

arr	Array to query (must not be NULL)

Returns

Number of elements that can be stored without reallocation

printf("Array using %d/%d slots\n", da_length(arr), da_capacity(arr));

da_concat()

DA_DEF da_array da_concat	(	da_array	arr1,
		da_array	arr2
	)

Creates a new array by concatenating two arrays.

Parameters

arr1	First array (must not be NULL)
arr2	Second array (must not be NULL)

Returns

New array containing elements from arr1 followed by arr2

Note

Arrays must have the same element_size

Original arrays are unchanged

Returned array has ref_count = 1

Capacity is exactly length (no wasted space)

Asserts on allocation failure or mismatched element sizes

da_array nums1 = DA_CREATE(int, 2);  // [10, 20]
da_array nums2 = DA_CREATE(int, 2);  // [30, 40]
da_array combined = da_concat(nums1, nums2);  // [10, 20, 30, 40]
// nums1 and nums2 remain unchanged

da_contains()

DA_DEF int da_contains	(	da_array	arr,
		int(*)(const void *element, void *context)	predicate,
		void *	context
	)

Check if array contains element matching predicate.

Parameters

arr	Array to search (must not be NULL)
predicate	Function to test elements (must not be NULL)
context	Optional context passed to predicate (can be NULL)

Returns

1 if matching element found, 0 otherwise

Note

More readable than da_find_index(arr, predicate, context) != -1

int has_negative(const void* elem, void* ctx) {
    return *(int*)elem < 0;
}
 
if (da_contains(numbers, has_negative, NULL)) {
    printf("Array contains negative numbers\n");
}

da_copy()

DA_DEF da_array da_copy

(

da_array

arr

)

Creates a complete copy of an existing array.

Parameters

arr	Source array to copy from (must not be NULL)

Returns

New array containing all elements from the source array

Note

Original array is unchanged

Returned array has ref_count = 1 and exact capacity = length

Perfect for creating arrays that can be modified independently

Asserts on allocation failure

da_array original = DA_CREATE(int, 3);  // [10, 20, 30]
da_array copy = da_copy(original);      // [10, 20, 30] - independent copy
 
// Now you can sort the copy without affecting the original
sort_array(copy);  // original remains [10, 20, 30]

da_fill()

DA_DEF void da_fill	(	da_array	arr,
		const void *	element,
		int	count
	)

Fills the array with multiple copies of an element.

Parameters

arr	Array to modify (must not be NULL)
element	Pointer to element to replicate (must not be NULL)
count	Number of copies to add (must be >= 0)

Note

Automatically grows array capacity if needed

More efficient than multiple da_push() calls

Asserts on allocation failure or NULL parameters

int zero = 0;
da_fill(arr, &zero, 100);  // Add 100 zeros to array

da_filter()

DA_DEF da_array da_filter	(	da_array	arr,
		int(*)(const void *element, void *context)	predicate,
		void *	context
	)

Creates a new array containing elements that pass a predicate test.

Parameters

arr	Source array to filter (must not be NULL)
predicate	Function that returns non-zero for elements to keep (must not be NULL)
context	Optional context pointer passed to predicate function (can be NULL)

Returns

New array containing only elements that pass the predicate test (exact capacity)

Note

Creates a new array with reference count = 1

Result array has exact capacity = number of matching elements (no wasted memory)

Returns empty array (capacity=0) if no elements match

Predicate receives (element_pointer, context) and should return non-zero to keep element

Asserts on allocation failure or NULL required parameters

Perfect for functional programming patterns and data filtering

// Filter even numbers
int is_even(const void* elem, void* ctx) {
    return *(int*)elem % 2 == 0;
}
 
da_array numbers = DA_CREATE(int, 5);  // [1, 2, 3, 4, 5]
da_array evens = da_filter(numbers, is_even, NULL);  // [2, 4] - exact capacity

da_find_index()

DA_DEF int da_find_index	(	da_array	arr,
		int(*)(const void *element, void *context)	predicate,
		void *	context
	)

Find index of first element matching predicate.

Parameters

arr	Array to search (must not be NULL)
predicate	Function to test elements (must not be NULL)
context	Optional context passed to predicate (can be NULL)

Returns

Index of first matching element, or -1 if not found

Note

Predicate receives (element_pointer, context) and should return non-zero for match

int is_even(const void* elem, void* ctx) {
    return *(int*)elem % 2 == 0;
}
 
da_array numbers = DA_CREATE(int, 5);  // [1, 3, 4, 7, 8]
int index = da_find_index(numbers, is_even, NULL);  // returns 2 (index of 4)

da_is_empty()

DA_DEF int da_is_empty

(

da_array

arr

)

Checks if the array is empty.

Parameters

arr	Array to check (must not be NULL)

Returns

1 if length == 0, 0 otherwise

Note

More readable than da_length(arr) == 0

if (da_is_empty(arr)) {
    printf("Array is empty\n");
}

da_length()

DA_DEF int da_length

(

da_array

arr

)

Gets the current number of elements in the array.

Parameters

arr	Array to query (must not be NULL)

Returns

Number of elements currently in the array

for (int i = 0; i < da_length(arr); i++) {
    process_element(da_get(arr, i));
}

da_map()

DA_DEF da_array da_map	(	da_array	arr,
		void(*)(const void *src, void *dst, void *context)	mapper,
		void *	context
	)

Creates a new array by transforming each element using a mapper function.

Parameters

arr	Source array to transform (must not be NULL)
mapper	Function to transform elements (must not be NULL)
context	Optional context pointer passed to mapper function (can be NULL)

Returns

New array with transformed elements (same length, exact capacity)

Note

Creates a new array with reference count = 1

Result array has same length as source and exact capacity = length

Mapper receives (src_element_ptr, dst_element_ptr, context)

Mapper should write transformed result to dst_element_ptr

Asserts on allocation failure or NULL required parameters

Perfect for functional programming patterns and data transformation

// Double all values
void double_int(const void* src, void* dst, void* ctx) {
    *(int*)dst = *(int*)src * 2;
}
 
da_array numbers = DA_CREATE(int, 3);    // [1, 2, 3]
da_array doubled = da_map(numbers, double_int, NULL);  // [2, 4, 6] - exact capacity

da_reduce()

DA_DEF void da_reduce	(	da_array	arr,
		const void *	initial,
		void *	result,
		void(*)(void *accumulator, const void *element, void *context)	reducer,
		void *	context
	)

Reduces array to single value using accumulator function.

Parameters

arr	Source array (must not be NULL)
initial	Initial accumulator value (must not be NULL)
result	Output buffer for final result (must not be NULL)
reducer	Function that combines accumulator with each element
context	Optional context passed to reducer function (can be NULL)

Note

Reducer function signature: void (reducer)(void accumulator, const void* element, void* context)

The accumulator is passed as first parameter and modified in-place

Result buffer receives the final accumulated value

// Sum all integers
void sum_ints(void* acc, const void* elem, void* ctx) {
    (void)ctx;
    *(int*)acc += *(int*)elem;
}
 
int initial = 0;
int result;
da_reduce(numbers, &initial, &result, sum_ints, NULL);  // result = sum of all elements

da_remove_range()

DA_DEF void da_remove_range	(	da_array	arr,
		int	start,
		int	count
	)

Removes multiple consecutive elements from the array.

Parameters

arr	Array to modify (must not be NULL)
start	Starting index of range to remove (must be >= 0)
count	Number of elements to remove (must be >= 0)

Note

Shifts elements after the range to the left

Does not shrink capacity

Asserts on out-of-bounds range

// Remove elements at indices 2, 3, 4 (3 elements starting at index 2)
da_remove_range(arr, 2, 3);

da_reserve()

DA_DEF void da_reserve	(	da_array	arr,
		int	new_capacity
	)

Ensures the array has at least the specified capacity.

Parameters

arr	Array to modify (must not be NULL)
new_capacity	Minimum capacity required (must be >= 0)

Note

Only increases capacity, never decreases

Asserts on allocation failure

Useful for avoiding multiple reallocations when size is known

da_reserve(arr, 1000);  // Ensure space for 1000 elements
for (int i = 0; i < 1000; i++) {
    da_push(arr, &i);  // No reallocations needed
}

da_resize()

DA_DEF void da_resize	(	da_array	arr,
		int	new_length
	)

Changes the array length, growing or shrinking as needed.

Parameters

arr	Array to modify (must not be NULL)
new_length	New length for the array (must be >= 0)

Note

If growing, new elements are zero-initialized

If shrinking, excess elements are discarded

Automatically adjusts capacity if needed

Asserts on allocation failure

da_resize(arr, 100);  // Array now has exactly 100 elements
// Elements 0..old_length-1 preserve their values
// Elements old_length..99 are zero-initialized

da_reverse()

DA_DEF void da_reverse

(

da_array

arr

)

Reverses all elements in the array in place.

Parameters

arr	Array to reverse (must not be NULL)

Note

Modifies the array directly

O(n/2) time complexity with element swaps

// [10, 20, 30] becomes [30, 20, 10]
da_reverse(arr);

da_slice()

DA_DEF da_array da_slice	(	da_array	arr,
		int	start,
		int	end
	)

Creates a new array containing elements from a range [start, end)

Parameters

arr	Source array to slice from (must not be NULL)
start	Starting index (inclusive, must be >= 0)
end	Ending index (exclusive, must be >= start and <= length)

Returns

New array containing elements from [start, end)

Note

Original array is unchanged

Returned array has ref_count = 1 and exact capacity

Empty range (start == end) returns empty array

Asserts on out-of-bounds indices or allocation failure

da_array original = DA_CREATE(int, 5);  // [10, 20, 30, 40, 50]
da_array slice = da_slice(original, 1, 4);  // [20, 30, 40]

da_sort()

DA_DEF void da_sort	(	da_array	arr,
		int(*)(const void *a, const void *b, void *context)	compare,
		void *	context
	)

Sort array elements using comparison function.

Parameters

arr	Array to sort in-place (must not be NULL)
compare	Comparison function (must not be NULL)
context	Optional context passed to comparison function (can be NULL)

Note

Comparison function signature: int (compare)(const void a, const void* b, void* context)

Should return <0 if a < b, 0 if a == b, >0 if a > b

Uses standard qsort algorithm

int compare_ints(const void* a, const void* b, void* ctx) {
    (void)ctx;
    int ia = *(const int*)a;
    int ib = *(const int*)b;
    return ia - ib;
}
 
da_sort(numbers, compare_ints, NULL);  // Sort ascending

da_swap()

DA_DEF void da_swap	(	da_array	arr,
		int	i,
		int	j
	)

Swaps two elements at the specified indices.

Parameters

arr	Array to modify (must not be NULL)
i	First index (must be >= 0 and < length)
j	Second index (must be >= 0 and < length)

Note

Asserts on out-of-bounds indices

No-op if i == j

da_swap(arr, 0, 2);  // Swap first and third elements

da_trim()

DA_DEF void da_trim	(	da_array	arr,
		int	new_capacity
	)

Reduces the array's allocated capacity to a specific size.

Parameters

arr	Array to modify (must not be NULL)
new_capacity	New capacity for the array (must be >= length)

Note

Only reduces capacity, never increases

Useful for memory optimization after removing many elements

Asserts if new_capacity < current length

Asserts on allocation failure

da_array arr = DA_CREATE(int, 1000);  // capacity = 1000
// ... add 50 elements, remove 30, now length = 20
da_trim(arr, 30);  // capacity = 30, saves memory