ezEngine  Milestone 7
ezVariant Class Reference

ezVariant 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

union  Data
 
struct  SharedData
 
struct  Type
 This enum describes the type of data that is currently stored inside the variant. More...
 
struct  TypeDeduction
 A helper struct to convert the C++ type, which is passed as the template argument, into one of the ezVariant::Type enum values. More...
 
class  TypedSharedData
 

Public Member Functions

 ezVariant ()
 Initializes the variant to be 'Invalid'.
 
 ezVariant (const ezVariant &other)
 Copies the data from the other variant. More...
 
 ezVariant (ezVariant &&other)
 Moves the data from the other variant.
 
template<typename T >
 ezVariant (const T &value)
 Deduces the type of the passed argument and stores that type in the variant. More...
 
 ~ezVariant ()
 If necessary, this will deallocate any heap memory that is not in use any more.
 
void operator= (const ezVariant &other)
 Copies the data from the other variant into this one.
 
void operator= (ezVariant &&other)
 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. More...
 
bool operator== (const ezVariant &other) const
 Will compare the value of this variant to that of other. More...
 
bool operator!= (const ezVariant &other) const
 Same as operator== (with a twist!)
 
template<typename T >
bool operator== (const T &other) const
 See non-templated operator==.
 
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'.
 
template<typename T >
bool IsA () const
 Returns whether the stored type is exactly the given type. More...
 
Type::Enum GetType () const
 Returns the exact ezVariant::Type value.
 
template<typename T >
const T & Get () const
 Returns the variants value as the provided type. More...
 
void * GetData ()
 Returns a void* to the internal data.
 
const void * GetData () const
 Returns a void* to the internal data.
 
ezVariant operator[] (ezUInt32 uiIndex) const
 Returns the sub value at iIndex. This could be an element in an array or a member property inside a reflected type. More...
 
ezVariant operator[] (ezHashing::StringWrapper szKey) const
 Returns the sub value with szKey. This could be a value in a dictionary or a member property inside a reflected type. More...
 
template<typename T >
bool CanConvertTo () const
 Returns whether the stored type can generally be converted to the desired type. More...
 
bool CanConvertTo (Type::Enum type) const
 Same as the templated CanConvertTo function.
 
template<typename T >
ConvertTo (ezResult *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. More...
 
ezVariant ConvertTo (Type::Enum type, ezResult *out_pConversionStatus=nullptr) const
 Same as the templated function.
 
ezUInt64 ComputeHash (ezUInt64 uiSeed=0) const
 Computes the hash value of the stored data. Returns uiSeed (unchanged) for an invalid Variant.
 
template<typename T >
EZ_FORCE_INLINE ezVariant (const T &value)
 
template<typename T >
EZ_FORCE_INLINE void operator= (const T &value)
 
template<typename T >
EZ_FORCE_INLINE bool operator== (const T &other) const
 
template<typename T >
EZ_FORCE_INLINE bool operator!= (const T &other) const
 
template<typename T >
EZ_FORCE_INLINE bool IsA () const
 
template<typename T >
EZ_FORCE_INLINE const T & Get () const
 
template<typename T >
EZ_FORCE_INLINE bool CanConvertTo () const
 
template<typename Functor >
void DispatchTo (Functor &functor, Type::Enum type)
 
template<typename T >
EZ_FORCE_INLINE void Init (const T &value)
 private methods
 
template<typename StorageType , typename T >
EZ_FORCE_INLINE void Store (const T &value, ezTraitInt< 0 >)
 
template<typename StorageType , typename T >
EZ_FORCE_INLINE void Store (const T &value, ezTraitInt< 1 >)
 
template<typename T >
EZ_FORCE_INLINE T & Cast ()
 
template<typename T >
EZ_FORCE_INLINE const T & Cast () const
 

Static Public Member Functions

template<typename Functor >
static void DispatchTo (Functor &functor, Type::Enum type)
 This will call the overloaded operator() (function call operator) of the provided functor. More...
 

Private Member Functions

template<typename T >
void Init (const T &value)
 
template<typename StorageType , typename T >
void Store (const T &value, ezTraitInt< 0 >)
 
template<typename StorageType , typename T >
void Store (const T &value, ezTraitInt< 1 >)
 
void Release ()
 
void CopyFrom (const ezVariant &other)
 
void MoveFrom (ezVariant &&other)
 
template<typename T >
T & Cast ()
 
template<typename T >
const T & Cast () const
 
template<typename T >
ConvertNumber () const
 

Static Private Member Functions

static bool IsNumber (ezUInt32 type)
 
static bool IsFloatingPoint (ezUInt32 type)
 

Private Attributes

union ezVariant::Data m_Data
 
ezUInt32 m_Type: 31
 
ezUInt32 m_bIsShared: 1
 

Friends

class ezVariantHelper
 
struct CompareFunc
 

Detailed Description

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

Class Documentation

union ezVariant::Data
Class Members
float f[4]
SharedData * shared

Constructor & Destructor Documentation

EZ_FORCE_INLINE ezVariant::ezVariant ( const ezVariant 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.
template<typename T >
ezVariant::ezVariant ( const T &  value)

Deduces the type of the passed argument and stores that type in the variant.

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

Member Function Documentation

template<typename T >
bool ezVariant::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.

template<typename T >
T ezVariant::ConvertTo ( ezResult 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.

template<typename Functor >
static void ezVariant::DispatchTo ( Functor &  functor,
Type::Enum  type 
)
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.

template<typename T >
const T& ezVariant::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 instead.

template<typename T >
bool ezVariant::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.
template<typename T >
void ezVariant::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.

bool ezVariant::operator== ( const ezVariant 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.
ezVariant ezVariant::operator[] ( ezUInt32  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.

ezVariant ezVariant::operator[] ( ezHashing::StringWrapper  szKey) 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: