simth::Property Class Reference

A Property for the configuration of a device. More...

#include <propertylist.h>

List of all members.

Public Types
typedef std::vector< std::pair< std::string, std::string > >	StringPairList
typedef std::vector< std::string >	list_string
typedef std::vector< int >	vector_int
typedef std::vector< double >	vector_double
enum	p_type {   bool_t, int_t, unsigned_t, double_t,   complex_t, string_t, list_string_t, enum_t,   sequencelength_t, vector_octal_int_t, vector_double_t, octal_int_t }
Public Member Functions
	Property (const std::string &name, p_type type, const std::string &default_value="", const std::string &description="", const StringPairList &possible_values=StringPairList(), bool enable_empty_default=false, bool obsolete=false, const std::string &grouping="")
	Property (const Property &p)
	Property ()
	~Property ()
template<>
void	setValue (const bool &value)
template<>
void	setValue (const int &value)
template<>
void	setValue (const unsigned &value)
template<>
void	setValue (const double &value)
template<>
void	setValue (const Complex &value)
template<>
void	setValue (const std::string &value)
template<>
void	setValue (const list_string &value)
template<>
void	setValue (const vector_int &value)
template<>
void	setValue (const vector_double &value)
template<>
const bool &	getValue (const bool &dummyargument) const
template<>
const int &	getValue (const int &dummyargument) const
template<>
const unsigned &	getValue (const unsigned &dummyargument) const
template<>
const double &	getValue (const double &dummyargument) const
template<>
const Complex &	getValue (const Complex &dummyargument) const
template<>
const std::string &	getValue (const std::string &dummyargument) const
template<>
const list_string &	getValue (const list_string &dummyargument) const
template<>
const vector_int &	getValue (const vector_int &dummyargument) const
template<>
const vector_double &	getValue (const vector_double &dummyargument) const
Information
const std::string &	getName () const
p_type	getType () const
const std::string &	getDefault_value () const
const std::string &	getDescription () const
bool	hasDefault () const
bool	isSet () const
bool	hasEmptyDefaultEnabled () const
const StringPairList &	getPossibleValues () const
bool	obsolete () const
const std::string &	grouping () const
Type-correct getter/setter
template<class T>
void	setValue (const T &value)
template<class T>
const T &	getValue (MSVC_WORKAROUND(const T &dummyargument=0)) const
String getter/setter
void	setValueStr (const std::string &v)
std::string	getValueStr () const
std::string	toString () const
Static Public Member Functions
static const char *	p_type_toString (p_type t)
static p_type	string_to_p_type (const std::string &t)
static list_string	supported_types ()
static list_string	string_to_list (const std::string &s)
Classes
union	value_u

---

Detailed Description

A Property for the configuration of a device.

A property is the mechanism to configure a Device's behaviour in a concrete simulation setup. A property has a name and a value and some more characteristics, and the value adjusts the actual behaviour of the Device at run time.

More precisely: A property has a name, a type, a default value and a description. Type-correct (template) functions for setting and getting the value are provided. The definition of all properties of a Device should be done in the devicelist XML files. The values for these properties are then filled in from the parameter file by the SimulationSystem when the concrete simulation is set up.

If you want to add another supported type, you need to do the following steps: 1. Add flag to p_type and union member to value_u; 2. Add specializations to the getValue(), setValue() members (below); 3. Add entries for your new type to the static functions supported_types(), string_to_p_type(), p_type_toString(); 4. Scan all member function implementations for the switch(type_) statement (including constructor, *copy constructor*, and destructor) and add handling of your type accordingly.

---

Member Typedef Documentation

EXPIMP_TEMPLATE template DLLIMPORT simth::Property::StringPairList

To save typing and avoid ambiguities: The type for a list/vector of string pairs.

EXPIMP_TEMPLATE template DLLIMPORT simth::Property::list_string

To save typing and avoid ambiguities: The type for a list of strings.

EXPIMP_TEMPLATE template DLLIMPORT simth::Property::vector_int

To save typing and avoid ambiguities: The type for a vector of int's.

EXPIMP_TEMPLATE template DLLIMPORT simth::Property::vector_double

To save typing and avoid ambiguities: The type for a vector of double's.

---

Member Enumeration Documentation

enum simth::Property::p_type

The type flags for the different types that a property can be. If you access this Property's value i.e. call getValue() and setValue() with a non-matching type as template argument, a std::runtime_error is thrown. Enumeration values: bool_t  Boolean value. int_t  Integer value. (May also be accessed as unsigned.) unsigned_t  Unsigned integer value. May also be accessed as a normal integer value. double_t  Double float value. complex_t  simth::Complex value which is a std::complex<double> string_t  std::string value. list_string_t  std::vector<std::string> value. enum_t  This is also a std::string value. WATCH OUT: This has nothing to do with the C type enum; instead, it is a std::string value, but with the additional restriction that the allowed values have to be one out of the StringPairList that was set in the constructor. In other words, for the compiler this is just a std::string, but the semantics are actually similar to the C type enum. sequencelength_t  This behaves like an unsigned integer value, except that when setting the value, any negative value is transformed to DataInterface::undefinedLength. vector_octal_int_t  A vector of integers, but the string value is interpreted as a sequence of octal numbers. Returns a std::vector<int>. vector_double_t  A vector of doubles octal_int_t  An integer value specified in octal notation. (May also be accessed as unsigned)

---

Constructor & Destructor Documentation

simth::Property::Property (  const std::string &  name, p_type  type, const std::string &  default_value = "", const std::string &  description = "", const StringPairList &  possible_values = StringPairList(), bool  enable_empty_default = false, bool  obsolete = false, const std::string &  grouping = "" )

Constructor. Parameters: name  The name of the new property. type  The type flag describing the type of the new property. default_value  The default value for this property, or the empty string (default) if none should be given. description  The human-readable description of what this property is about. possible_values  A list of possible values for this property. Each list element is a pair of strings; the first string in a pair is the possible value itself (similar to default_value), and the second string is the explanation for this value. Note: In the case of the type enum_t, the actual value of this Property is only allowed to be one out of the possible_value list. For all other types, these possible values are only optional proposals that can be presented to the user by some GUI. enable_empty_default  If true, then allow the empty string to be the default value. If false (default), the empty string will be interpreted such that this Property does not have any default value and the property requires to be set to some value. obsolete  Whether this Property is marked as obsolete or not (obsolete() returns true). grouping  The key for grouping several properties together, in alphabetic order (only used by the GUI). All properties with an identical grouping string will be shown in the same section of the property list, and the sections will be sorted alphabetically according to this grouping string.

simth::Property::Property (  const Property &  p  )

Copy constructor. Creates a by-value copy.

simth::Property::Property (   )

Default constructor -- needed for instantiating a std::map of this.

simth::Property::~Property (   )

Destructor.

---

Member Function Documentation

const std::string& simth::Property::getName (   )  const [inline]

Returns the name (the identifier) of this property.

p_type simth::Property::getType (   )  const [inline]

Returns the type flag of this property.

const std::string& simth::Property::getDefault_value (   )  const [inline]

Returns the default value of this property. If it doesn't have one, this returns the empty string.

const std::string& simth::Property::getDescription (   )  const [inline]

Returns the description of this property.

bool simth::Property::hasDefault (   )  const

Returns true if this property has a valid default value. This is the case either if a non-empty default string has been specified, or if the attribute enable_empty_default has been set to true.

bool simth::Property::isSet (   )  const [inline]

Returns true if this property was set to a certain value. Returns false if this property is still at its default setting.

bool simth::Property::hasEmptyDefaultEnabled (   )  const [inline]

Returns true if this property's default value is allowed to be the empty string. If false (default), then the empty string will be interpreted such that this Property does not have any default value and the property requires to be set to some value. That behaviour can be overridden if this boolean has been set to true.

const StringPairList& simth::Property::getPossibleValues (   )  const [inline]

Returns the list of possible values, if there are any. See the comment in the constructor: This is a list of possible values for this property. Each list element is a pair of strings; the first string in the pair is the possible value itself (similar to default_value), and the second string is the explanation for this value. The meaning of these possible values are as follows: In the case of the type enum_t, the actual value of this Property is only allowed to be one out of the possible_value list. For all other types, these possible values are only optional proposals that can be presented to the user by some GUI.

bool simth::Property::obsolete (   )  const [inline]

Whether this Property is marked as obsolete or not. If this is true, the GUI should not show this property, but in order to preserve backward compatibility (for old parameter files) this property still exists.

const std::string& simth::Property::grouping (   )  const [inline]

Returns a string that gives grouping hints for this property inside a long list of properties.

template<class T> void simth::Property::setValue (  const T &  value  )

Set this to the given value. If this template function is called with the wrong type is called, this will throw an exception.

template<class T> const T& simth::Property::getValue (  MSVC_WORKAROUND(const T &dummyargument=0)   )  const

Returns the current value. If this template function is called with the wrong type is called, this will throw an exception. This dummyargument needs to be used here because MSVC won't work otherwise. See http://support.microsoft.com/default.aspx?scid=kb;EN-US;240871

void simth::Property::setValueStr (  const std::string &  v  )

Set this to the given value, parsed from the given string.

std::string simth::Property::getValueStr (   )  const

Returns the current value as a string. Note: The returned string here can easily be different than the one specified at setValueStr(). It is, however, not (yet) guaranteed that when feeding this string into setValueStr() the value will remain the same.

std::string simth::Property::toString (   )  const

Returns a description of this property, formatted for usage in the simthetic debugging output. Output includes name, type, and value, but no trailing newline -- you might want to add that manually.

static const char* simth::Property::p_type_toString (  p_type  t  )  [static]

Returns a human-readable type string for the given type flag.

static p_type simth::Property::string_to_p_type (  const std::string &  t  )  [static]

Converts the given human-readable type string into the internal type flag.

static list_string simth::Property::supported_types (   )  [static]

Returns a list of all supported type strings.

static list_string simth::Property::string_to_list (  const std::string &  s  )  [static]

Splits a space-separated string into a list of strings, separating at each whitespace.

template<> void simth::Property::setValue (  const bool &  value  )

template<> void simth::Property::setValue (  const int &  value  )

template<> void simth::Property::setValue (  const unsigned &  value  )

template<> void simth::Property::setValue (  const double &  value  )

template<> void simth::Property::setValue (  const Complex &  value  )

template<> void simth::Property::setValue (  const std::string &  value  )

template<> void simth::Property::setValue (  const list_string &  value  )

template<> void simth::Property::setValue (  const vector_int &  value  )

template<> void simth::Property::setValue (  const vector_double &  value  )

template<> const bool& simth::Property::getValue (  const bool &  dummyargument  )  const

template<> const int& simth::Property::getValue (  const int &  dummyargument  )  const

template<> const unsigned& simth::Property::getValue (  const unsigned &  dummyargument  )  const

template<> const double& simth::Property::getValue (  const double &  dummyargument  )  const

template<> const Complex& simth::Property::getValue (  const Complex &  dummyargument  )  const

template<> const std::string& simth::Property::getValue (  const std::string &  dummyargument  )  const

template<> const list_string& simth::Property::getValue (  const list_string &  dummyargument  )  const

template<> const vector_int& simth::Property::getValue (  const vector_int &  dummyargument  )  const

template<> const vector_double& simth::Property::getValue (  const vector_double &  dummyargument  )  const

---