Builder Lifecycle

Functions for creating and managing ArrayBuffer-style builders. More...

Functions
DA_DEF da_builder	da_builder_create (int element_size)
	Creates a new array builder for efficient construction.
DA_DEF da_array	da_builder_to_array (da_builder *builder, void(*retain_fn)(void *), void(*release_fn)(void *))
	Converts builder to a ref-counted array with exact capacity.
DA_DEF void	da_builder_clear (da_builder builder)
	Removes all elements from the builder.
DA_DEF void	da_builder_destroy (da_builder *builder)
	Destroys a builder and frees its memory.

Detailed Description

Functions for creating and managing ArrayBuffer-style builders.

Function Documentation

da_builder_clear()

DA_DEF void da_builder_clear

(

da_builder

builder

)

Removes all elements from the builder.

Parameters

builder

Builder to clear (must not be NULL)

Note

Sets length to 0 but preserves capacity

Allows reusing builder for multiple constructions

da_builder_clear(builder);
assert(da_builder_length(builder) == 0);

da_builder_create()

DA_DEF da_builder da_builder_create

(

int

element_size

)

Creates a new array builder for efficient construction.

Parameters

element_size

Size in bytes of each element (must be > 0)

Returns

New builder with length = 0 and capacity = 0

Note

Builders always use doubling growth strategy for fast construction

Not thread-safe

Use da_builder_to_array() to convert to ref-counted array

Asserts on allocation failure

da_builder builder = da_builder_create(sizeof(int));
DA_BUILDER_APPEND(builder, 42);
da_array arr = da_builder_to_array(&builder);

da_builder_destroy()

DA_DEF void da_builder_destroy

(

da_builder *

builder

)

Destroys a builder and frees its memory.

Parameters

builder

Pointer to builder pointer (will be set to NULL)

Note

Use this if you don't want to convert to da_array

Always sets *builder to NULL

da_builder builder = da_builder_create(sizeof(int));
// ... use builder ...
da_builder_destroy(&builder);  // builder becomes NULL

da_builder_to_array()

DA_DEF da_array da_builder_to_array	(	da_builder *	builder,
		void(*)(void *)	retain_fn,
		void(*)(void *)	release_fn
	)

Converts builder to a ref-counted array with exact capacity.

Parameters

builder	Pointer to builder pointer (will be set to NULL)
destructor	Optional destructor function for the resulting array (NULL if not needed)

Returns

New da_array with capacity = length (no wasted memory)

Note

Builder is consumed and *builder is set to NULL

Resulting array has ref_count = 1

Memory is reallocated to exact size for efficiency

Perfect for microcontroller memory optimization

da_builder builder = DA_BUILDER_CREATE(int);
DA_BUILDER_APPEND(builder, 42);
da_array arr = da_builder_to_array(&builder, NULL);  // Simple types
 
// For complex types:
da_array cells = da_builder_to_array(&builder, (void(*)(void*))cell_release);