Variant List Walking

Data Structures
struct	stvlist

Macros
#define	stvlInitSA(list, vararray)   _stvlInitSA(list, (vararray).a)
#define	stvlNext(list, type, pvar)   _stvlNext(list, stCheckedPtrArg(type, pvar))
#define	stvlNextPtr(list)   _stvlNextPtr(list, stType(ptr))
#define	stvlNextObj(list, class)   objDynCast(class, (ObjInst*)_stvlNextPtr(list, stType(object)))

Typedefs
typedef struct stvlist	stvlist

Functions
void	stvlInit (stvlist *list, int count, stvar *vars)
void	stvlRewind (stvlist *list)

Detailed Description

Iterator pattern for processing arrays of variants with type-safe extraction.

The variant list walker provides a cursor-based interface for sequentially extracting typed values from an array of variants, commonly used for implementing type-safe variadic functions.

Example usage pattern:

// Internal implementation function
void _myFunc(int count, stvar *args) {
    stvlist list;
    stvlInit(&list, count, args);
 
    int32 id;
    string name;
    MyClass *obj;
 
    // Extract arguments in order by type
    if (stvlNext(&list, int32, &id) &&
        stvlNext(&list, string, &name) &&
        (obj = stvlNextObj(&list, MyClass))) {
        // Process typed arguments
    }
}
 
// Macro wrapper for convenient calling
#define myFunc(...) _myFunc(count_macro_args(__VA_ARGS__), (stvar[]){__VA_ARGS__})
 
// Usage
myFunc(stvar(int32, 123), stvar(string, _S"test"), stvar(object, myObj));

Macro Definition Documentation

stvlInitSA

#define stvlInitSA	(		list,
			vararray
	)		_stvlInitSA(list, (vararray).a)

void stvlInitSA(stvlist *list, sa_stvar vararray)

Initialize variant list walker from an sarray of variants.

Sets up the list structure to iterate over a dynamic array (sarray) of variants. The count is extracted automatically from the array metadata.

Parameters

list	Pointer to list structure to initialize
vararray	Dynamic array of variants (sa_stvar or similar)

Example:

sa_stvar args;
saInit(&args, stvar, 8);
saPush(&args, stvar, stvar(int32, 42));
saPush(&args, stvar, stvar(string, _S"test"));
 
stvlist list;
stvlInitSA(&list, args);
// Walk the list
saDestroy(&args);

Definition at line 481 of file stvar.h.

stvlNext

#define stvlNext	(		list,
			type,
			pvar
	)		_stvlNext(list, stCheckedPtrArg(type, pvar))

bool stvlNext(stvlist *list, type, type *pvar)

Extract next variant of specified type from list.

Searches forward from the current cursor position for the next variant matching the specified type. If found, copies the value to the output parameter, advances the cursor past that variant, and returns true. If no matching variant is found, returns false and leaves the cursor unchanged.

This allows flexible argument ordering in variadic functions where arguments can be provided in any order.

Parameters

list	Pointer to list walker
type	Type name to search for (e.g., int32, string)
pvar	Pointer to variable to receive the value

Returns

true if matching variant found and extracted, false otherwise

Example:

stvlist list;
stvlInit(&list, count, args);
 
int32 num;
string str;
if (stvlNext(&list, int32, &num)) {
    // Found int32, num now contains value
}
if (stvlNext(&list, string, &str)) {
    // Found string, str now contains value
}

Definition at line 516 of file stvar.h.

stvlNextObj

#define stvlNextObj	(		list,
			class
	)		objDynCast(class, (ObjInst*)_stvlNextPtr(list, stType(object)))

ClassName* stvlNextObj(stvlist *list, ClassName)

Extract next object variant from list with runtime type checking.

Searches for the next variant containing an object, performs a dynamic cast to the specified class type, advances the cursor, and returns the typed object pointer. Returns NULL if no compatible object is found.

Parameters

list	Pointer to list walker
class	Target class name for dynamic cast

Returns

Typed object pointer, or NULL if not found or incompatible

Example:

TestClass *obj = stvlNextObj(&list, TestClass);
if (obj) {
    // Use typed object
}

Definition at line 559 of file stvar.h.

stvlNextPtr

#define stvlNextPtr

(

list

)

_stvlNextPtr(list, stType(ptr))

void* stvlNextPtr(stvlist *list)

Extract next pointer-type variant from list.

Searches for the next variant containing a generic pointer (ptr type), advances the cursor, and returns the pointer value. Returns NULL if no pointer variant is found.

Parameters

list	Pointer to list walker

Returns

Pointer value, or NULL if not found

Example:

void *data = stvlNextPtr(&list);
if (data) {
    // Use generic pointer
}

Definition at line 537 of file stvar.h.

Typedef Documentation

stvlist

typedef struct stvlist stvlist

Variant list walker structure.

Maintains a cursor position for iterating through an array of variants. Initialized with stvlInit() or stvlInitSA(), then accessed with the various stvlNext*() functions.

Function Documentation

stvlInit()

void stvlInit	(	stvlist *	list,
		int	count,
		stvar *	vars
	)

void stvlInit(stvlist *list, int count, stvar *vars)

Initialize variant list walker from array and count.

Sets up the list structure to iterate over a raw array of variants, typically from a variadic function's argument list. Resets the cursor to the beginning.

Parameters

list	Pointer to list structure to initialize
count	Number of variants in array
vars	Pointer to variant array

Example:

void processVars(int count, stvar *args) {
    stvlist list;
    stvlInit(&list, count, args);
    // Use stvlNext() to walk the list
}

stvlRewind()

void stvlRewind

(

stvlist *

list

)

void stvlRewind(stvlist *list)

Reset list walker cursor to beginning.

Resets the cursor to position 0, allowing the same variant array to be walked multiple times or re-scanned for different argument combinations.

Parameters

list	Pointer to list walker to rewind

Example:

stvlist list;
stvlInit(&list, count, args);
 
// First pass: extract required args
stvlNext(&list, int32, &required);
 
// Second pass: scan for optional args
stvlRewind(&list);
stvlNext(&list, string, &optional);