carb::variant::Translator

Defined in carb/variant/VariantTypes.h

template<class T, class Enable = void>
struct Translator

Default implementation of a Translator type.

Translator structs provide a VTable and instruct the Variant system in how the VariantData::data member is to be interpreted for conversion to-and-from C++ types.

All Translator specializations must provide three functions:

  • RString type() const noexcept - Retrieves the registered name of the type known to IVariant via IVariant::registerType(). The v-table will be looked up via translate().

  • void* data(T&&) const noexcept - This function must convert the given value to a void* representation that is stored in the VariantData struct. If this function allocates memory it should be from carb::allocate() or originate within the plugin that contains the VTable::Destructor() function that will be freeing the memory.

  • T value(void*) const noexcept - This function is the opposite of the data() function&#8212;it converts the void* value from VariantData::data and converts it back to type T.

Translator specializations are present for the following built-in types:

  • std::nullptr_t.

    • Does not convert to any other type.

    • Is only equal with other std::nullptr_t types.

  • bool

    • Can be convert to any integral type (will produce 0 or 1).

    • Will be equal with integer values of 0 or 1.

  • Integral types (8-, 16-, 32- and 64-bit; signed and unsigned).

    • Will convert to any other integral type as long as the value is representable in that type. For instance, a Variant(-1) would fail to convert to unsigned, and Variant(999) would fail to convert to uint8_t, but Variant(uint64_t(-1)) would convert just fine to int8_t.

    • Equality checks follow the same rules as conversion.

    • Not convertible to floating point due to potential data loss.

    • Convertible to bool only if the value is 0 or 1.

  • float and double

    • Will convert to each other, but will not convert to integral types due to potential data loss.

    • Equality checks follows conversion rules, but will compare as the larger type.

  • omni::string

    • Convertible to const char*, but this value must only be used transiently&#8212;it is equivalent to c_str() and follows the same rules for lifetime of the pointer from c_str().

    • Equality compares via operator == for omni::string, and comparable with [const] char*.

  • const char*

    • Stores the pointer, so memory lifetime must be longer than the Variant.

    • Accepts a char* but stored as a const char*; any attempts to convert to char* will fail.

    • Attempts to copy a Variant containing a const char* just copy the same pointer, so the lifetime guarantee must include these copies as well.

    • Comparable with omni::string.

  • dictionary::Item*

    • Stores the pointer, so memory lifetime must be longer than the Variant.

    • Copying the variant will trivially copy the pointer.

    • Comparison will trivially compare the pointer.

  • carb::Strong (Carbonite strong types)

    • Auto-converts to and from the underlying numeric type (i.e. int, size_t, etc.), so it will lose the type safety of the strong type.

    • Comparable with similar numeric types.

  • VariantArray* / VariantArrayPtr

    • Comparable only with other VariantArray types, by pointer value.

    • Hashes based on the pointer value, not the contained values.

    • Variants containing this type always hold a reference.

  • VariantMap* / VariantMapPtr

    • Comparable only with other VariantMap types, by pointer value.

    • Hashes based on the pointer value, not the contained values.

    • Variants containing this type always hold a reference.

  • RString / RStringU / RStringKey / RStringUKey

    • Types are comparable with other instances of the same type.

    • Key types are only comparable with Key types; RString and RStringKey will compare with RStringU and RStringKeyU respectively, as uncased comparisons.

    • Hashing is as by the getHash() function for each of the RString types.

    • RString and RStringU can be converted to const char* or omni::string as if by c_str().

    • RStringKey and RStringUKey can be converted to omni::string as if by toString().

Warning

The default template does not provide the above functions which will allow compile to fail for unrecognized types. Translations are available through specializations only.

Template Parameters

  • T – The type handled by the specialization.

  • Enable – A template parameter that can be used for SFINAE.