Loading...
Searching...
No Matches
TfEnum Class Reference

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

#include <enum.h>

Public Member Functions

 TfEnum ()
 Default constructor assigns integer value zero.
 
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.
 
 TfEnum (const std::type_info &ti, int value)
 Initializes value to integral value value with enum type ti.
 
bool operator== (const TfEnum &t) const
 True if *this and t have both the same type and value.
 
bool operator!= (const TfEnum &t) const
 Inequality operator.
 
bool operator< (const TfEnum &t) const
 Less than comparison.
 
bool operator<= (const TfEnum &t) const
 Less than or equal operator.
 
bool operator> (const TfEnum &t) const
 Greater than operator.
 
bool operator>= (const TfEnum &t) const
 Greater than or equal operator.
 
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.
 
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.
 
template<class T >
bool IsA () const
 True if *this has been assigned any enumerated value of type T.
 
bool IsA (const std::type_info &t) const
 True if *this has been assigned any enumerated value of type T with typeid(T)==t.
 
const std::type_info & GetType () const
 Returns the type of the enum value, as an std::type_info.
 
const int & GetValueAsInt () const
 Returns the integral value of the enum value.
 
template<typename T >
GetValue () const
 Returns the enum value for the enum type T.
 
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.
 

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

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.
 
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.
 

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
An enum class that records both enum type and enum value.
Definition: enum.h:137
bool IsA() const
True if *this has been assigned any enumerated value of type T.
Definition: enum.h:232

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
// Register the names for the values:
}
// 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
static TF_API std::string GetName(TfEnum val)
Returns the name associated with an enumerated value.
static TF_API TfEnum GetValueFromFullName(const std::string &fullname, bool *foundIt=NULL)
Returns the enumerated value for a fully-qualified name.
static TF_API std::string GetFullName(TfEnum val)
Returns the fully-qualified name for an enumerated value.
#define TF_ADD_ENUM_NAME(VAL,...)
Macro used to associate a name with an enumerated value.
Definition: enum.h:470
#define TF_REGISTRY_FUNCTION(KEY_TYPE)
Define a function that is called on demand by TfRegistryManager.

Definition at line 136 of file enum.h.

Constructor & Destructor Documentation

◆ TfEnum() [1/3]

TfEnum ( )
inline

Default constructor assigns integer value zero.

Definition at line 140 of file enum.h.

◆ TfEnum() [2/3]

TfEnum ( 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 147 of file enum.h.

◆ TfEnum() [3/3]

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 158 of file enum.h.

Member Function Documentation

◆ _AddName()

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.

◆ AddName()

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 396 of file enum.h.

◆ GetAllNames() [1/3]

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 332 of file enum.h.

◆ GetAllNames() [2/3]

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.

◆ GetAllNames() [3/3]

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 316 of file enum.h.

◆ GetDisplayName()

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.

◆ GetFullName()

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.

◆ GetName()

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.

◆ GetType()

const std::type_info & GetType ( ) const
inline

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

Definition at line 243 of file enum.h.

◆ GetTypeFromName()

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.

◆ GetValue()

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 264 of file enum.h.

◆ GetValueAsInt()

const int & GetValueAsInt ( ) const
inline

Returns the integral value of the enum value.

Definition at line 248 of file enum.h.

◆ GetValueFromFullName()

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.

◆ GetValueFromName() [1/2]

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 350 of file enum.h.

◆ GetValueFromName() [2/2]

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().

◆ IntegralEnum()

static TfEnum IntegralEnum ( value)
inlinestatic

Definition at line 403 of file enum.h.

◆ IsA() [1/2]

bool IsA ( ) const
inline

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

Definition at line 232 of file enum.h.

◆ IsA() [2/2]

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 238 of file enum.h.

◆ IsKnownEnumType()

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()

operator T ( ) const
inline

Conversion operator for enum and integral types only.

Definition at line 277 of file enum.h.

◆ operator!=() [1/2]

bool operator!= ( const TfEnum t) const
inline

Inequality operator.

See also
TfEnum::operator==(const TfEnum&)

Definition at line 171 of file enum.h.

◆ operator!=() [2/2]

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

False if *this has been assigned with value.

Definition at line 212 of file enum.h.

◆ operator<()

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 179 of file enum.h.

◆ operator<=()

bool operator<= ( const TfEnum t) const
inline

Less than or equal operator.

See also
TfEnum::operator<(const TfEnum&)

Definition at line 186 of file enum.h.

◆ operator==() [1/2]

bool operator== ( const TfEnum t) const
inline

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

Definition at line 164 of file enum.h.

◆ operator==() [2/2]

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

True if *this has been assigned with value.

Definition at line 205 of file enum.h.

◆ operator>()

bool operator> ( const TfEnum t) const
inline

Greater than operator.

See also
TfEnum::operator<(const TfEnum&)

Definition at line 192 of file enum.h.

◆ operator>=()

bool operator>= ( const TfEnum t) const
inline

Greater than or equal operator.

See also
TfEnum::operator<(const TfEnum&)

Definition at line 198 of file enum.h.

Friends And Related Function Documentation

◆ operator!=

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

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

Definition at line 226 of file enum.h.

◆ operator==

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

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

Definition at line 219 of file enum.h.


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