Array Operations

Macros
#define	saPush(handle, type, elem, ...)    _saPush(SAHANDLE(handle), stCheckedArg(type, elem), opt_flags(__VA_ARGS__))
#define	saPushC(handle, type, elem, ...)
#define	saPopPtr(handle)   _saPopPtr(SAHANDLE(handle), -1)
#define	saPopPtrI(handle, idx)   _saPopPtr(SAHANDLE(handle), idx)
#define	saFind(ref, type, elem, ...)    _saFindChecked(SAREF(ref), stCheckedArg(type, elem), opt_flags(__VA_ARGS__))
#define	saFindRemove(handle, type, elem, ...)    _saFindRemoveChecked(SAHANDLE(handle), stCheckedArg(type, elem), opt_flags(__VA_ARGS__))
#define	saInsert(handle, idx, type, elem)    _saInsertChecked(SAHANDLE(handle), idx, stCheckedArg(type, elem))
#define	saExtract(handle, idx, type, elem_copy_out, ...)
#define	saRemove(handle, idx, ...)    _saExtractChecked(SAHANDLE(handle), idx, stType(none), NULL, opt_flags(__VA_ARGS__))
#define	saSort(handle, keep)   _saSort(SAHANDLE(handle), keep)

Detailed Description

Operations for adding, searching, inserting, removing, and sorting elements

Macro Definition Documentation

saExtract

#define saExtract	(		handle,
			idx,
			type,
			elem_copy_out,
			...
	)

Value:

    _saExtractChecked(SAHANDLE(handle),                     \
                      idx,                                  \
                      stCheckedPtrArg(type, elem_copy_out), \
                      opt_flags(__VA_ARGS__))

bool saExtract(sa_type *handle, int32 idx, type, *elem_copy_out, [flags])

Removes an element at the specified index and optionally extracts its value

The element is removed from the array. If elem_copy_out is provided, the value is copied out before removal. Otherwise the element is destroyed. Negative indices count from the end (-1 is the last element).

Parameters

handle	Pointer to the array
idx	Index of element to remove
type	Runtime type of the element, or 'none' to just destroy it
elem_copy_out	Pointer to receive a copy of the element, or NULL to destroy it
...	(flags) Optional: SA_Fast - Swap with last element for O(1) removal (disrupts order) Not valid for sorted arrays

Returns

true if the element was removed, false if array is NULL or index is invalid

Example:

int32 val;
if (saExtract(&arr, 5, int32, &val)) {
    // val contains the removed element
}

Definition at line 680 of file sarray.h.

saFind

#define saFind	(		ref,
			type,
			elem,
			...
	)		_saFindChecked(SAREF(ref), stCheckedArg(type, elem), opt_flags(__VA_ARGS__))

int32 saFind(sa_type ref, type, elem, [flags])

Searches for an element in the array

Uses linear search for unsorted arrays (O(n)) or binary search for sorted arrays (O(log n)). Comparison is performed according to the element type's comparison semantics.

Parameters

ref	The array to search (passed by value)
type	Runtime type of the element
elem	Element value to search for
...	(flags) Optional: SA_Inexact - For sorted arrays, return insertion point if not found

Returns

Index of the found element, or -1 if not found. If SA_Inexact is set on a sorted array, returns the index where the element would be inserted even if not found (never returns -1)

Example:

int32 idx = saFind(arr, int32, 42);
if (idx >= 0) {
    // found at arr.a[idx]
}

Definition at line 569 of file sarray.h.

saFindRemove

#define saFindRemove	(		handle,
			type,
			elem,
			...
	)		_saFindRemoveChecked(SAHANDLE(handle), stCheckedArg(type, elem), opt_flags(__VA_ARGS__))

bool saFindRemove(sa_type *handle, type, elem, [flags])

Searches for an element and removes it if found

Combines find and remove operations into a single call. The element is properly destroyed (unless SA_Ref was used).

Parameters

handle	Pointer to the array
type	Runtime type of the element
elem	Element value to search for and remove
...	(flags) Optional: SA_Fast - Use fast removal (swap with last element, disrupts order) Not valid for sorted arrays

Returns

true if the element was found and removed, false if not found or array is NULL

Example:

if (saFindRemove(&arr, int32, 42)) {
    // Element was found and removed
}

Definition at line 605 of file sarray.h.

saInsert

#define saInsert	(		handle,
			idx,
			type,
			elem
	)		_saInsertChecked(SAHANDLE(handle), idx, stCheckedArg(type, elem))

int32 saInsert(sa_type *handle, int32 idx, type, elem)

Inserts an element at the specified index

All elements at or after the index are shifted right to make room. The element is copied according to its type semantics. Negative indices count from the end (-1 is after the last element).

Parameters

handle	Pointer to the array (must already be initialized)
idx	Index where element should be inserted (0 to count inclusive)
type	Runtime type of the element
elem	Element value to insert

Returns

The index where the element was inserted

Note: Inserting into a sorted array clears the SA_Sorted flag as it may violate sort order. Use saPush for sorted arrays to maintain order.

Example:

saInsert(&arr, 0, int32, 42);  // Insert at beginning
saInsert(&arr, -1, int32, 17); // Insert at end

Definition at line 641 of file sarray.h.

saPopPtr

#define saPopPtr

(

handle

)

_saPopPtr(SAHANDLE(handle), -1)

void *saPopPtr(sa_type *handle)

Removes and returns the last element without calling its destructor

Transfers ownership of the element to the caller. The destructor is NOT called, so the caller is responsible for managing the returned value. Only valid for pointer-type or object-type arrays.

Parameters

handle

Pointer to the array

Returns

Pointer to the removed element, or NULL if array is empty/NULL

Example:

SomeObj *obj = saPopPtr(&arr);  // Ownership transferred
// use obj...
objRelease(&obj);  // Caller must destroy

Definition at line 518 of file sarray.h.

saPopPtrI

#define saPopPtrI	(		handle,
			idx
	)		_saPopPtr(SAHANDLE(handle), idx)

void *saPopPtrI(sa_type *handle, int32 idx)

Removes and returns the element at the specified index without calling its destructor

Like saPopPtr but for an arbitrary index. Negative indices count from the end (-1 is last). Transfers ownership to the caller.

Parameters

handle	Pointer to the array
idx	Index of element to remove

Returns

Pointer to the removed element, or NULL if array is empty/NULL

Example:

void *elem = saPopPtrI(&arr, 5);  // Remove element at index 5

Definition at line 535 of file sarray.h.

saPush

#define saPush	(		handle,
			type,
			elem,
			...
	)		_saPush(SAHANDLE(handle), stCheckedArg(type, elem), opt_flags(__VA_ARGS__))

int32 saPush(sa_type *handle, type, elem, [flags])

Appends an element to the end of the array (or inserts in sorted position)

The element is copied according to its type semantics. For strings and objects, references are properly managed. The array is automatically initialized if NULL and grown if needed.

Parameters

handle	Pointer to the array (can be a valid pointer to a NULL array)
type	Runtime type of the element (must match array type if already initialized)
elem	Element value to push
...	(flags) Optional: SA_Unique - Don't insert if element already exists (requires equality check)

Returns

Index where the element was inserted, or -1 if SA_Unique prevented insertion

For sorted arrays, the element is inserted at the correct position to maintain order.

Example:

sa_int32 arr = {0};
saPush(&arr, int32, 42);
saPush(&arr, int32, 17);

Definition at line 467 of file sarray.h.

saPushC

#define saPushC	(		handle,
			type,
			elem,
			...
	)

Value:

    _saPushPtr(SAHANDLE(handle),            \
               stCheckedPtrArg(type, elem), \
               opt_flags(__VA_ARGS__) | SAINT_Consume)

int32 saPushC(sa_type *handle, type, *elem, [flags])

Appends an element to the array, consuming/stealing it to avoid copying

This is an optimized version of saPush that takes ownership of the element instead of copying it. The source variable will be destroyed/cleared after this call. Requires that elem be a pointer.

This is useful for expensive-to-copy elements like long strings or when transferring ownership.

Parameters

handle	Pointer to the array
type	Runtime type of the element
elem	Pointer to element to consume (will be destroyed/cleared)
...	(flags) Optional: SA_Unique flag

Returns

Index where the element was inserted, or -1 if SA_Unique prevented insertion

Example:

string str = 0;
strDup(&str, _S"long string...");
saPushC(&arr, string, &str);  // str is now NULL/invalid

Definition at line 493 of file sarray.h.

saRemove

#define saRemove	(		handle,
			idx,
			...
	)		_saExtractChecked(SAHANDLE(handle), idx, stType(none), NULL, opt_flags(__VA_ARGS__))

bool saRemove(sa_type *handle, int32 idx, [flags])

Removes and destroys the element at the specified index

This is a convenience wrapper around saExtract that always destroys the element. Negative indices count from the end (-1 is the last element).

Parameters

handle	Pointer to the array
idx	Index of element to remove
...	(flags) Optional: SA_Fast for O(1) removal by swapping with last element

Returns

true if the element was removed, false if array is NULL or index is invalid

Example:

saRemove(&arr, 5);  // Remove element at index 5
saRemove(&arr, -1, SA_Fast);  // Remove last element (fast flag has no effect here)

Definition at line 703 of file sarray.h.

saSort

#define saSort	(		handle,
			keep
	)		_saSort(SAHANDLE(handle), keep)

void saSort(sa_type *handle, bool keep)

Sorts the array in-place using the element type's comparison function

Uses an optimized quicksort implementation with specializations for built-in types. After sorting, you can optionally set the SA_Sorted flag to enable binary search and maintain sort order on future insertions.

Parameters

handle	Pointer to the array to sort
keep	If true, sets SA_Sorted flag to maintain sort order on future operations. If false, just sorts without changing flags

Safe to call with NULL or empty arrays.

Example:

saSort(&arr, true);   // Sort and maintain sorted order
saSort(&arr, false);  // Just sort once

Definition at line 727 of file sarray.h.