plist::NamedEnumeration< T > Class Template Reference

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

#include <plistPrimitives.h>

Inheritance diagram for plist::NamedEnumeration< T >:

[legend]

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

For the ultimate minimal binary size, explicitly declare a template specialization for each type you use: (note 'YOUR_T' is meant to be replaced!)
```
    // replace YOUR_T with the type you are using:
    template<> std::map<std::string,YOUR_T> plist::NamedEnumeration<YOUR_T>::namesToVals = std::map<std::string,YOUR_T>();
    template<> std::map<YOUR_T,std::string> plist::NamedEnumeration<YOUR_T>::valsToNames = std::map<YOUR_T,std::string>();
```
You can do this only once, in a single translation unit, yielding zero replication of symbols. For convenience, we provide a macro INSTANTIATE_NAMEDENUMERATION_STATICS(T) which will do this for you.

Definition at line 524 of file plistPrimitives.h.

List of all members.

Classes
struct	conversion_policy
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 NULL (i.e. names must be terminated with a NULL entry)
	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 &ne)
	assignment
const T &	operator* () const
	value access
	operator T () const
	automatic casting to the enumeration value
virtual NamedEnumeration &	operator= (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
void	set (long x)
	converts from a numeric value, may throw bad_format if strictValue is set
std::string	get () const
	return current value as a string
virtual bool	operator== (const PrimitiveBase &other)
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 NULL, 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 &v)
	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 &v)
	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	convert (long x, T &v) const
	attempts to convert x to T and store in v, but failing and returning false if strictValue is set and x does not correspond to a name
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
T	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)

Constructor & Destructor Documentation

template<typename T>

plist::NamedEnumeration< T >::NamedEnumeration ( )

constructor

Definition at line 527 of file plistPrimitives.h.

template<typename T>

plist::NamedEnumeration< T >::NamedEnumeration ( const NamedEnumeration< T > & ne )

copy constructor

Definition at line 528 of file plistPrimitives.h.

template<typename T>

plist::NamedEnumeration< T >::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 NULL (i.e. names must be terminated with a NULL entry)

Definition at line 529 of file plistPrimitives.h.

template<typename T>

plist::NamedEnumeration< T >::NamedEnumeration ( const T & v )

automatic casting from the enumeration

Definition at line 530 of file plistPrimitives.h.

Member Function Documentation

template<typename T>

void plist::NamedEnumeration< T >::addNameForVal	(	const std::string &	enumname,
		const T &	v
	)			`[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 756 of file plistPrimitives.h.

Referenced by plist::NamedEnumeration< T >::setPreferredNameForVal(), Config::sound_config::sound_config(), and Config::vision_config::vision_config().

template<typename T >

void plist::NamedEnumeration< T >::clearNames ( ) [static]

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

Definition at line 752 of file plistPrimitives.h.

template<typename T >

NamedEnumeration< T > * plist::NamedEnumeration< T >::clone ( ) const [virtual]

implements the clone function for NamedEnumeration<T>

Implements plist::ObjectBase.

Definition at line 691 of file plistPrimitives.h.

template<typename T>

bool plist::NamedEnumeration< T >::convert	(	long	x,
		T &	v
	)			const `[protected]`

attempts to convert x to T and store in v, but failing and returning false if strictValue is set and x does not correspond to a name

Definition at line 646 of file plistPrimitives.h.

template<typename T>

std::string plist::NamedEnumeration< T >::get ( ) const [virtual]

return current value as a string

Implements plist::PrimitiveBase.

Definition at line 616 of file plistPrimitives.h.

template<typename T >

void plist::NamedEnumeration< T >::getAllNames ( std::map< std::string, int > & names ) const [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 773 of file plistPrimitives.h.

template<typename T>

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

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

Definition at line 539 of file plistPrimitives.h.

template<typename T>

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

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

Definition at line 669 of file plistPrimitives.h.

template<typename T >

void plist::NamedEnumeration< T >::getPreferredNames ( std::map< int, std::string > & names ) const [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 768 of file plistPrimitives.h.

template<typename T>

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

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

Definition at line 538 of file plistPrimitives.h.

template<typename T>

const T& plist::NamedEnumeration< T >::getPreviousValue ( ) const

returns the previously assigned value

Definition at line 637 of file plistPrimitives.h.

template<typename T>

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

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

Definition at line 654 of file plistPrimitives.h.

template<typename T>

void plist::NamedEnumeration< T >::loadXML ( xmlNode * node ) [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 560 of file plistPrimitives.h.

template<typename T>

plist::NamedEnumeration< T >::operator T ( ) const

automatic casting to the enumeration value

Definition at line 536 of file plistPrimitives.h.

template<typename T>

const T& plist::NamedEnumeration< T >::operator* ( ) const

value access

Definition at line 535 of file plistPrimitives.h.

template<typename T>

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

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

Implements plist::NamedEnumerationBase.

Definition at line 545 of file plistPrimitives.h.

template<typename T>

NamedEnumeration& plist::NamedEnumeration< T >::operator= ( const NamedEnumeration< T > & ne )

assignment

Definition at line 533 of file plistPrimitives.h.

Referenced by plist::NamedEnumeration< shutter_speeds >::operator=().

template<typename T>

NamedEnumeration& plist::NamedEnumeration< T >::operator= ( const std::string & v )

assignment from string

Reimplemented from plist::NamedEnumerationBase.

Definition at line 532 of file plistPrimitives.h.

template<typename T>

NamedEnumeration& plist::NamedEnumeration< T >::operator= ( const T & v )

assignment from enumeration value (numeric)

Definition at line 531 of file plistPrimitives.h.

template<typename T>

virtual bool plist::NamedEnumeration< T >::operator== ( const PrimitiveBase & other ) [virtual]

Implements plist::PrimitiveBase.

Definition at line 624 of file plistPrimitives.h.

template<typename T>

void plist::NamedEnumeration< T >::saveXML ( xmlNode * node ) const [virtual]

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

Implements plist::ObjectBase.

Definition at line 587 of file plistPrimitives.h.

template<typename T>

void plist::NamedEnumeration< T >::set ( long x ) [virtual]

converts from a numeric value, may throw bad_format if strictValue is set

Implements plist::NamedEnumerationBase.

Definition at line 604 of file plistPrimitives.h.

template<typename T>

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

assign a new value

Implements plist::PrimitiveBase.

Definition at line 598 of file plistPrimitives.h.

template<typename T >

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

calls clearNames() and then resets the array of names, enumnames must be terminated with NULL, and the enumeration must be sequential starting at 0; these names become the "preferred" name for each value

Definition at line 714 of file plistPrimitives.h.

template<typename T>