Loading...
Searching...
No Matches
VtValue Class Reference

Provides a container which may hold any type, and provides introspection and iteration over array types. More...

#include <value.h>

Public Member Functions

 VtValue ()
 Default ctor gives empty VtValue.
 
 VtValue (VtValue const &other)
 Copy construct with other.
 
 VtValue (VtValue &&other) noexcept
 Move construct with other.
 
template<class T >
 VtValue (T const &obj)
 Construct a VtValue holding a copy of obj.
 
 ~VtValue ()
 Destructor.
 
VtValueoperator= (VtValue const &other)
 Copy assignment from another VtValue.
 
VtValueoperator= (VtValue &&other) noexcept
 Move assignment from another VtValue.
 
template<class T >
VtValueoperator= (T const &obj)
 Assignment operator from any type.
 
VtValueoperator= (char const *cstr)
 Assigning a char const * gives a VtValue holding a std::string.
 
VtValueoperator= (char *cstr)
 Assigning a char * gives a VtValue holding a std::string.
 
VtValueSwap (VtValue &rhs) noexcept
 Swap this with rhs.
 
template<class T >
void Swap (T &rhs)
 Swap the held value with rhs. If this value is holding a T,.
 
template<class T >
void UncheckedSwap (T &rhs)
 Swap the held value with rhs.
 
void UncheckedSwap (VtValue &rhs)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<class T >
Remove ()
 Make this value empty and return the held T instance.
 
template<class T >
UncheckedRemove ()
 Make this value empty and return the held T instance.
 
template<class T , class Fn >
std::enable_if_t< std::is_same< T, typename Vt_ValueGetStored< T >::Type >::value, bool > Mutate (Fn &&mutateFn)
 If this value holds an object of type T, invoke mutateFn, passing it a non-const reference to the held object and return true.
 
template<class T , class Fn >
std::enable_if_t< std::is_same< T, typename Vt_ValueGetStored< T >::Type >::value > UncheckedMutate (Fn &&mutateFn)
 Invoke mutateFn, it a non-const reference to the held object which must be of type T.
 
template<class T >
bool IsHolding () const
 Return true if this value is holding an object of type T, false otherwise.
 
VT_API bool IsArrayValued () const
 Returns true iff this is holding an array type (see VtIsArray<>).
 
size_t GetArraySize () const
 Return the number of elements in the held value if IsArrayValued(), return 0 otherwise.
 
VT_API std::type_info const & GetTypeid () const
 Returns the typeid of the type held by this value.
 
VT_API std::type_info const & GetElementTypeid () const
 Return the typeid of elements in a array valued type.
 
VT_API TfType GetType () const
 Returns the TfType of the type held by this value.
 
VT_API std::string GetTypeName () const
 Return the type name of the held typeid.
 
int GetKnownValueTypeIndex () const
 Return VtKnownValueTypeIndex<T> for the held type T.
 
template<class T >
T const & UncheckedGet () const &
 Returns a const reference to the held object if the held object is of type T.
 
template<class T >
UncheckedGet () &&
 
template<class T >
T const & Get () const &
 Returns a const reference to the held object if the held object is of type T.
 
template<class T >
Get () &&
 
template<class T >
GetWithDefault (T const &def=T()) const
 Return a copy of the held object if the held object is of type T.
 
template<typename T >
VtValueCast ()
 Return this holding value type cast to T.
 
VtValueCastToTypeOf (VtValue const &other)
 Return this holding value type cast to same type that other is holding.
 
VtValueCastToTypeid (std::type_info const &type)
 Return this holding value type cast to type.
 
template<typename T >
bool CanCast () const
 Return if this can be cast to T.
 
bool CanCastToTypeOf (VtValue const &other) const
 Return if this can be cast to type.
 
bool CanCastToTypeid (std::type_info const &type) const
 Return if this can be cast to type.
 
bool IsEmpty () const
 Returns true iff this value is empty.
 
VT_API bool CanHash () const
 Return true if the held object provides a hash implementation.
 
VT_API size_t GetHash () const
 Return a hash code for the held object by calling VtHashValue() on it.
 
bool operator== (const VtValue &rhs) const
 Test two values for equality.
 
bool operator!= (const VtValue &rhs) const
 

Static Public Member Functions

template<class T >
static VtValue Take (T &obj)
 Create a new VtValue, taking its contents from obj.
 
template<typename From , typename To >
static void RegisterCast (VtValue(*castFn)(VtValue const &))
 Register a cast from VtValue holding From to VtValue holding To.
 
template<typename From , typename To >
static void RegisterSimpleCast ()
 Register a simple cast from VtValue holding From to VtValue.
 
template<typename From , typename To >
static void RegisterSimpleBidirectionalCast ()
 Register a two-way cast from VtValue holding From to VtValue holding To.
 
template<typename T >
static VtValue Cast (VtValue const &val)
 Return a VtValue holding val cast to hold T.
 
static VT_API VtValue CastToTypeOf (VtValue const &val, VtValue const &other)
 Return a VtValue holding val cast to same type that other is holding.
 
static VT_API VtValue CastToTypeid (VtValue const &val, std::type_info const &type)
 Return a VtValue holding val cast to type.
 
static bool CanCastFromTypeidToTypeid (std::type_info const &from, std::type_info const &to)
 Return if a value of type from can be cast to type to.
 

Friends

struct _HoldAside
 
void swap (VtValue &lhs, VtValue &rhs)
 Overloaded swap() for generic code/stl/etc.
 
size_t hash_value (VtValue const &val)
 
template<typename T >
bool operator== (VtValue const &lhs, T const &rhs)
 Tests for equality.
 
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.
 
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.
 

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

}
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:164
#define TF_REGISTRY_FUNCTION(KEY_TYPE)
Define a function that is called on demand by TfRegistryManager.

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 163 of file value.h.

Constructor & Destructor Documentation

◆ VtValue() [1/4]

VtValue ( )
inline

Default ctor gives empty VtValue.

Definition at line 861 of file value.h.

◆ VtValue() [2/4]

VtValue ( VtValue const &  other)
inline

Copy construct with other.

Definition at line 864 of file value.h.

◆ VtValue() [3/4]

VtValue ( VtValue &&  other)
inlinenoexcept

Move construct with other.

Definition at line 869 of file value.h.

◆ VtValue() [4/4]

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 boost::python::object, produce a VtValue holding a TfPyObjWrapper.

Definition at line 879 of file value.h.

◆ ~VtValue()

~VtValue ( )
inline

Destructor.

Definition at line 910 of file value.h.

Member Function Documentation

◆ CanCast()

bool CanCast ( ) const
inline

Return if this can be cast to T.

See also
Held-type Conversion with VtValue::Cast

Definition at line 1281 of file value.h.

◆ CanCastFromTypeidToTypeid()

static bool 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 1233 of file value.h.

◆ CanCastToTypeid()

bool 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 1295 of file value.h.

◆ CanCastToTypeOf()

bool 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 1288 of file value.h.

◆ CanHash()

VT_API bool CanHash ( ) const

Return true if the held object provides a hash implementation.

◆ Cast() [1/2]

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 1246 of file value.h.

◆ Cast() [2/2]

static 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 1204 of file value.h.

◆ CastToTypeid() [1/2]

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 1270 of file value.h.

◆ CastToTypeid() [2/2]

static VT_API 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

◆ CastToTypeOf() [1/2]

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 1259 of file value.h.

◆ CastToTypeOf() [2/2]

static VT_API 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

◆ Get() [1/2]

T Get ( ) &&
inline

Definition at line 1153 of file value.h.

◆ Get() [2/2]

T const & 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 1137 of file value.h.

◆ GetArraySize()

size_t GetArraySize ( ) const
inline

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

Definition at line 1090 of file value.h.

◆ GetElementTypeid()

VT_API std::type_info const & GetElementTypeid ( ) const

Return the typeid of elements in a array valued type.

If not holding an array valued type, return typeid(void).

◆ GetHash()

VT_API size_t GetHash ( ) const

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

◆ GetKnownValueTypeIndex()

int 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 1109 of file value.h.

◆ GetType()

VT_API TfType GetType ( ) const

Returns the TfType of the type held by this value.

◆ GetTypeid()

VT_API std::type_info const & GetTypeid ( ) const

Returns the typeid of the type held by this value.

◆ GetTypeName()

VT_API std::string GetTypeName ( ) const

Return the type name of the held typeid.

◆ GetWithDefault()

T 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 1171 of file value.h.

◆ IsArrayValued()

VT_API bool IsArrayValued ( ) const

Returns true iff this is holding an array type (see VtIsArray<>).

◆ IsEmpty()

bool IsEmpty ( ) const
inline

Returns true iff this value is empty.

Definition at line 1300 of file value.h.

◆ IsHolding()

bool IsHolding ( ) const
inline

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

Definition at line 1081 of file value.h.

◆ Mutate()

std::enable_if_t< std::is_same< T, typename Vt_ValueGetStored< T >::Type >::value, bool > 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 1054 of file value.h.

◆ operator!=()

bool operator!= ( const VtValue rhs) const
inline

Definition at line 1346 of file value.h.

◆ operator=() [1/5]

VtValue & operator= ( char *  cstr)
inline

Assigning a char * gives a VtValue holding a std::string.

Definition at line 967 of file value.h.

◆ operator=() [2/5]

VtValue & operator= ( char const *  cstr)
inline

Assigning a char const * gives a VtValue holding a std::string.

Definition at line 959 of file value.h.

◆ operator=() [3/5]

VtValue & operator= ( T const &  obj)

Assignment operator from any type.

◆ operator=() [4/5]

VtValue & operator= ( VtValue &&  other)
inlinenoexcept

Move assignment from another VtValue.

Definition at line 920 of file value.h.

◆ operator=() [5/5]

VtValue & operator= ( VtValue const &  other)
inline

Copy assignment from another VtValue.

Definition at line 913 of file value.h.

◆ operator==()

bool operator== ( const VtValue rhs) const
inline

Test two values for equality.

Definition at line 1334 of file value.h.

◆ RegisterCast()

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

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

Definition at line 1177 of file value.h.

◆ RegisterSimpleBidirectionalCast()

static void RegisterSimpleBidirectionalCast ( )
inlinestatic

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

Definition at line 1191 of file value.h.

◆ RegisterSimpleCast()

static void RegisterSimpleCast ( )
inlinestatic

Register a simple cast from VtValue holding From to VtValue.

Definition at line 1184 of file value.h.

◆ Remove()

T 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 1030 of file value.h.

◆ Swap() [1/2]

void Swap ( T &  rhs)

Swap the held value with rhs. If this value is holding a T,.

◆ Swap() [2/2]

VtValue & Swap ( VtValue rhs)
inlinenoexcept

Swap this with rhs.

Definition at line 972 of file value.h.

◆ Take()

static 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);
static VtValue Take(T &obj)
Create a new VtValue, taking its contents from obj.
Definition: value.h:903

Rather than:

MyExpensiveObject obj = CreateObject();
return VtValue(obj);
VtValue()
Default ctor gives empty VtValue.
Definition: value.h:861

Definition at line 903 of file value.h.

◆ UncheckedGet() [1/2]

T UncheckedGet ( ) &&
inline

Definition at line 1126 of file value.h.

◆ UncheckedGet() [2/2]

T const & 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 1121 of file value.h.

◆ UncheckedMutate()

std::enable_if_t< std::is_same< T, typename Vt_ValueGetStored< T >::Type >::value > UncheckedMutate ( Fn &&  mutateFn)
inline

Invoke mutateFn, 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 1068 of file value.h.

◆ UncheckedRemove()

T 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 1041 of file value.h.

◆ UncheckedSwap() [1/2]

void UncheckedSwap ( T &  rhs)

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.

◆ UncheckedSwap() [2/2]

void 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 1024 of file value.h.

Friends And Related Function Documentation

◆ _HoldAside

friend struct _HoldAside
friend

Definition at line 826 of file value.h.

◆ hash_value

size_t hash_value ( VtValue const &  val)
friend

Definition at line 1308 of file value.h.

◆ operator!= [1/2]

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

Definition at line 1329 of file value.h.

◆ operator!= [2/2]

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

Tests for inequality.

Definition at line 1325 of file value.h.

◆ operator<<

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

Calls through to operator << on the held object.

◆ operator== [1/2]

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

Definition at line 1319 of file value.h.

◆ operator== [2/2]

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

Tests for equality.

Definition at line 1314 of file value.h.

◆ swap

void swap ( VtValue lhs,
VtValue rhs 
)
friend

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

Definition at line 984 of file value.h.


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