Overview

Core Concept

The stype system provides runtime type information through pointers to canonical STypeInfo descriptors. This enables generic programming patterns similar to C++ templates while maintaining C compatibility and avoiding code bloat from template instantiation.

Each type has exactly one canonical const STypeInfo in static storage. An stype value is simply a pointer to that descriptor - equality is pointer equality (via stEq, which canonicalizes before comparing). Type names like int32, string, and opaque(MyStruct) expand to pointers to their canonical descriptors through the stType() macro.

Type Descriptor

stype is a const STypeInfo*. The STypeInfo struct carries all information about a type in one place:

typedef struct STypeInfo {
    uint32 id;                      // hierarchical type class | subtype | discriminant
    uint16 size;                    // storage size in bytes
    uint16 flags;                   // STypeFlag_Object, STypeFlag_PassPtr,
                                     // STypeFlag_Temporary
    STypeOps ops;                   // embedded operations: dtor, cmp, hash, copy, convert
} STypeInfo;

Type ID Structure

The id field uses a hierarchical bit-field:

• Bits 31–16: Class - STCLASS_BASIC, STCLASS_CX, STCLASS_DYNAMIC, STCLASS_USER
• Bits 15–8: Subtype - for BASIC: STST_INT, STST_UINT, STST_FLOAT, STST_PTR; for CX: STST_OPAQUE, STST_MISC, STST_OBJ, STST_CONTAINER
• Bits 7–0: Discriminant - often sizeof(type) for primitives, sequential for CX types

Use st->id to inspect the type class. Compare against stTypeId(name) constants (e.g., stTypeId(int32), stTypeId(sarray)) for type-specific dispatch.

Supported Types

Primitive Types:

• Integers: int8, int16, int32, int64, intptr
• Unsigned: uint8, uint16, uint32, uint64, uintptr, bool, size
• Floating point: float32, float64
• Pointer: ptr (generic void*)
• Special: opaque (POD blob), none (empty/void sentinel)

CX Framework Types:

• string, strref - Copy-on-write strings
• object, weakref - Object system handles
• suid - 128-bit unique identifiers
• stvar - Type-tagged variant containers
• sarray - Dynamic arrays
• hashtable - Hash tables
• closure, cchain - Function closures

Object Classes (cxautogen):

Object classes generated by the cxautogen tool can be used as type names directly in container operations. MyClass is a valid type name for saInit, saPush, htInsert, and similar APIs. The named class type is an alias for object, so all class instances share the same underlying descriptor and containers remain polymorphic: a container initialized with MyBase will accept MyDerived instances, since the type identity is the same throughout the object hierarchy.

When a named class is used at an insertion site, the argument is checked against the expected class at compile time (and in debug builds at runtime). Compare:

// Generic object — any object instance accepted:
sa_object arr;
saInit(&arr, object, 16);
saPush(&arr, object, inst);
 
// Named class — instance checked against MyClass:
sa_object arr;
saInit(&arr, MyClass, 16);
saPush(&arr, MyClass, inst);

The storage type for a named class (SType_MyClass) is MyClass*, so accessors such as hteVal return the correct pointer type without an explicit cast.

Canonical Descriptors and the Type Registry

All built-in type descriptors are static const STypeInfo with STypeFlag_Temporary clear. For dynamic types - plain opaque(T) with no custom ops, or parameterized container types like an sarray of a specific element - the descriptor is constructed as a compound literal with STypeFlag_Temporary set. When such a descriptor is passed to a container init function, stCanonical() is called:

• If Temporary is clear, the descriptor is already canonical - returned as-is.
• If Temporary is set, _stGetCanonical() looks up or inserts the descriptor in the global type registry (keyed by id + size), returns the canonical heap-allocated copy with Temporary cleared.

After the first use, all subsequent calls with equivalent parameters resolve to the same pointer, so type identity is pointer equality everywhere.

For custom types with user-defined ops, the correct pattern is a global or file-static canonical descriptor - see Custom Type Integration.

Usage Patterns

Generic function parameters use macros that expand to type-value pairs:

htInsert(&ht, string, _SL("key"), int32, 42);
// Expands to stType(string)/stArg(string,...) + stType(int32)/stArg(int32,...)

Stored values in containers use stStored() to load from raw memory:

stgeneric val = stStored(hdr->elemtype, ELEMPTR(hdr, i));

Type identity checks use stEq() or direct pointer comparison on known-canonical types:

if (stEq(saElemType(arr), stType(int32))) { ... }
if (v.type == stType(string)) { ... }   // safe when v.type came from stCanonical

Plain opaque (POD blob, no custom ops):

sa_MyPOD arr;
saInit(&arr, opaque(MyPOD), 16);    // Temporary; type registry provides canonical pointer
saPush(&arr, opaque, val);          // opaque push: size checked against container's elem type

Type Operations

STypeInfo embeds an STypeOps struct with seven optional function pointers:

• dtor - Destructor (cleanup/release resources). NULL = trivial (no-op).
• cmp - Comparison (for sorting, equality). NULL = memcmp fallback.
• hash - Hash function. NULL = generic byte-hash fallback.
• copy - Deep copy (ref-count bump for managed types). NULL = memcpy fallback.
• convert - Type conversion with range/precision checking. NULL = cannot convert.
• serialize - Write the value to a serialization backend. NULL = handled by the traverser.
• deserialize - Read the value from a serialization backend. NULL = handled by the traverser.

Type Safety

Compile-time checking is enforced through macro expansion:

• Type names must match expected patterns (verified at preprocessing)
• Values are checked against type structure members (compile-time type validation)
• Containers verify element types on access

Runtime checking occurs when:

• Converting between types (with range/precision validation)
• Accessing heterogeneous containers
• Comparing types for compatibility

Variant Types (stvar)

The stvar structure combines a value with its type descriptor for runtime polymorphism. Access the descriptor through stvarType() (or check it with stvarIs()) rather than reading the _type field directly - its low bit is an ownership tag, so the raw field is not a usable stype pointer.

stvar v = stvar(int32, 42);
if (stvarIs(&v, int32)) {
    int32 val = v.data.st_int32;
}

This is the foundation for type-safe variadic arguments and heterogeneous collections throughout the framework.