carb::variant::VTable

struct VTable

A v-table definition for a variant type. Each registered type has a unique v-table pointer that is retrievable via IVariant::getVTable(). Each entry in the v-table is a function with a default behavior if nullptr.

Note

This class is applicable only to users of carb.variant.plugin that author a custom Translator class.

Warning

Functions in the v-table should not be called directly; the Variant wrapper class calls them through various traits functions.

Warning

All functions require that self->vtable->[function] is equal to the function called.

Public Members

uint32_t sizeOf

A member used as version control.

This member should be set to sizeof(VTable) for the version of the v-table that a module is built against.

RString typeName

Indicates the type name of the v-table.

Once registered with IVariant::registerType(), this name can be used to look up the type with IVariant::getVTable().

Warning

This must be a unique name within the running process and may not match any of the built-in type names.

void (*Destructor)(VariantData *self) noexcept

Used to destroy the VariantData::data member.

A nullptr destructor function indicates that no destruction needs to take place.

Param self: The VariantData to destroy. Can assume that self->vtable->Destructor is the same as the function called.

VariantData (*Copy)(const VariantData *self) noexcept

Called to create a functional copy of the given VariantData.

A nullptr function indicates that VariantData can be trivially copied.

Note

The resulting VariantData need not have the same v-table as self.

Param self: The VariantData to copy. Can assume that self->vtable->Copy is the same as the function called.
Return: A VariantData that is a functional copy of self. traits::equals() should be true for *self and the returned VariantData.

bool (*Equals)(const VariantData *self, const VariantData *other) noexcept

Called to test equality of *self with (possibly different type) *other.

A nullptr function indicates that a trivial comparison of the VariantData is performed (i.e. memcmp).

Warning

Generally speaking, order should not matter: assuming that lhs and rhs are both const VariantData* with non-null Equals, it should hold that lhs->vtable->Equals(lhs, rhs) should always equal rhs->vtable->Equals(rhs, lhs) regardless of their respective v-tables.

Param self: The VariantData performing the compare. Can assume that self->vtable->Equals is the same as the function called.
Param other: The same or a different VariantData to compare with self. May have a different vtable than self.
Return: true if the types are equal; false otherwise.

omni::string (*ToString)(const VariantData *self) noexcept

Called to render the VariantData as a string.

A nullptr function indicates that a string is produced that contains “<vtable pointer>:<data pointer>”.

Param self: The VariantData to render. Can assume that self->vtable->ToString is the same as the function called.
Return: A type-dependent printable string representing the type, useful for debugging.

bool (*ConvertTo)(const VariantData *self, const VTable *newtype, VariantData *out) noexcept

Called to attempt to convert self to a different type.

A nullptr function is the same as returning false.

Note

Generally speaking, Equals() and ConvertTo() should understand the same types.

Warning

If false is returned, out is in an undefined state. If and only if true is returned, traits::destruct() must be called at some later point on *out.

Param self: The VariantData performing the conversion. Can assume that self->vtable->ConvertTo is this same as the function called.
Param newtype: A v-table representing the type to attempt to convert to. If the function recognizes the given v-table (which should not be the same as self->vtable) and can convert to that type then the function should write to out and return true. If the v-table is not recognized, the function must return false.
Param out: If true is returned from the function, this must be a valid VariantData and must be later destroyed with traits::destruct(). If false is returned then the state of out is undefined. There is no requirement that out->vtable matches newtype if true is returned; it must merely be valid.
Return: true if and only if out contains a valid converted representation of self; false otherwise.

size_t (*Hash)(const VariantData *self) noexcept

Computes a hash of self.

A nullptr function casts self->data to a size_t for use as a hash.

Param self: The VariantData to hash. Can assume that self->vtable->Hash is the same as the function called.
Return: A value to use as a hash identifying *self.