#include <BALL/DATATYPE/options.h>

Inheritance diagram for BALL::Options:

Public Member Functions
Constructors and Destructors
	Options ()

	Options (const Options &options)

virtual	~Options ()

Assignment
const Options &	operator= (const Options &options)

virtual void	clear ()

Predicates
bool	isInteger (const String &key) const

bool	isBool (const String &key) const

bool	isReal (const String &key) const

bool	isVector (const String &key) const

bool	isSet (const String &key) const

Inspectors and mutators
void	addParameterDescription (const String &key, String description, ParameterType type, list< String > *allowed_values=NULL)

const ParameterDescription *	getParameterDescription (const String &key) const

Options *	createSubcategory (String name)

Options *	getSubcategory (String name)

StringHashMap< Options * > ::Iterator	beginSubcategories ()

StringHashMap< Options * > ::Iterator	endSubcategories ()

void	setName (const String &name)

const String &	getName () const

String	get (const String &key) const

bool	getBool (const String &key) const

double	getReal (const String &key) const

Vector3	getVector (const String &key) const

long	getInteger (const String &key) const

void	set (const String &key, const String &value)

void	setReal (const String &key, const double value)

void	setVector (const String &key, const Vector3 &value)

void	setInteger (const String &key, const long value)

void	setBool (const String &key, const bool value)

String	setDefault (const String &key, const String &value)

long	setDefaultInteger (const String &key, const long value)

double	setDefaultReal (const String &key, const double value)

bool	setDefaultBool (const String &key, const bool value)

bool	readOptionFile (const String &filename)

bool	writeOptionFile (const String &filename) const

void	write (PersistenceManager &pm) const

bool	read (PersistenceManager &pm)

bool	operator== (const Options &option) const
	Equality operator. More...

bool	operator!= (const Options &option) const
	Inequality operator. More...

Debugging
virtual void	dump (std::ostream &s=std::cout, Size depth=0) const

Public Member Functions inherited from BALL::StringHashMap< String >
	StringHashMap ()

	StringHashMap (const StringHashMap &map)

virtual	~StringHashMap ()

void	destroy ()

void	set (const StringHashMap &hash_map)

const StringHashMap &	operator= (const StringHashMap &hash_map)
	Assign a hash map from another. More...

void	get (StringHashMap &hash_map) const
	Assigns the content of a hash map to another. More...

void	swap (StringHashMap &hash_map)
	Swaps the contents of two hash maps. More...

std::pair< Iterator, bool >	insert (const ValueType &obj)

::std::pair< Iterator, bool >	insert (const String &key, const String &value)

bool	remove (const String &key)

Size	getSize () const

bool	operator== (const StringHashMap< String > &hash_map) const

bool	operator!= (const StringHashMap< String > &hash_map) const

bool	has (const String &key) const

bool	isEmpty () const

void	host (Visitor< StringHashMap< String > > &visitor)

Public Member Functions inherited from BALL::HashMap< Key, T >
bool	has (const Key &key) const
	Test whether the map contains the given key. More...

const T &	operator[] (const Key &key) const
	Return a constant reference to the element whose key is `key`. More...

T &	operator[] (const Key &key)
	Return a mutable reference to the element whose key is `key`. If an element with the key `key` does not exist, it is inserted. More...

bool	operator== (const HashMap< Key, T > &rhs) const
	Equality operator. Check whether two two hashmaps contain the same elements. O(n) runtime. More...

Size	size () const

Static Public Attributes
Constants
static const Size	MAX_ENTRY_LENGTH

Protected Attributes
String	name_

StringHashMap < ParameterDescription >	descriptions_

StringHashMap< Options * >	subcategories_

Additional Inherited Members
Public Types inherited from BALL::StringHashMap< String >
typedef HashMap< String, String >::Iterator	Iterator

typedef HashMap< String, String >::ConstIterator	ConstIterator

typedef HashMap< String, String >::ValueType	ValueType

Public Types inherited from BALL::HashMap< Key, T >
typedef boost::unordered_map < Key, T >	Base

typedef Base::value_type	ValueType

typedef Key	KeyType

typedef Base::value_type *	PointerType

typedef Base::iterator	Iterator

typedef Base::const_iterator	ConstIterator

Detailed Description

Options class. This object is intended to store options for complex method calls. These options are stored as key/value pairs of String .

: Using this datastructure, options for force fields ( ForceField ), finit difference Poisson Boltzmann calculations ( FDPB ), or the results of calculations can be given, retrieved, stored into a file and retrieved from a file. This simplifies the handling of such complex parameter sets.

Definition at line 46 of file options.h.

Constructor & Destructor Documentation

BALL::Options::Options ( )

Default constructor. Creates a new and empty Options object.

BALL::Options::Options ( const Options & options )

Copy constructor. Creates a new option table from an existing one.

Parameters

options the options to be copied

virtual BALL::Options::~Options ( )

virtual

Destructor. Destructs the option table and frees all allocated memory.

See also: clear

Member Function Documentation

void BALL::Options::addParameterDescription	(	const String &	key,
		String	description,
		ParameterType	type,
		list< String > *	allowed_values = `NULL`
	)

StringHashMap<Options*>::Iterator BALL::Options::beginSubcategories ( )

Get an iterator to the first subcategory

virtual void BALL::Options::clear ( )

virtual

Clear method

Options* BALL::Options::createSubcategory ( String name )

Create a new subcategory of options.

Returns: a pointer to the newly created subcategory. Note that the Options instance that represents the subcategory belongs to the parent object, so do not delete it manually.

virtual void BALL::Options::dump	(	std::ostream &	s = `std::cout`,
		Size	depth = `0`
	)		const

virtual

Dumps the whole content of the object

StringHashMap<Options*>::Iterator BALL::Options::endSubcategories ( )

Get an iterator past the last subcategory

String BALL::Options::get ( const String & key ) const

Returns the value associated with the key. If the key does not exists an empty string is returned.

Parameters

key the key

Returns: String, the value

bool BALL::Options::getBool ( const String & key ) const

Returns the value associated with the key as bool. This method tries to convert the value associated with key to a bool value.

: If the value is neither "true", nor "false" or the key does not exist false is returned! You might want to check the value's validity as a bool first by calling isBool().

Parameters

key the key

Returns: bool, boolean value

long BALL::Options::getInteger ( const String & key ) const

Returns the value associated with the key as an integer. If the value corresponding to key could not be converted to an integer number or the key does not exists, zero is returned. It is possible to check for the validity of this conversion by calling isInteger() .

Returns: long the integer value

Parameters

key the key

const String& BALL::Options::getName ( ) const

Returns the option table's name.

const ParameterDescription* BALL::Options::getParameterDescription ( const String & key ) const

double BALL::Options::getReal ( const String & key ) const

Returns the value associated with the key as a floting point number. If the value could not be converted to a floating point number or the key does not exist a value of #0.0# is returned.

: You might want to check the value's validity as a floating point number first by calling isReal().

Parameters

key the key

Returns: float, floating point value

Options* BALL::Options::getSubcategory ( String name )

Search and return a subcategories of options.

Returns: a pointer to the newly created subcategory. Note that the Options instance that represents the subcategory belongs to the parent object, so do not delete it manually.
If no subcategory for the given name is found, a null-pointer is returned.

Vector3 BALL::Options::getVector ( const String & key ) const

Returns the value associated with the key as a Vector3 object. This method is useful to read threedimensional coordinates, points, etc. The value corresponding to key has to be of the form #(<float> <float> <float>)# (i.e. three floating point numbers separated by white blanks and surrounded by round brackets).

: If the content of the value is of a differnet format or the key does not exists, the content of the returned vector is undefined. You might therefore check the value's validity first by calling isVector .

Parameters

key the key

Returns: Vector3 vector containing the three coordinates

bool BALL::Options::isBool ( const String & key ) const

Returns true, if the value associated with the given key is a boolean. A boolean entry has either the value true or false.

Parameters

key String

Returns: true, if key is a boolean value

bool BALL::Options::isInteger ( const String & key ) const

Returns true, if the value associated with the given key is an integer

Parameters

key String

Returns: true, if key is an integer

bool BALL::Options::isReal ( const String & key ) const

Returns true, if the value associated with the given key is a real number

Parameters

key String

Returns: true, if key is a real number

bool BALL::Options::isSet ( const String & key ) const

Returns true, if a value is defined for the given key.

Parameters

key String

Returns: bool, true/false

bool BALL::Options::isVector ( const String & key ) const

Returns true, if the value associated with the given key can be read as a vector. This method simply checks whether the value is of the form #(<float> <float> <float>)# where #<float># represents an arbitrary floating point number.

Parameters

key String

Returns: true, if key represents a 3D vector of reals

bool BALL::Options::operator!= ( const Options & option ) const

Inequality operator.

const Options& BALL::Options::operator= ( const Options & options )

Assignment operator

bool BALL::Options::operator== ( const Options & option ) const

Equality operator.

bool BALL::Options::read ( PersistenceManager & pm )

Persistent stream reading. This method reads from the persistent stream using the readPrimitive method of the PersistenceManager.

Parameters

pm	the persistence manager

bool BALL::Options::readOptionFile ( const String & filename )

Reads options from a file. This method opens the file specified by filename. If the file could not be opened, the method returns false. Otherwise, the file is read line by line and each line is interpreted as a key (starting with the first non-blank character and terminated by the next blank) separated by a blank from a value (starting with the first non-blank charakter after the key and terminated by the end of the line). For each line either an existing key is updated with the value read, or a new key-value pair is created.

: Lines starting with '#', '!', or ';' are ignored and may be used as comments.

Parameters

filename the name of the file to be read

Returns

bool

true if the file could be read
false otherwise

void BALL::Options::set	(	const String &	key,
		const String &	value
	)

Assigns value to key. The string given as value is assigned to the key. If key didn't exist in the internal hash table, it is inserted.

Parameters

key the key

void BALL::Options::setBool	(	const String &	key,
		const bool	value
	)

Assigns the boolean value given by value to the table entry key. The value associated with key is either set to the string "true" or the string "false".

: If key didn't already exist, it is created.

Parameters

key	the key
value	the boolean value

String BALL::Options::setDefault	(	const String &	key,
		const String &	value
	)

Assigns the value only, if the key is not yet defined. If an entry for key exists, it is not modified. It is set to value otherwise.

See also: set

Parameters

key	the key
value	a new value

bool BALL::Options::setDefaultBool	(	const String &	key,
		const bool	value
	)

Assigns the value only if the key is not yet defined. If an entry for key exists, it is not modified. It is set to value otherwise.

See also: setBool

Parameters

key	the key
value	a new value

Returns: the value of key

long BALL::Options::setDefaultInteger	(	const String &	key,
		const long	value
	)

Assigns the value only, if the key is not yet defined. If an entry for key exists, it is not modified. It is set to value otherwise.

See also: setInteger

Parameters

key	the key
value	a new value

Returns: the value of key

double BALL::Options::setDefaultReal	(	const String &	key,
		const double	value
	)

Assigns the value only, if the key is not yet defined. If an entry for key exists, it is not modified. It is set to value otherwise.

See also: setReal

Parameters

key	the key
value	a new value

Returns: the value of key

void BALL::Options::setInteger	(	const String &	key,
		const long	value
	)

Assigns the integer given by value to key. value is first converted to a string, which is then stored in the hash table under key.

: If key didn't already exist, it is created.

Parameters

key	the key
value	the integer value

void BALL::Options::setName ( const String & name )

Sets the option table's name.

void BALL::Options::setReal	(	const String &	key,
		const double	value
	)

Assigns the real number given by value to key. value is first converted to a string, which is then stored in the option object.

: If key didn't already exist, it is created.

Parameters

value	the new value
key	the key

void BALL::Options::setVector	(	const String &	key,
		const Vector3 &	value
	)

Assigns a Vector3 object to the value corresponding to a key. The given Vector3 is converted to a string by the following call to sprintf:

: #sprintf(buffer, "(%f %f %f)", value.x, value.y, value.z)#

: The so-built string is then stored in the hash table under key.

: If key didn't already exist, it is created.

Parameters

key	the key
value	a vector

void BALL::Options::write ( PersistenceManager & pm ) const

Persistent stream writing. This method writes the strings using the writePrimitive method of the PersistenceManager.

Parameters

pm	the persistence manager

bool BALL::Options::writeOptionFile ( const String & filename ) const

Writes options to a file. This method opens or creates the file specified by filename. If the file could not be opened, the method returns false. The option table's name is writen in a line starting with '!'.

Parameters

filename the name of the file to write

Returns

bool

true if the file could be writen
false otherwise

See also: readOptionFile

Member Data Documentation

StringHashMap<ParameterDescription> BALL::Options::descriptions_

protected

Definition at line 385 of file options.h.

const Size BALL::Options::MAX_ENTRY_LENGTH

static

Maximum length for each entry (key + value): 1024 byte.

Definition at line 61 of file options.h.

String BALL::Options::name_

protected

Definition at line 384 of file options.h.

StringHashMap<Options*> BALL::Options::subcategories_

protected

Definition at line 386 of file options.h.

Public Member Functions

Static Public Attributes

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation