Array Lifecycle & Size Management

Macros
#define	saInit(out, type, capacity, ...)    _saInit(SAHANDLE(out), stFullType(type), capacity, false, opt_flags(__VA_ARGS__))
#define	saTryInit(out, type, capacity, ...)    _saInit(SAHANDLE(out), stFullType(type), capacity, true, opt_flags(__VA_ARGS__))
#define	saDestroy(handle)   _saDestroy(SAHANDLE(handle))
#define	saReserve(handle, capacity)   _saReserve(SAHANDLE(handle), capacity, true)
#define	saShrink(handle, capacity)   _saShrink(SAHANDLE(handle), capacity)
#define	saSetSize(handle, size)   _saSetSize(SAHANDLE(handle), size)
#define	saClear(handle)   _saClear(SAHANDLE(handle))

Detailed Description

Array creation, destruction, and capacity/size management operations

Macro Definition Documentation

saClear

#define saClear

(

handle

)

_saClear(SAHANDLE(handle))

void saClear(sa_type *handle)

Removes all elements from the array and sets size to 0

All elements are properly destroyed (unless SA_Ref was used). The allocated capacity is preserved. Safe to call with NULL or uninitialized arrays.

Parameters

handle

Pointer to the array

Example:

saClear(&arr);  // Remove all elements but keep capacity

Definition at line 427 of file sarray.h.

saDestroy

#define saDestroy

(

handle

)

_saDestroy(SAHANDLE(handle))

void saDestroy(sa_type *handle)

Destroys a dynamic array and frees all associated memory

All elements are properly destroyed according to their type (unless SA_Ref was used). Sets handle->a to NULL after destruction. Safe to call with NULL or uninitialized arrays.

Parameters

handle

Pointer to the array

Example:

saDestroy(&arr);

Definition at line 348 of file sarray.h.

saInit

#define saInit	(		out,
			type,
			capacity,
			...
	)		_saInit(SAHANDLE(out), stFullType(type), capacity, false, opt_flags(__VA_ARGS__))

bool saInit(sa_type *out, type, int32 capacity, [flags])

Initializes a new dynamic array with the specified element type

Parameters

out	Pointer to the sarray to initialize
type	Runtime type for elements (e.g., int32, string, ptr, object, etc.)
capacity	Initial capacity (will be clamped to at least 1, use 0 for default of 8)
...	(flags) Optional combination of SA_* flags: SA_Ref - Array references data without copying/destroying (pointer types only) SA_Sorted - Maintain sorted order with O(log n) search, O(n) insert SA_AutoShrink - Release memory when array shrinks SA_Grow(rate) - Growth rate: Normal, Aggressive, Slow, 100, 50, 25, Minimal

Returns

true (this version cannot fail and will runtime assert on allocation failure)

Example:

sa_int32 arr;
saInit(&arr, int32, 16);
saPush(&arr, int32, 42);
saDestroy(&arr);

Definition at line 318 of file sarray.h.

saReserve

#define saReserve	(		handle,
			capacity
	)		_saReserve(SAHANDLE(handle), capacity, true)

bool saReserve(sa_type *handle, int32 capacity)

Reserves space for at least the specified capacity

If the current capacity is less than requested, the array is expanded. The array size (number of elements) is not changed, only the allocated capacity.

Parameters

handle	Pointer to the array
capacity	Minimum capacity to ensure (use 0 for at least 1)

Returns

true on success, false on allocation failure

Example:

saReserve(&arr, 100);  // Ensure space for at least 100 elements

Definition at line 370 of file sarray.h.

saSetSize

#define saSetSize	(		handle,
			size
	)		_saSetSize(SAHANDLE(handle), size)

void saSetSize(sa_type *handle, int32 size)

Sets the array to exactly the specified size

If growing, new elements are zero-initialized. If shrinking, excess elements are properly destroyed. The capacity is automatically adjusted if needed.

Parameters

handle	Pointer to the array
size	New size for the array

Example:

saSetSize(&arr, 50);  // Array now has exactly 50 elements

Definition at line 410 of file sarray.h.

saShrink

#define saShrink	(		handle,
			capacity
	)		_saShrink(SAHANDLE(handle), capacity)

void saShrink(sa_type *handle, int32 capacity)

Reduces the array capacity to free unused memory

Shrinks the allocated capacity to the specified size, but never below the current element count. This is useful for reclaiming memory after removing many elements. Unlike saSetSize, this does not affect the number of elements in the array.

Parameters

handle	Pointer to the array
capacity	Desired capacity (use 0 for minimum of 1)

Example:

// After removing many elements:
saShrink(&arr, 15);           // Shrink but leave room for 15 elements
saShrink(&arr, 0);            // Shrink to minimum (current count or 1)

Definition at line 392 of file sarray.h.

saTryInit

#define saTryInit	(		out,
			type,
			capacity,
			...
	)		_saInit(SAHANDLE(out), stFullType(type), capacity, true, opt_flags(__VA_ARGS__))

bool saTryInit(sa_type *out, type, int32 capacity, [flags])

Same as saInit but can fail and return false if memory allocation fails

Parameters

out	Pointer to the sarray to initialize
type	Runtime type for elements
capacity	Initial capacity
...	(flags) Optional combination of SA_* flags

Returns

true on success, false on allocation failure

Definition at line 330 of file sarray.h.