All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Friends | List of all members
TfEnum Class Reference
Runtime Typing

An enum class that records both enum type and enum value. More...

Inherits totally_ordered< TfEnum >.

Public Member Functions

 TfEnum ()
 Default constructor assigns integer value zero. More...
 
template<class T >
 TfEnum (T value, std::enable_if_t< std::is_enum< T >::value > *=0)
 Initializes value to enum variable value of enum type T. More...
 
 TfEnum (const std::type_info &ti, int value)
 Initializes value to integral value value with enum type ti. More...
 
bool operator== (const TfEnum &t) const
 True if *this and t have both the same type and value. More...
 
bool operator< (const TfEnum &t) const
 Less than comparison. More...
 
template<class T >
std::enable_if_t< std::is_enum
< T >::value, bool > 		operator== (T value) const
 True if *this has been assigned with value. More...
 
template<class T >
std::enable_if_t< std::is_enum
< T >::value, bool > 		operator!= (T value) const
 False if *this has been assigned with value. More...
 
template<class T >
bool IsA () const
 True if *this has been assigned any enumerated value of type T. More...
 
bool IsA (const std::type_info &t) const
 True if *this has been assigned any enumerated value of type T with typeid(T)==t. More...
 
const std::type_info & GetType () const
 Returns the type of the enum value, as an std::type_info. More...
 
const int & GetValueAsInt () const
 Returns the integral value of the enum value. More...
 
template<typename T >
T GetValue () const
 Returns the enum value for the enum type T. More...
 
template<typename T , typename = typename std::enable_if< std::is_integral<T>::value || std::is_enum<T>::value>::type>
 operator T () const
 Conversion operator for enum and integral types only. More...
 

Static Public Member Functions

static TF_API void _AddName (TfEnum val, const std::string &valName, const std::string &displayName="")
 Associates a name with an enumerated value. More...
 
static void AddName (TfEnum val, const std::string &valName, const std::string &displayName="")
 Associates a name with an enumerated value. More...
 
template<typename T >
static TfEnum IntegralEnum (T value)
 
Retrieving Corresponding Names and Enumerated Values

The methods in this group can be used to retrieve corresponding names and values.

The correspondences are set up with the TF_ADD_ENUM_NAME() macro.

static TF_API std::string GetName (TfEnum val)
 Returns the name associated with an enumerated value. More...
 
static TF_API std::string GetFullName (TfEnum val)
 Returns the fully-qualified name for an enumerated value. More...
 
static TF_API std::string GetDisplayName (TfEnum val)
 Returns the display name for an enumerated value. More...
 
static std::vector< std::string > GetAllNames (TfEnum val)
 Returns a vector of all the names associated with an enum type. More...
 
static TF_API std::vector
< std::string > 		GetAllNames (const std::type_info &ti)
 
template<class T >
static std::vector< std::string > GetAllNames ()
 Returns a vector of all the names associated with an enum type. More...
 
static TF_API const
std::type_info * 		GetTypeFromName (const std::string &typeName)
 Returns the typeid for a given enum type name. More...
 
template<class T >
static T GetValueFromName (const std::string &name, bool *foundIt=NULL)
 Returns the enumerated value for a name. More...
 
static TF_API TfEnum GetValueFromName (const std::type_info &ti, const std::string &name, bool *foundIt=NULL)
 Returns the enumerated value for a name. More...
 
static TF_API TfEnum GetValueFromFullName (const std::string &fullname, bool *foundIt=NULL)
 Returns the enumerated value for a fully-qualified name. More...
 
static TF_API bool IsKnownEnumType (const std::string &typeName)
 Returns true if typeName is a known enum type. More...
 

Friends

template<class T >
std::enable_if_t< std::is_enum
< T >::value, bool > 		operator== (T val, TfEnum const &e)
 Compare a literal enum value val of enum type T with TfEnum e. More...
 
template<class T >
std::enable_if_t< std::is_enum
< T >::value, bool > 		operator!= (T val, TfEnum const &e)
 Compare a literal enum value val of enum type T with TfEnum e. More...
 

Detailed Description

An enum class that records both enum type and enum value.

Run-Time Typing

A TfEnum can hold an enum variable of any enum type, while still being able to distinguish between various enum types. Here is an example:

* enum Monsters { SULLEY = 0, MIKE, ROZ };
* enum Fish { NEMO = 0, FATHER, DORY };
*
* TfEnum t1 = MIKE,
* t2 = NEMO;
*
* t1 == MIKE; // yields true
* t2 == NEMO; // yields true
* t1 == t2; // yields false
* t1 == SULLEY; // yields false
*
* t1.IsA<Monsters>(); // yields true
* t1.IsA<Fish>(); // yields false
*

Even though NEMO and SULLEY both are represented with integral value zero, t1 and t2 compare false. A TfEnum can be passed by value, assigned, etc. just like a regular Enum variable. A TfEnum can also hold a plain integer, which will compare false against any other enum variable.

Associating Names with Enumerated Values

The TfEnum class can also be used to represent enumerated values as strings. This can be useful for storing enum values in files for later retrieval.

Use the TF_ADD_ENUM_NAME() macro to set up and enable strings for the values of an enum. Once this is done, several static TfEnum methods may be used to look up names corresponding to enum values and vice-versa.

For example, see TfRegistryManager to understand the use of the TF_REGISTRY_FUNCTION() macro below:

Enum Registration Macro

* // header file
* // Declare an enumerated type with some values
* enum Season {
* SPRING,
* SUMMER = 3, // It's ok to have initializers
* AUTUMN,
* WINTER
* };
*
* // source file
* #include "pxr/base/tf/registryManager.h"
* TF_REGISTRY_FUNCTION(TfEnum) {
* // Register the names for the values:
* TF_ADD_ENUM_NAME(SPRING);
* TF_ADD_ENUM_NAME(SUMMER);
* TF_ADD_ENUM_NAME(AUTUMN);
* TF_ADD_ENUM_NAME(WINTER);
* }
*
* // another source file:
*
* // Look up the name for a value:
* string name1 = TfEnum::GetName(SUMMER); // Returns "SUMMER"
* string name2 = TfEnum::GetFullName(SUMMER); // Returns "Season::SUMMER"
*
* // Look up the value for a name:
* bool found;
* Season s1 = TfEnum::GetValueFromName<Season>("AUTUMN", &found);
* // Returns 4, sets found to true
* Season s2 = TfEnum::GetValueFromName<Season>("MONDAY", &found);
* // Returns -1, sets found to false
*
* // Look up a fully-qualified name. Since this is not a templated
* // function, it has to return a generic value type, so we use
* // TfEnum.
* TfEnum s3 = TfEnum::GetValueFromFullName("Season::WINTER", &found);
* // Returns 5, sets found to \c true
*

Definition at line 139 of file enum.h.

Constructor & Destructor Documentation

TfEnum ( )
inline

Default constructor assigns integer value zero.

Definition at line 143 of file enum.h.

TfEnum ( T  value,
std::enable_if_t< std::is_enum< T >::value > *  = 0 
)
inline

Initializes value to enum variable value of enum type T.

Definition at line 150 of file enum.h.

TfEnum ( const std::type_info &  ti,
int  value 
)
inline

Initializes value to integral value value with enum type ti.

Warning
This is only for use in extreme circumstances; there is no way for an implementation to guarantee that ti is really an enum type, and/or that value is a valid value for that enum type.

Definition at line 161 of file enum.h.

Member Function Documentation

static TF_API void _AddName ( TfEnum  val,
const std::string &  valName,
const std::string &  displayName = "" 
)
static

Associates a name with an enumerated value.

Warning
This method is called by the TF_ADD_ENUM_NAME() macro, and should NOT be called directly. Instead, call AddName(), which does exactly the same thing.
static void AddName ( TfEnum  val,
const std::string &  valName,
const std::string &  displayName = "" 
)
inlinestatic

Associates a name with an enumerated value.

See Also
_AddName().

Definition at line 375 of file enum.h.

static std::vector<std::string> GetAllNames ( TfEnum  val)
inlinestatic

Returns a vector of all the names associated with an enum type.

This returns a vector of all the names associated with the enum that contains the type val. The names are not fully qualified. For example, TfEnum::GetAllNames(WINTER) would return a vector containing "SPRING", "SUMMER", "AUTUMN", and "WINTER".

If there are no such names registered, an empty vector is returned.

Definition at line 295 of file enum.h.

static TF_API std::vector<std::string> GetAllNames ( const std::type_info &  ti)
static

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

static std::vector<std::string> GetAllNames ( )
inlinestatic

Returns a vector of all the names associated with an enum type.

This returns a vector of all the names associated with the enum type T. The names are not fully qualified. For example, TfEnum::GetAllNames<Season>() would return a vector containing "SPRING", "SUMMER", "AUTUMN", and "WINTER".

If there are no such names registered, an empty vector is returned.

Definition at line 311 of file enum.h.

static TF_API std::string GetDisplayName ( TfEnum  val)
static

Returns the display name for an enumerated value.

This returns a user interface-suitable string for the given enumerated value.

static TF_API std::string GetFullName ( TfEnum  val)
static

Returns the fully-qualified name for an enumerated value.

This returns a fully-qualified enumerated value name (e.g., "Season::WINTER") associated with the given value. If there is no such name registered, an empty string is returned.

static TF_API std::string GetName ( TfEnum  val)
static

Returns the name associated with an enumerated value.

If there is no such name registered, an empty string is returned.

const std::type_info& GetType ( ) const
inline

Returns the type of the enum value, as an std::type_info.

Definition at line 222 of file enum.h.

static TF_API const std::type_info* GetTypeFromName ( const std::string &  typeName)
static

Returns the typeid for a given enum type name.

This returns a pointer to the type_info associated with the enum that has the type name typeName. If no such enum is registered, returns NULL.

T GetValue ( ) const
inline

Returns the enum value for the enum type T.

Warning
This function can cause your program to abort if not used properly.

If it is possible that the enum value is not of type T, first use IsA() to test whether the enum value is of type T before calling GetValue<T>().

Note that if IsA<T>() succeeds, then GetValue<T>() will also succeed.

Definition at line 243 of file enum.h.

const int& GetValueAsInt ( ) const
inline

Returns the integral value of the enum value.

Definition at line 227 of file enum.h.

static TF_API TfEnum GetValueFromFullName ( const std::string &  fullname,
bool *  foundIt = NULL 
)
static

Returns the enumerated value for a fully-qualified name.

This takes a fully-qualified enumerated value name (e.g., "Season::WINTER") and returns the associated value. If there is no such name, this returns -1. Since -1 can sometimes be a valid value, the foundIt flag pointer, if not NULL, is set to true if the name was found and false otherwise. Also, since this is not a templated function, it has to return a generic value type, so we use TfEnum.

static T GetValueFromName ( const std::string &  name,
bool *  foundIt = NULL 
)
inlinestatic

Returns the enumerated value for a name.

If there is no such name registered, this returns -1. Since -1 can sometimes be a valid value, the foundIt flag pointer, if not NULL, is set to true if the name was found and false otherwise.

Definition at line 329 of file enum.h.

static TF_API TfEnum GetValueFromName ( const std::type_info &  ti,
const std::string &  name,
bool *  foundIt = NULL 
)
static

Returns the enumerated value for a name.

This is a template-independent version of GetValueFromName().

bool IsA ( ) const
inline

True if *this has been assigned any enumerated value of type T.

Definition at line 211 of file enum.h.

bool IsA ( const std::type_info &  t) const
inline

True if *this has been assigned any enumerated value of type T with typeid(T)==t.

Definition at line 217 of file enum.h.

static TF_API bool IsKnownEnumType ( const std::string &  typeName)
static

Returns true if typeName is a known enum type.

If any enum whose demangled type name is typeName has been added via TF_ADD_ENUM_NAME(), this function returns true.

operator T ( ) const
inline

Conversion operator for enum and integral types only.

Definition at line 256 of file enum.h.

std::enable_if_t<std::is_enum<T>::value, bool> operator!= ( T  value) const
inline

False if *this has been assigned with value.

Definition at line 191 of file enum.h.

bool operator< ( const TfEnum &  t) const
inline

Less than comparison.

Enum values belonging to the same type are ordered according to their numeric value. Enum values belonging to different types are ordered in a consistent but arbitrary way which may vary between program runs.

Definition at line 176 of file enum.h.

bool operator== ( const TfEnum &  t) const
inline

True if *this and t have both the same type and value.

Definition at line 167 of file enum.h.

std::enable_if_t<std::is_enum<T>::value, bool> operator== ( T  value) const
inline

True if *this has been assigned with value.

Definition at line 184 of file enum.h.

Friends And Related Function Documentation

std::enable_if_t<std::is_enum<T>::value, bool> operator!= ( T  val,
TfEnum const &  e 
)
friend

Compare a literal enum value val of enum type T with TfEnum e.

Definition at line 205 of file enum.h.

std::enable_if_t<std::is_enum<T>::value, bool> operator== ( T  val,
TfEnum const &  e 
)
friend

Compare a literal enum value val of enum type T with TfEnum e.

Definition at line 198 of file enum.h.

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