VtValue Class Reference

#include <value.h>

Public Member Functions
	VtValue ()
	Default ctor gives empty VtValue. More...
	VtValue (VtValue const &other)
	Copy construct with other. More...
	VtValue (VtValue &&other) noexcept
	Move construct with other. More...
template<class T >
	VtValue (T const &obj)
VT_API	VtValue (VtValueRef ref)
	Construct with VtValueRef. More...
	~VtValue ()
	Destructor. More...
VtValue &	operator= (VtValue const &other)
	Copy assignment from another VtValue. More...
VtValue &	operator= (VtValue &&other) noexcept
	Move assignment from another VtValue. More...
VT_API VtValue &	operator= (VtValueRef ref)
	Assignment from VtValueRef. More...
template<class T >
VtValue &	operator= (T const &obj)
	Assignment operator from any type. More...
VtValue &	Swap (VtValue &rhs) noexcept
	Swap this with rhs. More...
template<class T >
void	Swap (T &rhs)
template<class T >
void	UncheckedSwap (T &rhs)
void	UncheckedSwap (VtValue &rhs)
template<class T >
T	Remove ()
template<class T >
T	UncheckedRemove ()
template<class T , class Fn >
bool	Mutate (Fn &&mutateFn)
template<class T , class Fn >
void	UncheckedMutate (Fn &&mutateFn)
template<class T >
bool	IsHolding () const
VT_API bool	IsArrayValued () const
	Return true if this holds a VtArray instance, false otherwise. More...
VT_API bool	IsArrayEditValued () const
	Return true if this holds a VtArrayEdit instance, false otherwise. More...
size_t	GetArraySize () const
VT_API std::type_info const &	GetTypeid () const
	Return the typeid of the type held by this value. More...
VT_API std::type_info const &	GetElementTypeid () const
VT_API TfType	GetType () const
	Returns the TfType of the type held by this value. More...
VT_API std::string	GetTypeName () const
	Return the type name of the held typeid. More...
int	GetKnownValueTypeIndex () const
template<class T >
T const &	UncheckedGet () const &
template<class T >
T	UncheckedGet ()&&
template<class T >
T const &	Get () const &
template<class T >
T	Get ()&&
template<class T >
T	GetWithDefault (T const &def=T()) const
template<typename T >
VtValue &	Cast ()
VtValue &	CastToTypeOf (VtValue const &other)
VtValue &	CastToTypeid (std::type_info const &type)
template<typename T >
bool	CanCast () const
bool	CanCastToTypeOf (VtValue const &other) const
bool	CanCastToTypeid (std::type_info const &type) const
bool	IsEmpty () const
	Returns true iff this value is empty. More...
VT_API VtValueRef	Ref () const &
VT_API VtValueRef	Ref ()&&
VT_API	operator VtValueRef () const &
	Implicitly convert to VtValueRef. More...
VT_API	operator VtValueRef ()&&
	Implicitly convert to an rvalue VtValueRef. More...
VT_API bool	CanHash () const
	Return true if the held object provides a hash implementation. More...
VT_API size_t	GetHash () const
	Return a hash code for the held object by calling VtHashValue() on it. More...
VT_API bool	CanComposeOver () const
VT_API bool	CanTransform () const
bool	operator== (const VtValue &rhs) const
	Test two values for equality. More...
bool	operator!= (const VtValue &rhs) const
template<>
const VtValue &	Get () const &
template<>
VtValue	Get ()&&
template<>
const VtValue &	UncheckedGet () const &
template<>
VtValue	UncheckedGet ()&&
template<>
bool	IsHolding () const
template<>
bool	IsHolding () const
template<class T >
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE VtValue &	operator= (T const &obj)
template<>
VtValue &	operator= (VtValueRef const &obj)=delete

Static Public Member Functions
template<class T >
static VtValue	Take (T &obj)
template<typename From , typename To >
static void	RegisterCast (VtValue(*castFn)(VtValue const &))
	Register a cast from VtValue holding From to VtValue holding To. More...
template<typename From , typename To >
static void	RegisterSimpleCast ()
	Register a simple cast from VtValue holding From to VtValue. More...
template<typename From , typename To >
static void	RegisterSimpleBidirectionalCast ()
template<typename T >
static VtValue	Cast (VtValue const &val)
static VT_API VtValue	CastToTypeOf (VtValue const &val, VtValue const &other)
static VT_API VtValue	CastToTypeid (VtValue const &val, std::type_info const &type)
static bool	CanCastFromTypeidToTypeid (std::type_info const &from, std::type_info const &to)

Friends
struct	_HoldAside
struct	Vt_ValueShapeDataAccess
struct	Vt_ValueTestAccess
void	swap (VtValue &lhs, VtValue &rhs)
	Overloaded swap() for generic code/stl/etc. More...
size_t	hash_value (VtValue const &val)
template<typename T >
bool	operator== (VtValue const &lhs, T const &rhs)
	Tests for equality. More...
template<typename T >
bool	operator== (T const &lhs, VtValue const &rhs)
template<typename T >
bool	operator!= (VtValue const &lhs, T const &rhs)
	Tests for inequality. More...
template<typename T >
bool	operator!= (T const &lhs, VtValue const &rhs)
VT_API friend std::ostream &	operator<< (std::ostream &out, const VtValue &self)
	Calls through to operator << on the held object. More...
TfPyObjWrapper	Vt_GetPythonObjectFromHeldValue (VtValue const &self)

Detailed Description

Provides a container which may hold any type, and provides introspection and iteration over array types. See VtIsArray for more info.

Held-type Conversion with VtValue::Cast

VtValue provides a suite of "Cast" methods that convert or create a VtValue holding a requested type (via template parameter, typeid, or type-matching to another VtValue) from the type of the currently-held value. Clients can add conversions between their own types using the RegisterCast(), RegisterSimpleCast(), and RegisterSimpleBidirectionalCast() methods. Conversions from plugins can be guaranteed to be registered before they are needed by registering them from within a

TF_REGISTRY_FUNCTION(VtValue) {
}

block.

Builtin Type Conversion

Conversions between most of the basic "value types" that are intrinsically convertible are builtin, including all numeric types (including Gf's half), std::string/TfToken, GfVec* (for vecs of the same dimension), and VtArray<T> for floating-point POD and GfVec of the preceding.

Numeric Conversion Safety

The conversions between all scalar numeric types are performed with range checks such as provided by boost::numeric_cast(), and will fail, returning an empty VtValue if the source value is out of range of the destination type.

Conversions between GfVec and other compound-numeric types provide no more or less safety or checking than the conversion constructors of the types themselves. This includes VtArray, even VtArray<T> for T in scalar types that are range-checked when held singly.

Definition at line 89 of file value.h.

Constructor & Destructor Documentation

VtValue::VtValue ( )

inline

Default ctor gives empty VtValue.

Definition at line 823 of file value.h.

VtValue::VtValue ( VtValue const &  other )

inline

Copy construct with other.

Definition at line 826 of file value.h.

VtValue::VtValue ( VtValue &&  other )

inlinenoexcept

Move construct with other.

Definition at line 831 of file value.h.

template<class T >

VtValue::VtValue ( T const &  obj )

inlineexplicit

Construct a VtValue holding a copy of obj.

If T is a char pointer or array, produce a VtValue holding a std::string. If T is pxr_boost::python::object, produce a VtValue holding a TfPyObjWrapper.

Definition at line 841 of file value.h.

VT_API VtValue::VtValue ( VtValueRef  ref )

explicit

Construct with VtValueRef.

VtValue::~VtValue ( )

inline

Destructor.

Definition at line 876 of file value.h.

Member Function Documentation

template<typename T >

bool VtValue::CanCast ( ) const

inline

Return if this can be cast to T.

See Also

Held-type Conversion with VtValue::Cast

Definition at line 1208 of file value.h.

static bool VtValue::CanCastFromTypeidToTypeid ( std::type_info const &  from, std::type_info const &  to  )

inlinestatic

Return if a value of type from can be cast to type to.

See Also

Held-type Conversion with VtValue::Cast

Definition at line 1160 of file value.h.

bool VtValue::CanCastToTypeid ( std::type_info const &  type ) const

inline

Return if this can be cast to type.

See Also

Held-type Conversion with VtValue::Cast

Definition at line 1222 of file value.h.

bool VtValue::CanCastToTypeOf ( VtValue const &  other ) const

inline

Return if this can be cast to type.

See Also

Held-type Conversion with VtValue::Cast

Definition at line 1215 of file value.h.

VT_API bool VtValue::CanComposeOver

(

)

const

Return true if this value holds a type that has been declared at compile time to support composing over other types. This is a fast check that can be used to avoid calling VtValueComposeOver(strong, weak) if strong does not support composing over. Empty VtValue always can compose over.

VT_API bool VtValue::CanHash

(

)

const

Return true if the held object provides a hash implementation.

VT_API bool VtValue::CanTransform

(

)

const

Return true if this value holds a type that has been declared to support value transforms at compile time. This is a fast check that can be used to avoid calling the relatively slower VtValueTryTransform(obj, xform) if obj does not support transforms at all. Empty VtValue does not support transforms.

template<typename T >

static VtValue VtValue::Cast ( VtValue const &  val )

inlinestatic

Return a VtValue holding val cast to hold T. Return empty VtValue if cast fails.

This Cast() function is safe to call in multiple threads as it does not mutate the operant val.

See Also

Held-type Conversion with VtValue::Cast

Definition at line 1131 of file value.h.

template<typename T >

VtValue& VtValue::Cast ( )

inline

Return this holding value type cast to T. This value is left empty if the cast fails.

Note

Since this method mutates this value, it is not safe to invoke on the same VtValue in multiple threads simultaneously.

See Also

Held-type Conversion with VtValue::Cast

Definition at line 1173 of file value.h.

static VT_API VtValue VtValue::CastToTypeid ( VtValue const &  val, std::type_info const &  type  )

static

Return a VtValue holding val cast to type. Return empty VtValue if cast fails.

This Cast() function is safe to call in multiple threads as it does not mutate the operant val.

See Also

Held-type Conversion with VtValue::Cast

VtValue& VtValue::CastToTypeid ( std::type_info const &  type )

inline

Return this holding value type cast to type. This value is left empty if the cast fails.

Note

Since this method mutates this value, it is not safe to invoke on the same VtValue in multiple threads simultaneously.

See Also

Held-type Conversion with VtValue::Cast

Definition at line 1197 of file value.h.

static VT_API VtValue VtValue::CastToTypeOf ( VtValue const &  val, VtValue const &  other  )

static

Return a VtValue holding val cast to same type that other is holding. Return empty VtValue if cast fails.

This Cast() function is safe to call in multiple threads as it does not mutate the operant val.

See Also

Held-type Conversion with VtValue::Cast

VtValue& VtValue::CastToTypeOf ( VtValue const &  other )

inline

Return this holding value type cast to same type that other is holding. This value is left empty if the cast fails.

Note

Since this method mutates this value, it is not safe to invoke on the same VtValue in multiple threads simultaneously.

See Also

Held-type Conversion with VtValue::Cast

Definition at line 1186 of file value.h.

template<class T >

T const& VtValue::Get ( ) const

inline

Returns a const reference to the held object if the held object is of type T. Issues an error and returns a const reference to a default value if the held object is not of type T. Use IsHolding to verify correct type before calling this function. The default value returned in case of type mismatch is constructed using Vt_DefaultValueFactory<T>. That may be specialized for client types. The default implementation of the default value factory produces a value-initialized T.

Definition at line 1063 of file value.h.

template<class T >

T VtValue::Get ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. In case *this is an rvalue, move the held value out and return by value.

Definition at line 1080 of file value.h.

template<>

const VtValue& VtValue::Get ( ) const

inline

Definition at line 1484 of file value.h.

template<>

VtValue VtValue::Get ( )

inline

Definition at line 1490 of file value.h.

size_t VtValue::GetArraySize ( ) const

inline

Return the number of elements in the held value if IsArrayValued(), return 0 otherwise.

Definition at line 1014 of file value.h.

VT_API std::type_info const& VtValue::GetElementTypeid

(

)

const

If this value holds a VtArray or VtArrayEdit instance, return the typeid of its element type. For example, if this value holds a VtIntArray or a VtIntArrayEdit, return typeid(int). Otherwise return typeid(void).

VT_API size_t VtValue::GetHash

(

)

const

Return a hash code for the held object by calling VtHashValue() on it.

int VtValue::GetKnownValueTypeIndex ( ) const

inline

Return VtKnownValueTypeIndex<T> for the held type T. If this value holds a proxy type, resolve the proxy and return the proxied type's index. If this value is empty or holds a type that is not 'known', return -1.

Definition at line 1034 of file value.h.

VT_API TfType VtValue::GetType

(

)

const

Returns the TfType of the type held by this value.

VT_API std::type_info const& VtValue::GetTypeid

(

)

const

Return the typeid of the type held by this value.

VT_API std::string VtValue::GetTypeName

(

)

const

Return the type name of the held typeid.

template<class T >

T VtValue::GetWithDefault ( T const &  def = T() ) const

inline

Return a copy of the held object if the held object is of type T. Return a copy of the default value def otherwise. Note that this always returns a copy, as opposed to Get() which always returns a reference.

Definition at line 1098 of file value.h.

VT_API bool VtValue::IsArrayEditValued

(

)

const

Return true if this holds a VtArrayEdit instance, false otherwise.

VT_API bool VtValue::IsArrayValued

(

)

const

Return true if this holds a VtArray instance, false otherwise.

bool VtValue::IsEmpty ( ) const

inline

Returns true iff this value is empty.

Definition at line 1227 of file value.h.

template<class T >

bool VtValue::IsHolding ( ) const

inline

Return true if this value is holding an object of type T, false otherwise.

Definition at line 1002 of file value.h.

template<>

bool VtValue::IsHolding ( ) const

inline

Definition at line 1508 of file value.h.

template<>

bool VtValue::IsHolding ( ) const

inline

Definition at line 1515 of file value.h.

template<class T , class Fn >

bool VtValue::Mutate ( Fn &&  mutateFn )

inline

If this value holds an object of type T, invoke mutateFn, passing it a non-const reference to the held object and return true. Otherwise do nothing and return false.

Definition at line 972 of file value.h.

VT_API VtValue::operator VtValueRef

(

)

const

Implicitly convert to VtValueRef.

VT_API VtValue::operator VtValueRef

(

)

Implicitly convert to an rvalue VtValueRef.

bool VtValue::operator!= ( const VtValue &  rhs ) const

inline

Definition at line 1303 of file value.h.

VtValue& VtValue::operator= ( VtValue const &  other )

inline

Copy assignment from another VtValue.

Definition at line 879 of file value.h.

VtValue& VtValue::operator= ( VtValue &&  other )

inlinenoexcept

Move assignment from another VtValue.

Definition at line 886 of file value.h.

VT_API VtValue& VtValue::operator=

(

VtValueRef

ref

)

Assignment from VtValueRef.

template<class T >

VtValue& VtValue::operator=

(

T const &

obj

)

Assignment operator from any type.

template<class T >

PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE VtValue& VtValue::operator=

(

T const &

obj

)

Definition at line 1537 of file value.h.

template<>

VtValue& VtValue::operator= ( VtValueRef const &  obj )

delete

bool VtValue::operator== ( const VtValue &  rhs ) const

inline

Test two values for equality.

Definition at line 1291 of file value.h.

VT_API VtValueRef VtValue::Ref

(

)

const

Return a VtValueRef that refers to the current object held by this VtValue. The returned VtValueRef is invalidated and must not be used after this VtValue is modified or destroyed.

VT_API VtValueRef VtValue::Ref

(

)

Return a VtValueRef that refers to the current object held by this rvalue VtValue. The returned VtValueRef is invalidated and must not be used after this VtValue is modified or destroyed.

template<typename From , typename To >

static void VtValue::RegisterCast ( VtValue(*)(VtValue const &)  castFn )

inlinestatic

Register a cast from VtValue holding From to VtValue holding To.

Definition at line 1104 of file value.h.

template<typename From , typename To >

static void VtValue::RegisterSimpleBidirectionalCast ( )

inlinestatic

Register a two-way cast from VtValue holding From to VtValue holding To.

Definition at line 1118 of file value.h.

template<typename From , typename To >

static void VtValue::RegisterSimpleCast ( )

inlinestatic

Register a simple cast from VtValue holding From to VtValue.

Definition at line 1111 of file value.h.

template<class T >

T VtValue::Remove ( )

inline

Make this value empty and return the held T instance. If this value does not hold a T instance, make this value empty and return a default-constructed T.

Definition at line 949 of file value.h.

VtValue& VtValue::Swap ( VtValue &  rhs )

inlinenoexcept

Swap this with rhs.

Definition at line 901 of file value.h.

template<class T >

void VtValue::Swap ( T &  rhs )

inline

Swap the held value with rhs. If this value is holding a T, make an unqualified call to swap(<held-value>, rhs). If this value is not holding a T, replace the held value with a value-initialized T instance first, then swap.

Definition at line 921 of file value.h.

template<class T >

static VtValue VtValue::Take ( T &  obj )

inlinestatic

Create a new VtValue, taking its contents from obj.

This is equivalent to creating a VtValue holding a value-initialized T instance, then invoking swap(<held-value>, obj), leaving obj in a default-constructed (value-initialized) state. In the case that obj is expensive to copy, it may be significantly faster to use this idiom when obj need not retain its contents:

MyExpensiveObject obj = CreateObject();
return VtValue::Take(obj);

Rather than:

MyExpensiveObject obj = CreateObject();
return VtValue(obj);

Definition at line 869 of file value.h.

template<class T >

T const& VtValue::UncheckedGet ( ) const

inline

Returns a const reference to the held object if the held object is of type T. Invokes undefined behavior otherwise. This is the fastest Get() method to use after a successful IsHolding() check.

Definition at line 1046 of file value.h.

template<class T >

T VtValue::UncheckedGet ( )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. In case *this is an rvalue, move the held value out and return by value.

Definition at line 1052 of file value.h.

template<>

const VtValue& VtValue::UncheckedGet ( ) const

inline

Definition at line 1496 of file value.h.

template<>

VtValue VtValue::UncheckedGet ( )

inline

Definition at line 1502 of file value.h.

template<class T , class Fn >

void VtValue::UncheckedMutate ( Fn &&  mutateFn )

inline

Invoke mutateFn, passing it a non-const reference to the held object which must be of type T. If the held object is not of type T, this function invokes undefined behavior.

Definition at line 987 of file value.h.

template<class T >

T VtValue::UncheckedRemove ( )

inline

Make this value empty and return the held T instance. If this value does not hold a T instance, this method invokes undefined behavior.

Definition at line 960 of file value.h.

template<class T >

void VtValue::UncheckedSwap ( T &  rhs )

inline

Swap the held value with rhs. This VtValue must be holding an object of type T. If it does not, this invokes undefined behavior. Use Swap() if this VtValue is not known to contain an object of type T.

Definition at line 935 of file value.h.

void VtValue::UncheckedSwap ( VtValue &  rhs )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 943 of file value.h.

Friends And Related Function Documentation

friend struct _HoldAside

friend

Definition at line 776 of file value.h.

size_t hash_value ( VtValue const &  val )

friend

Definition at line 1251 of file value.h.

template<typename T >

bool operator!= ( VtValue const &  lhs, T const &  rhs  )

friend

Tests for inequality.

Definition at line 1282 of file value.h.

template<typename T >

bool operator!= ( T const &  lhs, VtValue const &  rhs  )

friend

Definition at line 1286 of file value.h.

VT_API friend std::ostream& operator<< ( std::ostream &  out, const VtValue &  self  )

friend

Calls through to operator << on the held object.

template<typename T >

bool operator== ( VtValue const &  lhs, T const &  rhs  )

friend

Tests for equality.

Definition at line 1271 of file value.h.

template<typename T >

bool operator== ( T const &  lhs, VtValue const &  rhs  )

friend

Definition at line 1276 of file value.h.

void swap ( VtValue &  lhs, VtValue &  rhs  )

friend

Overloaded swap() for generic code/stl/etc.

Definition at line 913 of file value.h.

TfPyObjWrapper Vt_GetPythonObjectFromHeldValue ( VtValue const &  self )

friend

friend struct Vt_ValueShapeDataAccess

friend

Definition at line 1312 of file value.h.

friend struct Vt_ValueTestAccess

friend

Definition at line 1455 of file value.h.

---

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

• pxr/base/vt/value.h