VTable

Fully qualified name: carb::variant::VTable

Defined in carb/variant/VariantTypes.h

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 the same as ConvertTo.

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.

bool (*ConvertFrom)(const VTable *desired, VariantData *out, const VariantData *from) noexcept

Called to attempt to convert to desired from from.

A nullptr function is the same as returning false.

If ConvertFrom recognizes the v-table from->vtable and can convert to that type, then the function should write to out and return true. desired should never be the same as from->vtable.

Note

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

Note

In the past, only ConvertTo was supported. This function is typically only called if ConvertTo fails. If two types are mutually convertible via their ConvertTo methods, they need not implement this function.

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 desired:

A v-table representing the type to attempt to convert to. ConvertFrom is the same as desired->ConvertFrom. Given this, desired can often be ignored.

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 desired if true is returned; it must merely be valid.

Param from:

The VariantData to convert from.

Return:

true if and only if out contains a valid converted representation of from; false otherwise.