xiiVariant is a class that can store different types of variables, which is useful in situations where it is not clear up front, which type of data will be passed around. More...

#include <Variant.h>

Classes
struct	StringWrapper
	helper struct to wrap a string pointer. More...

Public Types
using	Type = xiiVariantType

template<typename T>
using	TypeDeduction = xiiVariantTypeDeduction<T>

Public Member Functions
	xiiVariant ()
	Initializes the variant to be 'Invalid'.

	xiiVariant (const xiiVariant &other)
	Copies the data from the other variant.

	xiiVariant (xiiVariant &&other) noexcept
	Moves the data from the other variant.

	xiiVariant (const bool &value)

	xiiVariant (const xiiInt8 &value)

	xiiVariant (const xiiUInt8 &value)

	xiiVariant (const xiiInt16 &value)

	xiiVariant (const xiiUInt16 &value)

	xiiVariant (const xiiInt32 &value)

	xiiVariant (const xiiUInt32 &value)

	xiiVariant (const xiiInt64 &value)

	xiiVariant (const xiiUInt64 &value)

	xiiVariant (const float &value)

	xiiVariant (const double &value)

	xiiVariant (const xiiColor &value)

	xiiVariant (const xiiVec2 &value)

	xiiVariant (const xiiVec2d &value)

	xiiVariant (const xiiVec3 &value)

	xiiVariant (const xiiVec3d &value)

	xiiVariant (const xiiVec4 &value)

	xiiVariant (const xiiVec4d &value)

	xiiVariant (const xiiVec2I32 &value)

	xiiVariant (const xiiVec2I64 &value)

	xiiVariant (const xiiVec3I32 &value)

	xiiVariant (const xiiVec3I64 &value)

	xiiVariant (const xiiVec4I32 &value)

	xiiVariant (const xiiVec4I64 &value)

	xiiVariant (const xiiVec2U32 &value)

	xiiVariant (const xiiVec2U64 &value)

	xiiVariant (const xiiVec3U32 &value)

	xiiVariant (const xiiVec3U64 &value)

	xiiVariant (const xiiVec4U32 &value)

	xiiVariant (const xiiVec4U64 &value)

	xiiVariant (const xiiQuat &value)

	xiiVariant (const xiiQuatd &value)

	xiiVariant (const xiiMat3 &value)
	constructors

	xiiVariant (const xiiMat3d &value)

	xiiVariant (const xiiMat4 &value)

	xiiVariant (const xiiMat4d &value)

	xiiVariant (const xiiTransform &value)

	xiiVariant (const xiiTransformd &value)

	xiiVariant (const char *value)

	xiiVariant (const xiiString &value)

	xiiVariant (const xiiUntrackedString &value)

	xiiVariant (const xiiStringView &value, bool bCopyString=true)

	xiiVariant (const xiiHashedString &value)

	xiiVariant (const xiiTempHashedString &value)

	xiiVariant (const xiiDataBuffer &value)

	xiiVariant (const xiiTime &value)

	xiiVariant (const xiiUuid &value)

	xiiVariant (const xiiAngle &value)

	xiiVariant (const xiiAngled &value)

	xiiVariant (const xiiColorGammaUB &value)

	xiiVariant (const xiiVariantArray &value)

	xiiVariant (const xiiVariantDictionary &value)

	xiiVariant (const xiiTypedPointer &value)

	xiiVariant (const xiiTypedObject &value)

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::CustomTypeCast, xiiInt32 > = 0>
	xiiVariant (const T &value)

template<typename T>
	xiiVariant (const T *value)

	xiiVariant (void value, const xiiRTTI pType)
	Initializes to a TypedPointer of the given object and type.

void	CopyTypedObject (const void value, const xiiRTTI pType)
	Initializes to a TypedObject by cloning the given object and type.

void	MoveTypedObject (void value, const xiiRTTI pType)
	Initializes to a TypedObject by taking ownership of the given object and type.

	~xiiVariant ()
	If necessary, this will deallocate any heap memory that is not in use any more.

void	operator= (const xiiVariant &other)
	Copies the data from the other variant into this one.

void	operator= (xiiVariant &&other) noexcept
	Moves the data from the other variant into this one.

template<typename T>
void	operator= (const T &value)
	Deduces the type of T and stores value.

bool	operator== (const xiiVariant &other) const
	Will compare the value of this variant to that of other.

template<typename T>
bool	operator== (const T &other) const
	See non-templated operator==.

bool	IsValid () const
	Returns whether this variant stores any other type than 'Invalid'.

bool	IsNumber () const
	Returns whether the stored type is numerical type either integer or floating point.

bool	IsFloatingPoint () const
	Returns whether the stored type is floating point (float or double).

bool	IsString () const
	Returns whether the stored type is a string (xiiString or xiiStringView).

bool	IsHashedString () const
	Returns whether the stored type is a hashed string (xiiHashedString or xiiTempHashedString).

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::DirectCast, xiiInt32 > = 0>
bool	IsA () const
	Returns whether the stored type is exactly the given type.

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::PointerCast, xiiInt32 > = 0>
bool	IsA () const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::TypedObject, xiiInt32 > = 0>
bool	IsA () const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::CustomTypeCast, xiiInt32 > = 0>
bool	IsA () const

Type::Enum	GetType () const
	Returns the exact xiiVariant::Type value.

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::DirectCast, xiiInt32 > = 0>
const T &	Get () const
	Returns the variants value as the provided type.

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::PointerCast, xiiInt32 > = 0>
T	Get () const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::TypedObject, xiiInt32 > = 0>
const T	Get () const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::CustomTypeCast, xiiInt32 > = 0>
const T &	Get () const

xiiTypedPointer	GetWriteAccess ()
	Returns an writable xiiTypedPointer to the internal data. If the data is currently shared a clone will be made to ensure we hold the only reference.

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::DirectCast, xiiInt32 > = 0>
T &	GetWritable ()

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::PointerCast, xiiInt32 > = 0>
T	GetWritable ()

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::CustomTypeCast, xiiInt32 > = 0>
T &	GetWritable ()

const void *	GetData () const
	Returns a const void* to the internal data. For TypedPointer and TypedObject this will return a pointer to the target object.

const xiiRTTI *	GetReflectedType () const
	Returns the xiiRTTI type of the held value. For TypedPointer and TypedObject this will return the type of the target object.

const xiiVariant	operator[] (xiiUInt32 uiIndex) const
	Returns the sub value at iIndex. This could be an element in an array or a member property inside a reflected type.

const xiiVariant	operator[] (StringWrapper key) const
	Returns the sub value with szKey. This could be a value in a dictionary or a member property inside a reflected type.

template<typename T>
bool	CanConvertTo () const
	Returns whether the stored type can generally be converted to the desired type.

bool	CanConvertTo (Type::Enum type) const
	Same as the templated CanConvertTo function.

template<typename T>
T	ConvertTo (xiiResult *out_pConversionStatus=nullptr) const
	Tries to convert the stored value to the given type. The optional status parameter can be used to check whether the conversion succeeded.

xiiVariant	ConvertTo (Type::Enum type, xiiResult *out_pConversionStatus=nullptr) const
	Same as the templated function.

xiiUInt64	ComputeHash (xiiUInt64 uiSeed=0) const
	Computes the hash value of the stored data. Returns uiSeed (unchanged) for an invalid Variant.

template<typename T>
XII_ALWAYS_INLINE void	InitShared (const T &value)

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::CustomTypeCast, xiiInt32 >>
XII_ALWAYS_INLINE	xiiVariant (const T &value)

template<typename T>
XII_ALWAYS_INLINE	xiiVariant (const T *value)

template<typename T>
XII_ALWAYS_INLINE void	operator= (const T &value)

template<typename T>
XII_FORCE_INLINE bool	operator== (const T &other) const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::DirectCast, xiiInt32 >>
XII_ALWAYS_INLINE bool	IsA () const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::DirectCast, xiiInt32 >>
XII_ALWAYS_INLINE const T &	Get () const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::PointerCast, xiiInt32 >>
XII_ALWAYS_INLINE T	Get () const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::TypedObject, xiiInt32 >>
XII_ALWAYS_INLINE const T	Get () const

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::DirectCast, xiiInt32 >>
XII_ALWAYS_INLINE T &	GetWritable ()

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::PointerCast, xiiInt32 >>
XII_ALWAYS_INLINE T	GetWritable ()

template<typename T>
XII_ALWAYS_INLINE bool	CanConvertTo () const

template<typename T>
XII_FORCE_INLINE void	InitInplace (const T &value)
	Private Methods.

template<typename T>
XII_FORCE_INLINE void	InitTypedObject (const T &value, xiiTraitInt< 0 >)

template<typename T>
XII_FORCE_INLINE void	InitTypedObject (const T &value, xiiTraitInt< 1 >)

Static Public Member Functions
template<typename Functor, class... Args>
static auto	DispatchTo (Functor &ref_functor, Type::Enum type, Args &&... args)
	This will call the overloaded operator() (function call operator) of the provided functor.

Friends
class	xiiVariantHelper

struct	CompareFunc

struct	GetTypeFromVariantFunc

Detailed Description

xiiVariant is a class that can store different types of variables, which is useful in situations where it is not clear up front, which type of data will be passed around.

The variant supports a fixed list of types that it can store (

See also: xiiVariant::Type). All types of 16 bytes or less in size can be stored without requiring a heap allocation. For larger types memory is allocated on the heap. In general variants should be used for code that needs to be flexible. Although xiiVariant is implemented very efficiently, it should be avoided to use xiiVariant in code that needs to be fast.

Constructor & Destructor Documentation

◆ xiiVariant()

XII_ALWAYS_INLINE xiiVariant::xiiVariant ( const xiiVariant & other )

Copies the data from the other variant.

Note: If the data of the variant needed to be allocated on the heap, it will be shared among variants. Thus, once you have stored such a type inside a variant, you can copy it to other variants, without introducing additional memory allocations.

Member Function Documentation

◆ CanConvertTo()

template<typename T>

bool xiiVariant::CanConvertTo ( ) const

Returns whether the stored type can generally be converted to the desired type.

This function will return true for all number conversions, as float / double / int / etc. can generally be converted into each other. It will also return true for all conversion from string to number types, and from all 'simple' types (not array or dictionary) to string.

Note: This function only returns whether a conversion between the stored TYPE and the desired TYPE is generally possible. It does NOT return whether the stored VALUE is indeed convertible to the desired type. For example, a string is generally convertible to float, if it stores a string representation of a float value. If, however, it stores anything else, the conversion can still fail.

The only way to figure out whether the stored data can be converted to some type, is to actually convert it, using ConvertTo(), and then to check the conversion status.

◆ ConvertTo()

template<typename T>

T xiiVariant::ConvertTo ( xiiResult * out_pConversionStatus = nullptr ) const

Tries to convert the stored value to the given type. The optional status parameter can be used to check whether the conversion succeeded.

When CanConvertTo() returns false, ConvertTo() will also always fail. However, when CanConvertTo() returns true, this is no guarantee that ConvertTo() will succeed. Conversion between numbers and to strings will generally succeed. However, converting from a string to another type can fail or succeed, depending on the exact string value.

◆ DispatchTo()

template<typename Functor, class... Args>

auto xiiVariant::DispatchTo	(	Functor &	ref_functor,
		Type::Enum	type,
		Args &&...	args )

static

This will call the overloaded operator() (function call operator) of the provided functor.

This allows to implement a functor that overloads operator() for different types and then call the proper version of that operator, depending on the provided runtime type. Note that the proper overload of operator() is selected by providing a dummy type, but it will contain no useful value. Instead, store the other necessary data inside the functor object, before calling this function. For example, store a pointer to a variant inside the functor object and then call DispatchTo to execute the function that will handle the given type of the variant.

◆ Get()

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::DirectCast, xiiInt32 > = 0>

const T & xiiVariant::Get ( ) const

Returns the variants value as the provided type.

Note: This function does not do ANY type of conversion from the stored type to the given type. Not even integer conversions! If the types don't match, this function will assert! So be careful to use this function only when you know exactly that the stored type matches the expected type.

Prefer to use ConvertTo() when you can instead.

◆ IsA()

template<typename T, typename std::enable_if_t< xiiVariantTypeDeduction< T >::classification==xiiVariantClass::DirectCast, xiiInt32 > = 0>

bool xiiVariant::IsA ( ) const

Returns whether the stored type is exactly the given type.

Note: This explicitly also differentiates between the different integer types. So when the variant stores an Int32, IsA<Int64>() will return false, even though the types could be converted.

◆ IsNumber()

XII_ALWAYS_INLINE bool xiiVariant::IsNumber ( ) const

Returns whether the stored type is numerical type either integer or floating point.

Bool counts as number.

◆ operator=()

template<typename T>

void xiiVariant::operator= ( const T & value )

Deduces the type of T and stores value.

If the type to be stored in the variant is not supported, a compile time error will occur.

◆ operator==()

bool xiiVariant::operator== ( const xiiVariant & other ) const

Will compare the value of this variant to that of other.

public methods

If both variants store 'numbers' (float, double, xiiInt32 types) the comparison will work, even if the types are not identical.

Note: If the two types are not numbers and not equal, an assert will occur. So be careful to only compare variants that can either both be converted to double (

See also: CanConvertTo()) or whose types are equal.

◆ operator[]() [1/2]

const xiiVariant xiiVariant::operator[] ( StringWrapper key ) const

Returns the sub value with szKey. This could be a value in a dictionary or a member property inside a reflected type.

This function will return an invalid variant if no corresponding sub value is found.

◆ operator[]() [2/2]

const xiiVariant xiiVariant::operator[] ( xiiUInt32 uiIndex ) const

Returns the sub value at iIndex. This could be an element in an array or a member property inside a reflected type.

Out of bounds access is handled gracefully and will return an invalid variant.

The documentation for this class was generated from the following files:

/home/runner/work/XII/XII/Source/Engine/Foundation/Types/Variant.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Types/Implementation/Variant.cpp
/home/runner/work/XII/XII/Source/Engine/Foundation/Types/Implementation/Variant_inl.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Types/Implementation/VariantHelper_inl.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ xiiVariant()

Member Function Documentation

◆ CanConvertTo()

◆ ConvertTo()

◆ DispatchTo()

◆ Get()

◆ IsA()

◆ IsNumber()

◆ operator=()

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]