Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

plist::NamedEnumeration< T > Class Template Reference

#include <plistPrimitives.h>

Inheritance diagram for plist::NamedEnumeration< T >:

List of all members.


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 specified, you must order the array such that the enumeration value can be used as an index into the array. The array must be terminated with an empty element ("") so NamedEnumeration can tell how many elements there are.

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:
        template<typename T> std::map<std::string,T> plist::NamedEnumeration<T>::namesToVals;
        template<typename T> std::map<T,std::string> plist::NamedEnumeration<T>::valsToNames;
    
    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.

Definition at line 423 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
NamedEnumerationoperator= (const T &v)
 assignment from enumeration value (numeric)
NamedEnumerationoperator= (const std::string &v)
 assignment from string
NamedEnumerationoperator= (const NamedEnumeration &ne)
 assignment
const T & operator * () const
 value access
 operator T () const
 automatic casting to the enumeration value
virtual NamedEnumerationoperator= (const PrimitiveBase &pb)
 polymorphic assignment, throws bad_format if strictValue is requested and the value is invalid integer
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 long toLong () const
 return current value as an (long) integer (throws std::runtime_error exception if incompatable, e.g. dictionary or array to value type)
virtual double toDouble () const
 return current value as a double (throws std::runtime_error exception if incompatable, e.g. dictionary or array to value type)
virtual NamedEnumeration< T > * clone () const __attribute__((warn_unused_result))
 implements the clone function for NamedEnumeration<T>
const T & getPreviousValue () const
 returns the previously assigned value

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

val
 storage of enum value
prevVal
 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

Constructor & Destructor Documentation

template<typename T>
plist::NamedEnumeration< T >::NamedEnumeration (  )  [inline]

constructor

Definition at line 426 of file plistPrimitives.h.

template<typename T>
plist::NamedEnumeration< T >::NamedEnumeration ( const NamedEnumeration< T > &  ne  )  [inline]

copy constructor

Definition at line 427 of file plistPrimitives.h.

template<typename T>
plist::NamedEnumeration< T >::NamedEnumeration ( const T &  v,
const char *const *  enumnames 
) [inline]

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

Definition at line 428 of file plistPrimitives.h.

template<typename T>
plist::NamedEnumeration< T >::NamedEnumeration ( const T &  v  )  [inline]

automatic casting from the enumeration

Definition at line 429 of file plistPrimitives.h.


Member Function Documentation

template<typename T>
NamedEnumeration& plist::NamedEnumeration< T >::operator= ( const T &  v  )  [inline]

assignment from enumeration value (numeric)

Definition at line 430 of file plistPrimitives.h.

template<typename T>
NamedEnumeration& plist::NamedEnumeration< T >::operator= ( const std::string &  v  )  [inline]

assignment from string

Reimplemented from plist::NamedEnumerationBase.

Definition at line 431 of file plistPrimitives.h.

template<typename T>
NamedEnumeration& plist::NamedEnumeration< T >::operator= ( const NamedEnumeration< T > &  ne  )  [inline]

assignment

Definition at line 432 of file plistPrimitives.h.

template<typename T>
const T& plist::NamedEnumeration< T >::operator * (  )  const [inline]

value access

Definition at line 434 of file plistPrimitives.h.

template<typename T>
plist::NamedEnumeration< T >::operator T (  )  const [inline]

automatic casting to the enumeration value

Definition at line 435 of file plistPrimitives.h.

template<typename T>
void plist::NamedEnumeration< T >::setNames ( const char *const *  enumnames  )  [inline, static]

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

Definition at line 582 of file plistPrimitives.h.

template<typename T>
static const std::map<T,std::string>& plist::NamedEnumeration< T >::getPreferredNames (  )  [inline, static]

returns mapping from numeric value to "preferred" name (one-to-one)

Definition at line 437 of file plistPrimitives.h.

template<typename T>
static const std::map<std::string,T>& plist::NamedEnumeration< T >::getAllNames (  )  [inline, static]

returns mapping from names to values (many-to-one allowed)

Definition at line 438 of file plistPrimitives.h.

template<typename T>
void plist::NamedEnumeration< T >::clearNames (  )  [inline, static]

removes all names, thus causing only numeric values to be accepted

Definition at line 591 of file plistPrimitives.h.

Referenced by plist::NamedEnumeration< T >::setNames().

template<typename T>
void plist::NamedEnumeration< T >::addNameForVal ( const std::string &  enumname,
const T &  val 
) [inline, static]

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

Definition at line 595 of file plistPrimitives.h.

template<typename T>
void plist::NamedEnumeration< T >::setPreferredNameForVal ( const std::string &  enumname,
const T &  val 
) [inline, static]

replaces any previous "preferred" name for a specific value

Definition at line 602 of file plistPrimitives.h.

template<typename T>
virtual NamedEnumeration& plist::NamedEnumeration< T >::operator= ( const PrimitiveBase pb  )  [inline, virtual]

polymorphic assignment, throws bad_format if strictValue is requested and the value is invalid integer

Implements plist::NamedEnumerationBase.

Definition at line 444 of file plistPrimitives.h.

template<typename T>
void plist::NamedEnumeration< T >::loadXML ( xmlNode node  )  [inline, virtual]

interprets node as either a string holding the name, or a number corresponding to its index (name is preferred)

Reimplemented from plist::ObjectBase.

Definition at line 459 of file plistPrimitives.h.

template<typename T>
void plist::NamedEnumeration< T >::saveXML ( xmlNode node  )  const [inline, virtual]

saves name of current value (if available, index used otherwise) into node

Implements plist::ObjectBase.

Definition at line 486 of file plistPrimitives.h.

template<typename T>
void plist::NamedEnumeration< T >::set ( const std::string &  str  )  [inline, virtual]

assign a new value

Implements plist::PrimitiveBase.

Definition at line 497 of file plistPrimitives.h.

template<typename T>
std::string plist::NamedEnumeration< T >::get (  )  const [inline, virtual]

return current value as a string

Implements plist::PrimitiveBase.

Definition at line 504 of file plistPrimitives.h.

template<typename T>
virtual long plist::NamedEnumeration< T >::toLong (  )  const [inline, virtual]

return current value as an (long) integer (throws std::runtime_error exception if incompatable, e.g. dictionary or array to value type)

Implements plist::ObjectBase.

Definition at line 509 of file plistPrimitives.h.

template<typename T>
virtual double plist::NamedEnumeration< T >::toDouble (  )  const [inline, virtual]

return current value as a double (throws std::runtime_error exception if incompatable, e.g. dictionary or array to value type)

Implements plist::ObjectBase.

Definition at line 510 of file plistPrimitives.h.

template<typename T>
NamedEnumeration< T > * plist::NamedEnumeration< T >::clone (  )  const [inline, virtual]

implements the clone function for NamedEnumeration<T>

Implements plist::ObjectBase.

Definition at line 563 of file plistPrimitives.h.

template<typename T>
const T& plist::NamedEnumeration< T >::getPreviousValue (  )  const [inline]

returns the previously assigned value

Definition at line 515 of file plistPrimitives.h.

template<typename T>
void plist::NamedEnumeration< T >::getPreferredNames ( std::map< int, std::string > &  names  )  const [inline, protected, virtual]

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

Implements plist::NamedEnumerationBase.

Definition at line 606 of file plistPrimitives.h.

template<typename T>
void plist::NamedEnumeration< T >::getAllNames ( std::map< std::string, int > &  names  )  const [inline, protected, virtual]

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

Implements plist::NamedEnumerationBase.

Definition at line 611 of file plistPrimitives.h.

template<typename T>
bool plist::NamedEnumeration< T >::getValForName ( std::string  name,
T &  v 
) const [inline, protected]

sets v to the enumeration value named name; returns false if no such name is found

Definition at line 524 of file plistPrimitives.h.

template<typename T>
bool plist::NamedEnumeration< T >::getNameForVal ( const T &  v,
std::string &  name 
) const [inline, protected]

retrieves the "preferred" name for the enumeration value v; returns false if no name is registered

Definition at line 541 of file plistPrimitives.h.


Member Data Documentation

template<typename T>
T plist::NamedEnumeration< T >::val [protected]

storage of enum value

Definition at line 552 of file plistPrimitives.h.

Referenced by plist::NamedEnumeration< Config::vision_config::gain_levels >::operator=().

template<typename T>
T plist::NamedEnumeration< T >::prevVal [protected]

storage of enum value

Definition at line 553 of file plistPrimitives.h.

template<typename T>
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 557 of file plistPrimitives.h.

Referenced by plist::NamedEnumeration< T >::addNameForVal(), plist::NamedEnumeration< T >::clearNames(), plist::NamedEnumeration< T >::getAllNames(), and plist::NamedEnumeration< T >::setNames().

template<typename T>
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 560 of file plistPrimitives.h.

Referenced by plist::NamedEnumeration< T >::addNameForVal(), plist::NamedEnumeration< T >::clearNames(), plist::NamedEnumeration< T >::getPreferredNames(), plist::NamedEnumeration< T >::setNames(), and plist::NamedEnumeration< T >::setPreferredNameForVal().


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

Tekkotsu v4.0
Generated Thu Nov 22 00:58:58 2007 by Doxygen 1.5.4