Variant Types

Modules
	Variant Creation
	Variant Lifecycle
	Variant Type Checking and Access
	Variant List Walking

Detailed Description

Type-tagged variant containers providing runtime polymorphism and type-safe variadic function arguments without exposing raw va_list semantics.

Concept

The stvar structure combines an stype descriptor with a typed value container (stgeneric), enabling a single variable to hold values of different types while preserving type information at runtime. This is the foundation for:

• Type-safe variadic functions: Replace C's unsafe va_list with arrays of stvar
• Heterogeneous containers: Store mixed types in a single array or collection
• Dynamic dispatch: Route operations based on runtime type information
• Generic algorithms: Process values without compile-time type knowledge

Lifetime and Scope

Variants created with stvar() use C99 compound literals to create stack-allocated temporaries. These temporaries have automatic storage duration limited to the enclosing block scope:

void processVariants(int count, stvar *vars);
 
void example() {
    // Temporary variants valid until end of function
    processVariants(3, (stvar[]){
        stvar(int32, 42),
        stvar(string, _SL("hello")),
        stvar(float64, 3.14)
    });
    // Temporaries destroyed here
}

For persistent variants, use explicit allocation or embed in structures. Duplicate a temporary into a persistent variant with stvarCopy() (which assumes an uninitialized destination), or replace the contents of an already-initialized variant with stvarSet() (which destroys any existing value first). Both deep-copy oversized (suid, opaque, struct) values into storage the variant owns, so the persistent copy stays valid after the temporary goes out of scope:

stvar persistent;
stvarCopy(&persistent, stvar(int32, 42));   // destination was uninitialized
// ... use persistent ...
stvarSet(&persistent, string, _SL("now a string"));   // replaces the int32
// ... use persistent ...
stvarDestroy(&persistent);

Usage Patterns

Creating variants:

stvar v1 = stvar(int32, 42);
stvar v2 = stvar(string, _SL("text"));
stvar empty = stvNone;

Type checking and access:

if (stvarIs(&v1, int32)) {
    int32 val = v1.data.st_int32;
}
 
string s = stvarString(&v2);  // Returns NULL if not a string

Variadic function pattern:

// Internal function taking count and variant array
void _myFunc(int count, stvar *args) {
    stvlist list;
    stvlInit(&list, count, args);
 
    int32 num;
    string str;
    if (stvlNext(&list, int32, &num) && stvlNext(&list, string, &str)) {
        // Process typed arguments
    }
}
 
// Macro wrapper to automatically fill count and create array
#define myFunc(...) _myFunc(count_macro_args(__VA_ARGS__), (stvar[]){__VA_ARGS__})
 
// Usage - caller just passes typed arguments directly
myFunc(stvar(int32, 10), stvar(string, _SL("data")));