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)
#define	saSortCustom(handle, cmp, ctx, ...)    _saSortCustom(SAHANDLE(handle), cmp, ctx, opt_flags(__VA_ARGS__))

Typedefs
typedef intptr(*	saCmpFunc) (stype st, stgeneric gen1, stgeneric gen2, flags_t flags, void *ctx)

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 667 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 561 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 594 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 628 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 510 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 527 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 460 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, _SL("long string..."));
saPushC(&arr, string, &str);  // str is now NULL/invalid

Definition at line 486 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 690 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 714 of file sarray.h.

saSortCustom

#define saSortCustom	(		handle,
			cmp,
			ctx,
			...
	)		_saSortCustom(SAHANDLE(handle), cmp, ctx, opt_flags(__VA_ARGS__))

void saSortCustom(sa_type *handle, saCmpFunc cmp, void *ctx, [flags])

Sorts the array in-place using a caller-supplied comparison function

Uses the same quicksort implementation as saSort(), but orders elements by the given comparator rather than the element type's built-in comparison. The comparator receives the context pointer and flags unchanged on every call, so ordering state (sort direction, key selection, collation rules) can be passed without globals.

Unlike saSort(), this clears the SA_Sorted flag: a custom ordering is generally not the element type's canonical order, and saFind()'s binary search and sorted insertion both assume canonical order. Call saSort(handle, true) if the sorted invariant is needed again afterwards.

Parameters

handle	Pointer to the array to sort
cmp	Comparison function used to order elements
ctx	Context pointer passed through to every comparison (may be NULL)
...	(flags) Optional: flags passed through to every comparison, such as ST_CaseInsensitive

Safe to call with NULL or empty arrays.

Example:

static intptr cmpInt(stype st, stgeneric g1, stgeneric g2, flags_t flags, void *ctx)
{
    bool desc = *(bool*)ctx;
    intptr ret = (intptr)g1.st_int32 - (intptr)g2.st_int32;
    return desc ? -ret : ret;
}
 
bool desc = true;
saSortCustom(&arr, cmpInt, &desc);   // sort descending

Definition at line 775 of file sarray.h.

Typedef Documentation

saCmpFunc

typedef intptr(* saCmpFunc) (stype st, stgeneric gen1, stgeneric gen2, flags_t flags, void *ctx)

Custom comparison function for saSortCustom()

Mirrors the stype cmp operation (stCmpFunc) with an additional caller-supplied context pointer. Elements are passed as stgeneric values just as they would be to a type's own comparison operation, so they are unpacked through the matching stgeneric union member (gen1.st_int32, gen1.st_string, etc).

Parameters

st	Type descriptor for both values (the array's element type)
gen1	First value
gen2	Second value
flags	Flags passed to saSortCustom(), forwarded unchanged. ST_Equality is never passed, as sorting always requires full ordering
ctx	Context pointer passed to saSortCustom(), forwarded unchanged

Returns

Negative if gen1 < gen2, zero if equal, positive if gen1 > gen2

Definition at line 730 of file sarray.h.