Trait module

Cnx provides a simple way to create and utilize polymorphic interfaces via Trait objects. Trait objects are fat pointers, containing a pointer-to-self and a vtable pointer, that allow use of polymorphic interfaces explicitly (you operate via the Trait object), without the need for a type to carry its vtable in its definition, and without the need for heap allocation (in most cases). For specific examples of Trait objects in action, look into CnxFormat and its use through the Cnx IO, and Cnx's iterator categories.

A general example:

// declare a Trait `NumberGenerator` that requires the functions `generate` and `seed`
Trait(NumberGenerator,
      u32 (*const generate)(NumberGenerator* restrict self);
      void (*const seed)(NumberGenerator* restrict self, u32 seed););

typedef struct ExampleGenerator {
    u32 m_seed;
} ExampleGenerator;

u32 example_generate(NumberGenerator* restrict self) {
    let_mut _self = static_cast(ExampleGenerator*)(self->m_self);
    return _self->m_seed++;
}

void example_seed(NumberGenerator* restrict self, u32 seed) {
    let_mut _self = static_cast(ExampleGenerator*)(self->m_self);
    _self->m_seed = seed;
}

// Implement `NumberGenerator` for our `ExampleGenerator` type with the `example_generate`
// and `example_seed` functions.
// The names of the implementation functions do not have to stem from/build on/etc the names
// in the Trait definition, but it is good practice/convention to do so.
static maybe_unused ImplTraitFor(NumberGenerator,
                                 ExampleGenerator,
                                 example_generate,
                                 example_seed);
// a function that uses the `NumberGenerator` Trait as a parameter
u32 generate(NumberGenerator generator) {
    return trait_call(generate, generator);
}

void do_thing(void) {
    let_mut generator = (ExampleGenerator){.m_seed = 10;}
    // cast `generator` to its `NumberGenerator` implementation and pass that to `generate`
    let num = generate(as_trait(NumberGenerator, ExampleGenerator, generator));
}