plVariant 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 = plVariantType

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

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

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

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

	plVariant (const bool &value)

	plVariant (const plInt8 &value)

	plVariant (const plUInt8 &value)

	plVariant (const plInt16 &value)

	plVariant (const plUInt16 &value)

	plVariant (const plInt32 &value)

	plVariant (const plUInt32 &value)

	plVariant (const plInt64 &value)

	plVariant (const plUInt64 &value)

	plVariant (const float &value)

	plVariant (const double &value)

	plVariant (const plColor &value)

	plVariant (const plVec2 &value)

	plVariant (const plVec3 &value)

	plVariant (const plVec4 &value)

	plVariant (const plVec2I32 &value)

	plVariant (const plVec3I32 &value)

	plVariant (const plVec4I32 &value)

	plVariant (const plVec2U32 &value)

	plVariant (const plVec3U32 &value)

	plVariant (const plVec4U32 &value)

	plVariant (const plQuat &value)

	plVariant (const plMat3 &value)
	constructors

	plVariant (const plMat4 &value)

	plVariant (const plTransform &value)

	plVariant (const char *value)

	plVariant (const plString &value)

	plVariant (const plUntrackedString &value)

	plVariant (const plStringView &value, bool bCopyString=true)

	plVariant (const plDataBuffer &value)

	plVariant (const plTime &value)

	plVariant (const plUuid &value)

	plVariant (const plAngle &value)

	plVariant (const plColorGammaUB &value)

	plVariant (const plHashedString &value)

	plVariant (const plTempHashedString &value)

	plVariant (const plVariantArray &value)

	plVariant (const plVariantDictionary &value)

	plVariant (const plTypedPointer &value)

	plVariant (const plTypedObject &value)

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::CustomTypeCast, int > = 0>
	plVariant (const T &value)

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

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

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

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

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

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

void	operator= (plVariant &&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 plVariant &other) const
	Will compare the value of this variant to that of other.

	PL_ADD_DEFAULT_OPERATOR_NOTEQUAL (const plVariant &)

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 (plString or plStringView).

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

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

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::PointerCast, int > = 0>
bool	IsA () const

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::TypedObject, int > = 0>
bool	IsA () const

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::CustomTypeCast, int > = 0>
bool	IsA () const

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

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

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::PointerCast, int > = 0>
T	Get () const

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::TypedObject, int > = 0>
const T	Get () const

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::CustomTypeCast, int > = 0>
const T &	Get () const

plTypedPointer	GetWriteAccess ()
	Returns an writable plTypedPointer 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< plVariantTypeDeduction< T >::classification==plVariantClass::DirectCast, int > = 0>
T &	GetWritable ()

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::PointerCast, int > = 0>
T	GetWritable ()

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::CustomTypeCast, int > = 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 plRTTI *	GetReflectedType () const
	Returns the plRTTI type of the held value. For TypedPointer and TypedObject this will return the type of the target object.

const plVariant	operator[] (plUInt32 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 plVariant	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 (plResult *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.

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

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

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

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::CustomTypeCast, int > >
PL_ALWAYS_INLINE	plVariant (const T &value)

template<typename T >
PL_ALWAYS_INLINE	plVariant (const T *value)

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

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

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::DirectCast, int > >
PL_ALWAYS_INLINE bool	IsA () const

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::DirectCast, int > >
PL_ALWAYS_INLINE const T &	Get () const

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::PointerCast, int > >
PL_ALWAYS_INLINE T	Get () const

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::TypedObject, int > >
PL_ALWAYS_INLINE const T	Get () const

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::DirectCast, int > >
PL_ALWAYS_INLINE T &	GetWritable ()

template<typename T , typename std::enable_if_t< plVariantTypeDeduction< T >::classification==plVariantClass::PointerCast, int > >
PL_ALWAYS_INLINE T	GetWritable ()

template<typename T >
PL_ALWAYS_INLINE bool	CanConvertTo () const

template<typename T >
PL_FORCE_INLINE void	InitInplace (const T &value)
	private methods

template<typename T >
PL_FORCE_INLINE void	InitTypedObject (const T &value, plTraitInt< 0 >)

template<typename T >
PL_FORCE_INLINE void	InitTypedObject (const T &value, plTraitInt< 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	plVariantHelper

struct	CompareFunc

struct	GetTypeFromVariantFunc

Detailed Description

plVariant 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: plVariant::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 plVariant is implemented very efficiently, it should be avoided to use plVariant in code that needs to be fast.

Constructor & Destructor Documentation

◆ plVariant()

PL_ALWAYS_INLINE plVariant::plVariant ( const plVariant & 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 plVariant::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 plVariant::ConvertTo ( plResult * 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 plVariant::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< plVariantTypeDeduction< T >::classification==plVariantClass::DirectCast, int > = 0>

const T & plVariant::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< plVariantTypeDeduction< T >::classification==plVariantClass::DirectCast, int > = 0>

bool plVariant::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()

PL_ALWAYS_INLINE bool plVariant::IsNumber ( ) const

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

Bool counts as number.

◆ operator=()

template<typename T >

void plVariant::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 plVariant::operator== ( const plVariant & other ) const

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

public methods

If both variants store 'numbers' (float, double, int 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 plVariant plVariant::operator[] ( plUInt32 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.

◆ operator[]() [2/2]

const plVariant plVariant::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.

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

Code/Engine/Foundation/Types/Variant.h
Code/Engine/Foundation/Types/Implementation/Variant.cpp
Code/Engine/Foundation/Types/Implementation/Variant_inl.h
Code/Engine/Foundation/Types/Implementation/VariantHelper_inl.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ plVariant()

Member Function Documentation

◆ CanConvertTo()

◆ ConvertTo()

◆ DispatchTo()

◆ Get()

◆ IsA()

◆ IsNumber()

◆ operator=()

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]