Variant Lifecycle

Macros
#define	stvarSet(stv, type, val)   _stvarSet(stv, stCheckedArg(type, val))
#define	stvarSetK(stv, key, type, val)   _stvarSetK(stv, stCheckedArg(type, val), #key)

Functions
void	stvarDestroy (stvar *stv)
void	stvarCopy (stvar *dvar, stvar svar)

Detailed Description

Functions for managing variant lifetime and copying.

Macro Definition Documentation

stvarSet

#define stvarSet	(		stv,
			type,
			val
	)		_stvarSet(stv, stCheckedArg(type, val))

void stvarSet(stvar *stv, type, value)

Replace the contents of a variant with a new typed value.

Unlike stvarCopy (which assumes an uninitialized destination), stvarSet destroys any existing value first, then stores the new one. The variant must already be initialized (e.g. stvNone or a prior value). Oversized values (suid, opaque, struct) are deep-copied into storage the variant owns.

Parameters

stv	Pointer to variant to modify (must be initialized)
type	Type name (e.g. int32, string, suid)
val	Value of the specified type

Example:

stvar v = stvNone;
stvarSet(&v, int32, 42);
stvarSet(&v, string, _SL("hello"));   // previous int32 replaced safely
stvarDestroy(&v);

Definition at line 422 of file stvar.h.

stvarSetK

#define stvarSetK	(		stv,
			key,
			type,
			val
	)		_stvarSetK(stv, stCheckedArg(type, val), #key)

void stvarSetK(stvar *stv, key, type, value)

Replace the contents of a variant with a new typed value and attach a key name.

As stvarSet, but also tags the variant with a key, written as a bare token and stringized exactly as in stvark(). Plain stvarSet clears any existing key, on the grounds that a stale key on a new value is worse than no key at all – so use this form when replacing the value of a keyed variant.

Parameters

stv	Pointer to variant to modify (must be initialized)
key	Key name as a bare token (not a string literal)
type	Type name (e.g. int32, string, suid)
val	Value of the specified type

Example:

stvar v = stvNone;
stvarSetK(&v, host, string, _SL("web01"));
stvarDestroy(&v);

Definition at line 444 of file stvar.h.

Function Documentation

stvarCopy()

void stvarCopy ( stvar *  dvar, stvar  svar  )

inline

void stvarCopy(stvar *dest, stvar source)

Copy a variant to another variant.

Copies the type descriptor, the value, and any key name, performing appropriate operations for the contained type (incrementing reference counts for objects, duplicating strings, etc.). The destination variant should be uninitialized or previously destroyed to avoid leaking resources.

The key name is pointer-copied, not duplicated – which is why keys are required to have program lifetime. A copied variant may outlive the call that created it.

Parameters

dvar	Pointer to destination variant (overwritten)
svar	Source variant to copy (passed by value)

Example:

stvar original = stvar(string, _SL("text"));
stvar copy;
stvarCopy(&copy, original);
// Both variants now reference the string (refcount incremented)
stvarDestroy(&copy);

Definition at line 492 of file stvar.h.

References stvarType().

stvarDestroy()

void stvarDestroy ( stvar *  stv )

inline

void stvarDestroy(stvar *stv)

Destroy a variant and release its resources.

Invokes the type-appropriate destructor on the contained value (e.g., decrements reference counts for objects, frees strings) and resets the type to none. After destruction, the variant is in a valid but empty state and can be safely destroyed again or reassigned.

Parameters

stv	Pointer to variant to destroy

Example:

stvar v;
stvarCopy(&v, stvar(string, _SL("hello")));
// ... use v ...
stvarDestroy(&v);  // Releases string reference

Definition at line 464 of file stvar.h.