Translator#

Fully qualified name: 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.

• Enum types (std::is_enum_v returns true).

  • Treated as their underlying integer type (see above).

  • NOTE: enum class types lose type safety since they are stored internally as their underlying type and no type checking is performed when reading the value out of the Variant.

• 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*.

• std::string

  • Internally stored as omni::string and converted to std::string when read, since std::string is not considered ABI stable.

  • 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 raw 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 pointers

  • 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.

  • Can be converted to bool as if by dictionary::IDictionary::getAsBool().

  • Can be converted to integer types as if by dictionary::IDictionary::getAsInt64(). If the result would not fit into the integer type, conversion fails.

  • Can be converted to float or double as if by dictionary::IDictionary::getAsFloat() or dictionary::IDictionary::getAsFloat64().

  • Can be converted to const char* if and only if the Item represents a string. NOTE however that this merely trivially copies the string pointer, so it is not recommended unless the lifetime of the Item is guaranteed.

  • Can be converted to omni::string or std::string as if by dictionary::IDictionary::getStringBuffer() or if that fails, dictionary::IDictionary::createStringBufferFromItemName().

  • Can be converted to VariantArray if dictionary::IDictionary::isAccessibleAsArray() returns true. This also enables conversion to standard library containers such as std::vector. The entries will be Variant of type dictionary::Item*

  • Items of type dictionary::ItemType::eDictionary can be converted to VariantMap. The key will be of type RStringKey. Array indexes will be Empty but will have a number component corresponding to the array index. The mapped value will be Variant of type dictionary::Item*.

• 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.

• std::vector / std::list / std::deque / std::set / std::unordered_set

  • Usable as long as the contained type has a Translator specialization.

  • Stored internally as a VariantArrayPtr (see above).

• std::map / std::unordered_map

  • Usable as long as the contained key and value types have Translator specializations.

  • Stored internally as a VariantMapPtr (see above).

• RString / RStringU / RStringKey / RStringUKey

  • RString Types are all comparable with each other. Non-Key types will promote to Key. If either type is Uncased, the other type is converted to Uncased before comparing.

  • RString can convert to RStringU, RStringUKey and RStringKey. If promoted to a Key, the number component is 0.

  • RStringU can convert to RStringUKey with a number component of zero.

  • RStringKey can convert to RStringUKey as via toUncased(). If the number component is zero it can also convert to RString and RStringU, otherwise the conversion to these types fails.

  • RStringUKey can convert to RStringU if the number component is zero, otherwise the conversion fails.

  • 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 with number components of zero can convert to const char* as if by .truncate().c_str(). If the number component is non-zero, conversion fails.

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

• carb::IObject* / carb::ObjectPtr

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

  • Hashes based on the pointer value.

  • Variants containing this type always hold a reference.

• Python types: If the carb.variant.python bindings are loaded, a type is registered that can store Python objects in Variant.

  • Will do a rich comparison with similar types. So a Python str will compare with Variant string types such as omni::string, [const] char* and std::string. Python numeric types will compare with Variant objects containing numeric types. Same with boolean types.

  • Variant::toString will attempt to convert the Python object to a string as by str().

  • Python types attempt to convert to their C++ types: str to Variant string types, Python numeric types to C++ numeric types, etc. A Python sequence object is convertible to VariantArray. A Python dict object is convertible to VariantMap.

  • C++ types are normally not convertible to Python types, however, carb.eventdispatcher.python bindings will perform some translation for events, essentially the reverse of the above list.

Warning

Type information for the underlying child class of IObject is not known. It is up to the caller to provide type safety.

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.