Variant

class ReflectExport( reflect ) Variant

Variants represent objects of any reflected type. Some variants own their data, others reference data. They may be blank, have a type, a type and a const value, or a type and a mutable value, or be alias another variant of another type (see: Alias).

Variants are used in the property system for reading and writing data without a serializer, and by the function call system for passing arguments. Variants can be used any time an interface with specific typeinfo needs to be exposed with a generic interface.

Variants share data. A copy of a reference variant (created with Variant::Ref or Variant::ConstRef) will refer to the same data. A copy of a constructed variant (created with <Variant::Copy> or a blank one after SetValue or Construct) will share the object, the last one to destruct will deallocate it. This pattern makes it possible to return variants from functions. Operations like <operator=> or Construct unshares the variant.

Reference counting is achieved using a circular singly-linked list.

Summary

Variant	Variants represent objects of any reflected type.
Functions
Variant() (constructor)	constructs a blank variant.
Variant() (copy constructor)	clones another variant.
operator=	copies another variant
FromRef	Builds a Variant which can references a value.
FromConstRef	Builds a Variant which wraps a const value.
ConstRef	Builds a Variant which wraps a const value array (as a pointer).
FromValue	Creates a variant holding a copy of the value.
FromStaticValue	Creates a variant holding a copy of the value, without using reflection at all.
FromOpaque	Builds a variant from an Type *, opaque pair.
FromConstOpaque	Builds a variant from an Type *, opaque pair.
BindType	Sets the class type for this variant.
GetType	Check the type of this variant.
Construct	Ensures that this variant can be Set.
ConvertToType	Converts this variant to another type, keeping the same (or “similar”) value.
Set	Assigns a value to the variant.
Ref	Assigns a reference to the variant.
ConstRef	Assigns a const reference to the variant.
Alias	This is a special function, for reflected parameters to reflected function calls.
Alias	This is a special function, for reflected parameters to reflected function calls.
CanRefAs	checks if this variant can be used as a reference to type.
CanConstRefAs	checks if this variant can be used as a const reference to type.
CanReadAs	checks if this variant is convertable to type.
CanWriteAs	checks if this variant is convertable from type.
Serialize	reads or writes this variant with a reflector.
ToString	Serializes with the StandardSerializer.
FromString	Deserializes with the StandardSerializer, at least a Type must be bound.
BindType()	Template version of BindType.
Construct()	Template version of Construct.
ConvertToType()	Template version of ConvertToType.
CanRefAs()	Template version of CanRefAs.
CanRefAs()	Template version of CanRefAs.
CanReadAs()	Template version of CanReadAs.
CanWriteAs()	Template version of CanWriteAs.
SetValue	Template version of Set.
RefValue	Template version of Ref.
ConstRefValue	Template version of ConstRef.
ReadValue	Reads this variant as typeof(value).
AsValue()	Returns the value of this variant as the requested type.
AsConstRef()	Returns the value of this variant as the requested type.
AsRef()	Returns the value of this variant as the requested type.
UpdateAliases	Updates aliased variants with this one’s value.
Downcast	Convert type and pointer to most derived form (when pointing to some kind of Dynamic).
Void	Returns the variant representing a void “value.”
Opaque
ConstOpaque

Functions

Variant() (constructor)

Variant()

constructs a blank variant.

Variant() (copy constructor)

clones another variant.

operator=

const Variant &operator=( const Variant & other )

copies another variant

FromRef

template<typename T> static Variant FromRef( T & value )

Builds a Variant which can references a value. The value must persist as long as this Variant (or copies of this variant) does.

FromConstRef

template<typename T> static Variant FromConstRef( const T & value )

Builds a Variant which wraps a const value. The value must persist as long as this Variant (or copies of this variant) does.

ConstRef

template<typename T, unsigned size> static Variant FromConstRef(
const T (&value)[size]
)

Builds a Variant which wraps a const value array (as a pointer). This is function is primarily intended to be used with string literals, which (without casting) are statically typed as const arrays.

NOTE: This allocates a pointer to point to the array.

FromValue

template<typename T> static Variant FromValue( const T & value )

Creates a variant holding a copy of the value.

FromStaticValue

template<typename T> static Variant FromStaticValue( const T & value )

Creates a variant holding a copy of the value, without using reflection at all.

FromOpaque

static Variant FromOpaque( const Type * type,
void * opaque )

Builds a variant from an Type *, opaque pair.

FromConstOpaque

static Variant FromConstOpaque( const Type * type,
const void * opaque )

Builds a variant from an Type *, opaque pair.

BindType

void BindType( const Type * type )

Sets the class type for this variant.

The bound class determins the datatype to construct after Set or Alias

GetType

const Type *GetType() const

Check the type of this variant.

Construct

bool Construct( const Type * type = 0,
bool own_data = false )

Ensures that this variant can be Set.

Parameters

type	the class type to construct as, if not specified the currently bound type will be used.
own_data	if true, this variants data will not be shared with any other variant or object.

ConvertToType

bool ConvertToType( const Type * type )

Converts this variant to another type, keeping the same (or “similar”) value.

Set

bool Set( const Variant & value )

Assigns a value to the variant.

constructs and assigns new data (of the type specified in BindType if available, or value) if this variant does not refer to another value.
assigns current data if this variant refers to a non-const value.
fails otherwise.

Ref

bool Ref( const Variant & value )

Assigns a reference to the variant.

requires a typed or blank, empty (no data) variant.
if the variant is typed, this does not change the type

ConstRef

bool ConstRef( const Variant & value )

Assigns a const reference to the variant.

requires a typed or blank, empty (no data) variant.
if the variant is typed, this does not change the type

Alias

bool Alias( Variant & value )

This is a special function, for reflected parameters to reflected function calls.

This variant must have it’s type set with BindType, as the visible type of the function parameter. The value must be a derived type or convertable to the bound type and back. In the latter case (just assume it), the aliased value will not be updated until UpdateAliases is called. See VariantAliasRef, which does that.

Alias

bool ConstAlias( const Variant & value )

This is a special function, for reflected parameters to reflected function calls.

This variant must have it’s type set with BindType, as the visible type of the function parameter. The value must be a derived type or convertable to to bound type. This will be the same as a ConstRef() when possible or a Set() when necessary.

CanRefAs

bool CanRefAs( const Type * type ) const

checks if this variant can be used as a reference to type.

CanConstRefAs

bool CanConstRefAs( const Type * type ) const

checks if this variant can be used as a const reference to type.

CanReadAs

bool CanReadAs( const Type * type ) const

checks if this variant is convertable to type.

CanWriteAs

bool CanWriteAs( const Type * type ) const

checks if this variant is convertable from type.

Serialize

void Serialize( Reflector & reflector ) const

reads or writes this variant with a reflector. Requires a type and should not be const.

ToString

string::String ToString() const

Serializes with the StandardSerializer.

FromString

bool FromString( string::Fragment )

Deserializes with the StandardSerializer, at least a Type must be bound.

Returns

true	if deserialization succeeded.

BindType()

template<typename T> void BindType()

Template version of BindType.

Construct()

template<typename T> bool Construct( bool own_data = false )

Template version of Construct.

ConvertToType()

template<typename T> bool ConvertToType()

Template version of ConvertToType.

CanRefAs()

template<typename T> bool CanRefAs() const

Template version of CanRefAs.

CanRefAs()

Template version of CanRefAs.

CanReadAs()

template<typename T> bool CanReadAs() const

Template version of CanReadAs.

CanWriteAs()

template<typename T> bool CanWriteAs() const

Template version of CanWriteAs.

SetValue

template<typename T> bool SetValue( const T & value )

Template version of Set.

RefValue

template<typename T> bool RefValue( T & value )

Template version of Ref.

ConstRefValue

template<typename T> bool ConstRefValue( const T & value )

Template version of ConstRef.

ReadValue

template<typename T> bool ReadValue( T & value ) const

Reads this variant as typeof(value). Can be used to export the value of this variant as a particular type.

AsValue()

template<typename T> T AsValue() const

Returns the value of this variant as the requested type. Check that <CasReadAs> is true before calling this function.

AsConstRef()

template<typename T> const T &AsConstRef() const

Returns the value of this variant as the requested type. Check that <CasConstRefAs> is true before calling this function.

AsRef()

template<typename T> T &AsRef() const

Returns the value of this variant as the requested type. Check that <CasRefAs> is true before calling this function.

UpdateAliases

void UpdateAliases() const

Updates aliased variants with this one’s value. Used with invoking function calls with slightly wrongly typed output parameters.

Downcast

Variant &Downcast()

Convert type and pointer to most derived form (when pointing to some kind of Dynamic).

Void

static Variant &Void()

Returns the variant representing a void “value.”

Opaque

void *Opaque() const

ConstOpaque

const void *ConstOpaque() const