Overview

Core Concept

The stype system provides runtime type information through 32-bit type descriptors that encode type identity, size, and behavioral flags. This enables generic programming patterns similar to C++ templates while maintaining C compatibility and avoiding code bloat from template instantiation.

Type descriptors are created at compile-time through macro expansion, allowing the compiler to optimize away most overhead when types are known statically. When types must be determined at runtime (e.g., heterogeneous containers, variant types), the compact 32-bit descriptor provides efficient type identification and dispatch to appropriate operations.

Type Descriptor Format

A stype is a 32-bit value with the following layout:

Bits 0-7:   Type ID (identifies the specific type)
Bits 8-15:  Flags (behavioral attributes)
Bits 16-31: Size (storage size in bytes)

Type IDs are grouped into classes (integer, unsigned, float, pointer, CX types) to enable efficient categorization and default operation selection.

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 pointer)
• Special: opaque (custom structures), none (empty/void)

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

Usage Patterns

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

htInsert(&ht, string, _S"key", int32, 42);
// Expands to type descriptors + type-checked values

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

stgeneric val = stStored(elemType, &array[idx]);

Custom types via opaque(RealType) provide type-safe handling of structs:

saInit(&arr, opaque(MyStruct), 16);

Type Operations

The system provides function pointers for standard operations on types:

• dtor - Destructor (cleanup/free resources)
• cmp - Comparison (for sorting, equality)
• hash - Hash function (for hash tables)
• copy - Deep copy (reference counting for objects)
• convert - Type conversion (with range/precision checking)

Default implementations exist for built-in types. Custom types can override these through the STypeOps structure.

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:

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

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