Variant List Walking

Modules
	Keyed Variant Lookup

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)))
#define	stvlAt(list, idx, type)   (_stvlAt((list), (idx), stType(type)).st_##type)
#define	stvlAtPtr(list, idx)   (_stvlAt((list), (idx), stType(ptr)).st_ptr)
#define	stvlAtObj(list, idx, class)    objDynCast(class, (ObjInst*)_stvlAt((list), (idx), stType(object)).st_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, _SL("test")), stvar(object, myObj));

Macro Definition Documentation

stvlAt

#define stvlAt	(		list,
			idx,
			type
	)		(_stvlAt((list), (idx), stType(type)).st_##type)

type stvlAt(stvlist *list, int idx, type)

Read a variant by position, without disturbing the walker.

Positions count from 0 and skip keyed variants, the same ones stvlNext() skips, so adding a keyed argument never shifts a positional one. The value is borrowed from the list: strings and objects read this way must not be destroyed or released. A type too large to fit in a variant, such as suid, comes back as a pointer to the stored value.

Use this where the position of each variant is fixed, such as the captured variables of a closure. A position that is out of range or holds a different type is a programming error, and yields zero. For optional arguments, use stvlNext(), which reports whether it found one.

Parameters

list	Pointer to list walker (not modified)
idx	Position among the unkeyed variants
type	Type of the variant at that position

Returns

The stored value

Example:

int32 limit = stvlAt(cvars, 1, int32);
SUID *id    = stvlAt(cvars, 2, suid);

Definition at line 865 of file stvar.h.

stvlAtObj

#define stvlAtObj	(		list,
			idx,
			class
	)		objDynCast(class, (ObjInst*)_stvlAt((list), (idx), stType(object)).st_object)

ClassName* stvlAtObj(stvlist *list, int idx, ClassName)

Read an object variant by position and dynamic-cast it. As stvlAt(); the reference is borrowed.

Parameters

list	Pointer to list walker (not modified)
idx	Position among the unkeyed variants
class	Target class name for dynamic cast

Returns

Typed object pointer, or NULL if incompatible

Definition at line 885 of file stvar.h.

stvlAtPtr

#define stvlAtPtr	(		list,
			idx
	)		(_stvlAt((list), (idx), stType(ptr)).st_ptr)

void* stvlAtPtr(stvlist *list, int idx)

Read a ptr variant by position. As stvlAt().

Parameters

list	Pointer to list walker (not modified)
idx	Position among the unkeyed variants

Returns

The stored pointer

Definition at line 874 of file stvar.h.

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, _SL("test")));
 
stvlist list;
stvlInitSA(&list, args);
// Walk the list
saDestroy(&args);

Definition at line 737 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 772 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 815 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 793 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);