plist::NamedEnumeration< T > Class Template Reference
#include <plistPrimitives.h>
Inheritance diagram for plist::NamedEnumeration< T >:
Detailed Description
template<typename T>
class plist::NamedEnumeration< T >
Provides an interface for the use of enumerations in a plist -- you can specify values by either the string name or the corresponding integer value.
Where an array of names is required, you must order the array such that the enumeration value can be used as an index into the array. The 'maxval' parameters should be one above the maximum enumeration -- if your enumeration runs sequentially from 0 to n, max should be the number of enumerations: n+1
Binary size and symbol definition: this class contains two static STL maps for storing the string names of the enumeration values. The problem is that due to the way static members of templates are handled, you will wind up with extensive symbol declarations in each translation unit which references this header, which can lead to significant binary bloat (particularly with debugging symbols). The solution is to limit the instantiation of these statics.
- Easy way out: define USE_GLOBAL_PLIST_STATICS, which will then declare the statics here in the header, and allow the duplication to occur (which is fine for small projects or if you don't reference this header widely)
- Otherwise, you can then declare: in the translation units where you introduce new types to the template parameter. This will greatly limit symbol replication, although there will still be some minor duplication if more than just the "new" types are found in the current unit. You may prefer to call the macro INSTANTIATE_ALL_NAMEDENUMERATION_STATICS() to ensure future compatability in the unlikely event more statics are added in the future.
template<typename T> std::map<std::string,T> plist::NamedEnumeration<T>::namesToVals; template<typename T> std::map<T,std::string> plist::NamedEnumeration<T>::valsToNames;
- For the ultimate minimal binary size, explicitly declare each time you introduce a new type: For convenience, we provide a macro INSTANTIATE_NAMEDENUMERATION_STATICS(T) which will do this for you.
// replace T with the type you are using: template<> std::map<std::string,T> plist::NamedEnumeration<T>::namesToVals = std::map<std::string,T>(); \ template<> std::map<T,std::string> plist::NamedEnumeration<T>::valsToNames = std::map<T,std::string>();
Definition at line 348 of file plistPrimitives.h.
Public Member Functions | |
| NamedEnumeration () | |
| constructor | |
| NamedEnumeration (const NamedEnumeration &ne) | |
| copy constructor | |
| NamedEnumeration (const T &v, const char *const *enumnames) | |
| constructor, pass initial value, array of strings (the names); assumes enumeration is sequential starting at 0, and runs until the names entry is an empty string (i.e. names must be terminated with "") | |
| NamedEnumeration (const T &v) | |
| automatic casting from the enumeration | |
| NamedEnumeration & | operator= (const T &v) |
| assignment from enumeration value (numeric) | |
| NamedEnumeration & | operator= (const std::string &v) |
| assignment from string | |
| NamedEnumeration & | operator= (const NamedEnumeration< T > &ne) |
| assignment | |
| const T & | operator * () const |
| value access | |
| operator T () const | |
| automatic casting to the enumeration value | |
| void | loadXML (xmlNode *node) |
| interprets node as either a string holding the name, or a number corresponding to its index (name is preferred) | |
| void | saveXML (xmlNode *node) const |
| saves name of current value (if available, index used otherwise) into node | |
| void | set (const std::string &str) |
| assign a new value | |
| std::string | get () const |
| return current value as a string | |
|
virtual NamedEnumeration< T > * | clone () const __attribute__((warn_unused_result)) |
| implements the clone function for NamedEnumeration<T> | |
Static Public Member Functions | |
| static void | setNames (const char *const *enumnames) |
| calls clearNames() and then resets the array of names, enumnames must be terminated with an empty string (""), and the enumeration must be sequential starting at 0; these names become the "preferred" name for each value | |
|
static const std::map< T, std::string > & | getPreferredNames () |
| returns mapping from numeric value to "preferred" name (one-to-one) | |
|
static const std::map< std::string, T > & | getAllNames () |
| returns mapping from names to values (many-to-one allowed) | |
| static void | clearNames () |
| removes all names, thus causing only numeric values to be accepted | |
| static void | addNameForVal (const std::string &enumname, const T &val) |
| adds an alternative name mapping to the specified numeric value; if the value doesn't already have a name, this is also the "preferred" name | |
| static void | setPreferredNameForVal (const std::string &enumname, const T &val) |
| replaces any previous "preferred" name for a specific value | |
Protected Member Functions | |
| virtual void | getPreferredNames (std::map< int, std::string > &names) const |
| provides the generic access to values and names from NamedEnumerationBase; protected because if you know the full type, better to use the static version of the function | |
| virtual void | getAllNames (std::map< std::string, int > &names) const |
| provides the generic access to values and names from NamedEnumerationBase; protected because if you know the full type, better to use the static version of the function | |
| bool | getValForName (std::string name, T &v) const |
| sets v to the enumeration value named name; returns false if no such name is found | |
| bool | getNameForVal (const T &v, std::string &name) const |
| retrieves the "preferred" name for the enumeration value v; returns false if no name is registered | |
Protected Attributes | |
| T | val |
| storage of enum value | |
Static Protected Attributes | |
| static std::map< std::string, T > | namesToVals |
| look up table of string names to enum values (can have multiple string names mapping to same enum -- deprecated values for example) | |
| static std::map< T, std::string > | valsToNames |
| look up table of enum values to preferred display name (by default, first name given) | |
Classes | |
| struct | conversion_policy |
Member Data Documentation
std::map<std::string,T> plist::NamedEnumeration< T >::namesToVals [static, protected] |
look up table of string names to enum values (can have multiple string names mapping to same enum -- deprecated values for example)
See class notes regarding instantiation options for static values like this
Definition at line 459 of file plistPrimitives.h.
Referenced by plist::NamedEnumeration< T >::addNameForVal(), plist::NamedEnumeration< T >::clearNames(), plist::NamedEnumeration< T >::getAllNames(), plist::NamedEnumeration< shutter_speeds >::getAllNames(), plist::NamedEnumeration< shutter_speeds >::getValForName(), and plist::NamedEnumeration< T >::setNames().
std::map<T,std::string> plist::NamedEnumeration< T >::valsToNames [static, protected] |
look up table of enum values to preferred display name (by default, first name given)
See class notes regarding instantiation options for static values like this
Definition at line 462 of file plistPrimitives.h.
Referenced by plist::NamedEnumeration< T >::addNameForVal(), plist::NamedEnumeration< T >::clearNames(), plist::NamedEnumeration< T >::getPreferredNames(), plist::NamedEnumeration< shutter_speeds >::getPreferredNames(), plist::NamedEnumeration< shutter_speeds >::getValForName(), plist::NamedEnumeration< T >::setNames(), and plist::NamedEnumeration< T >::setPreferredNameForVal().
The documentation for this class was generated from the following file:
