Keyed Variant Lookup

Macros
#define	stvlFind(list, key, type, pvar)   _stvlFind(list, #key, stCheckedPtrArg(type, pvar))
#define	stvlFindPtr(list, key)   _stvlFindPtr(list, #key, stType(ptr))
#define	stvlFindObj(list, key, class)    objDynCast(class, (ObjInst*)_stvlFindPtr(list, #key, stType(object)))
#define	stvlFindVal(list, key, type)   (_stvlFindVal(list, #key, stType(type)).st_##type)
#define	stvlHasKey(list, key)   _stvlHasKey(list, #key)

Detailed Description

Lookup by key name rather than by type and position.

How this differs from stvlNext

stvlNext() scans forward from the cursor for the next variant of a type, advances past the match, and discards everything it skipped. That is the right contract for positional arguments, which arrive in a known order.

Keys exist precisely so that order does not matter, so stvlFind() does the opposite: it scans the whole list from the start and mutates nothing – the cursor is left exactly where it was.

The two address the same argument list without interfering, in either order:

void _myFunc(int count, stvar *args)
{
    stvlist list;
    stvlInit(&list, count, args);
 
    int32 timeout = 5000;                          // optional, keyed
    stvlFind(&list, timeout, int32, &timeout);
 
    string required;                               // required, positional
    if (stvlNext(&list, string, &required)) { ... }
}
 
myFunc(stvar(string, _SL("path")), stvark(timeout, int32, 250));

The two modes are disjoint: stvlNext() skips keyed variants entirely. A keyed argument is reachable only through stvlFind(). This is deliberate – if positional walking could consume keyed arguments, adding one to an existing call would silently shift every same-typed positional argument after it, which is exactly the fragility keys exist to remove. It also means a caller can add a keyed argument to a call without renumbering or reordering anything.

Duplicate keys

Duplicate keys in one argument list resolve to the first match. This cannot be caught at compile time; debug builds assert on it, release builds take the first. Do not rely on the behaviour.

Macro Definition Documentation

stvlFind

#define stvlFind	(		list,
			key,
			type,
			pvar
	)		_stvlFind(list, #key, stCheckedPtrArg(type, pvar))

bool stvlFind(stvlist *list, key, type, type *pvar)

Find a variant by key name and type, without disturbing the walker.

Scans the entire list from the beginning for a variant whose key matches key and whose type matches type, and copies its value to pvar. The cursor is not moved and the list is not modified.

The key is written as a bare token and stringized, matching stvark().

Parameters

list	Pointer to list walker (not modified)
key	Key name as a bare token (not a string literal)
type	Expected type name
pvar	Pointer to storage receiving the value

Returns

true if a matching keyed variant was found

Example:

int32 ms;
if (stvlFind(&list, timeout, int32, &ms)) { ... }

Definition at line 958 of file stvar.h.

stvlFindObj

#define stvlFindObj	(		list,
			key,
			class
	)		objDynCast(class, (ObjInst*)_stvlFindPtr(list, #key, stType(object)))

ClassName* stvlFindObj(stvlist *list, key, ClassName)

Find an object variant by key name and dynamic-cast it, without disturbing the walker.

As stvlFindPtr(), but restricted to object variants and passed through objDynCast, so the result is NULL unless the object is compatible with the named class.

Parameters

list	Pointer to list walker (not modified)
key	Key name as a bare token (not a string literal)
class	Target class name for dynamic cast

Returns

Typed object pointer, or NULL if not found or incompatible

Example:

Document *doc = stvlFindObj(&list, source, Document);

Definition at line 995 of file stvar.h.

stvlFindPtr

#define stvlFindPtr	(		list,
			key
	)		_stvlFindPtr(list, #key, stType(ptr))

void* stvlFindPtr(stvlist *list, key)

Find a pointer-typed variant by key name, without disturbing the walker.

As stvlFind() for pointer-like types (ptr, objects, and PassPtr types). Returns the stored pointer directly.

Parameters

list	Pointer to list walker (not modified)
key	Key name as a bare token (not a string literal)

Returns

Stored pointer, or NULL if no matching keyed variant exists

Example:

void *ctx = stvlFindPtr(&list, context);

Definition at line 976 of file stvar.h.

stvlFindVal

#define stvlFindVal	(		list,
			key,
			type
	)		(_stvlFindVal(list, #key, stType(type)).st_##type)

type stvlFindVal(stvlist *list, key, type)

Find a variant by key name and type, and return its value, without disturbing the walker.

As stvlFind(), but returns the value directly, or zero if there is no matching variant. Use stvlFind() when zero is a valid value and you need to tell it apart from a missing one. The value is borrowed from the list, as with stvlAt().

Parameters

list	Pointer to list walker (not modified)
key	Key name as a bare token (not a string literal)
type	Expected type name

Returns

The stored value, or zero if not found

Example:

strref host = stvlFindVal(&list, host, strref);

Definition at line 1017 of file stvar.h.

stvlHasKey

#define stvlHasKey	(		list,
			key
	)		_stvlHasKey(list, #key)

bool stvlHasKey(stvlist *list, key)

Test whether a keyed variant exists, regardless of its type.

Parameters

list	Pointer to list walker (not modified)
key	Key name as a bare token (not a string literal)

Returns

true if any variant in the list carries that key

Example:

if (stvlHasKey(&list, verbose)) { ... }

Definition at line 1031 of file stvar.h.