#include <gromacs/options/optionstoragetemplate.h>

Inheritance diagram for gmx::OptionStorageTemplate< T >:

Collaboration diagram for gmx::OptionStorageTemplate< T >:

Description

template<typename T>
class gmx::OptionStorageTemplate< T >

Templated base class for constructing option value storage classes.

Template Parameters

T	Assignable type that stores a single option value.

Provides an implementation of the clearSet(), valueCount(), and processSet() methods of AbstractOptionStorage, as well as a basic no-action implementation of processAll(). Two new virtual methods are added: processSetValues() and refreshValues(). The default implementation of processSetValues() does nothing, and refreshValues() is used to update secondary storage after values have been added/changed. This leaves typeString(), formatValue(), and convertValue() to be implemented in derived classes. processSetValues() and processAll() can also be implemented if necessary.

Implements transaction support for adding values within a set: all calls to addValue() add the value to a temporary storage, processSetValues() operates on this temporary storage, and commitValues() then copies these values to the real storage. commitValues() provides a strong exception safety guarantee for the process (and it only throws if it runs out of memory).

Public Types
typedef OptionStorageTemplate< T >	MyBase
	Alias for the template class for use in base classes.

typedef std::vector< T >	ValueList
	Type of the container that contains the current values.

Public Member Functions
virtual std::string	typeString () const =0
	Returns a short string describing the type of the option.

virtual int	valueCount () const
	Returns the number of option values added so far. More...

virtual std::string	formatValue (int i) const
	Returns the i'th value formatted as a string. More...

Public Member Functions inherited from gmx::AbstractOptionStorage
bool	isSet () const
	Returns true if the option has been set.

bool	isBoolean () const
	Returns true if the option is a boolean option. More...

bool	isHidden () const
	Returns true if the option is a hidden option.

bool	isRequired () const
	Returns true if the option is required.

bool	isVector () const
	Returns true if the option is vector-valued.

const std::string &	name () const
	Returns the name of the option.

const std::string &	description () const
	Returns the description of the option set by the calling code.

bool	defaultValueIfSetExists () const
	Returns true if defaultValueIfSet() value is specified.

int	minValueCount () const
	Returns the minimum number of values required in one set.

int	maxValueCount () const
	Returns the maximum allowed number of values in one set (-1 = no limit).

virtual OptionInfo &	optionInfo ()=0
	Returns an option info object corresponding to this option.

virtual std::string	formatExtraDescription () const
	Formats additional description for the option. More...

std::string	formatDefaultValueIfSet () const
	Returns the default value if set for the option as a string. More...

void	startSource ()
	Starts adding values from a new source for the option. More...

void	startSet ()
	Starts adding a new set of values for the option. More...

void	appendValue (const std::string &value)
	Adds a new value for the option, converting it from a string. More...

void	finishSet ()
	Performs validation and/or actions once a set of values has been added. More...

void	finish ()
	Performs validation and/or actions once all values have been added. More...

Protected Member Functions
template<class U >
	OptionStorageTemplate (const OptionTemplate< T, U > &settings, OptionFlags staticFlags=OptionFlags())
	Initializes the storage from option settings. More...

	OptionStorageTemplate (const AbstractOption &settings)
	Initializes the storage from base option settings. More...

virtual void	clearSet ()
	Removes all values from temporary storage for a set. More...

virtual void	convertValue (const std::string &value)=0
	Adds a new value, converting it from a string. More...

virtual void	processSetValues (ValueList *values)
	Processes values for a set after all have been converted. More...

virtual void	processSet ()
	Performs validation and/or actions once a set of values has been added. More...

virtual void	processAll ()
	Performs validation and/or actions once all values have been added. More...

virtual std::string	formatSingleValue (const T &value) const =0
	Formats a single value as a string. More...

void	clear ()
	Removes all values from the storage. More...

void	addValue (const T &value)
	Adds a value to a temporary storage. More...

void	commitValues ()
	Commits values added with addValue(). More...

virtual void	refreshValues ()
	Updates alternative store locations. More...

void	setDefaultValue (const T &value)
	Sets the default value for the option. More...

void	setDefaultValueIfSet (const T &value)
	Sets the default value if set for the option. More...

ValueList &	values ()
	Provides derived classes access to the current list of values. More...

const ValueList &	values () const
	Provides derived classes access to the current list of values.

Protected Member Functions inherited from gmx::AbstractOptionStorage
	AbstractOptionStorage (const AbstractOption &settings, OptionFlags staticFlags)
	Initializes the storage object from the settings object. More...

void	markAsSet ()
	Marks the option as set.

bool	hasFlag (OptionFlag flag) const
	Returns true if the given flag is set.

void	setFlag (OptionFlag flag)
	Sets the given flag.

void	clearFlag (OptionFlag flag)
	Clears the given flag.

void	setMinValueCount (int count)
	Sets a new minimum number of values required in one set. More...

void	setMaxValueCount (int count)
	Sets a new maximum number of values required in one set. More...

Additional Inherited Members
Static Protected Attributes inherited from gmx::AbstractOptionStorage
static const int	DefaultValueIfSetIndex = -1
	Index used with formatValue() for formatting default value if set.

Constructor & Destructor Documentation

template<typename T>

template<class U >

gmx::OptionStorageTemplate< T >::OptionStorageTemplate	(	const OptionTemplate< T, U > &	settings,
		OptionFlags	staticFlags = `OptionFlags()`
	)

explicitprotected

Initializes the storage from option settings.

Parameters

[in]	settings	Option settings.
[in]	staticFlags	Option flags that are always set and specify generic behavior of the option.

Exceptions

APIError if invalid settings have been provided.

template<typename T >

gmx::OptionStorageTemplate< T >::OptionStorageTemplate ( const AbstractOption & settings )

explicitprotected

Initializes the storage from base option settings.

Parameters

[in] settings Option settings.

Exceptions

APIError if invalid settings have been provided.

This constructor works for cases where there is no matching OptionTemplate (e.g., EnumOption).

Member Function Documentation

template<typename T>

void gmx::OptionStorageTemplate< T >::addValue ( const T & value )

protected

Adds a value to a temporary storage.

Parameters

[in] value Value to add. A copy is made.

Exceptions

std::bad_alloc	if out of memory.
InvalidInputError	if the maximum value count has been reached.

Derived classes should call this function from the convertValue() implementation to add converted values to the storage. If the maximum value count has been reached, the value is discarded and an exception is thrown.

If adding values outside convertValue() (e.g., to set a custom default value), derived classes should call clearSet() before adding values (unless in the constructor) and commitValues() once all values are added.

template<typename T>

void gmx::OptionStorageTemplate< T >::clear ( )

inlineprotected

Removes all values from the storage.

Does not throw.

template<typename T >

void gmx::OptionStorageTemplate< T >::clearSet ( )

protectedvirtual

Removes all values from temporary storage for a set.

This function is always called before starting to add values to a set, allowing the storage to clear its internal buffers.

Should not throw.

Implements gmx::AbstractOptionStorage.

template<typename T >

void gmx::OptionStorageTemplate< T >::commitValues ( )

protected

Commits values added with addValue().

Exceptions

std::bad_alloc if out of memory.

If this function succeeds, values added with addValue() since the previous clearSet() are added to the storage for the option. Only throws in out-of-memory conditions, and provides the strong exception safety guarantee as long as the copy constructor of T does not throw.

See addValue() for cases where this method should be used in derived classes.

Calls refreshValues() and clearSet() if it is successful.

template<typename T>

virtual void gmx::OptionStorageTemplate< T >::convertValue ( const std::string & value )

protectedpure virtual

Adds a new value, converting it from a string.

Parameters

[in] value String value to convert.

Exceptions

InvalidInputError if value is not valid for this option or if there have been too many values in the set.

This method may be called multiple times if the underlying option is defined to accept multiple values.

See Also: OptionStorageTemplate::convertValue()

Derived classes should call addValue() after they have converted value to the storage type. It is allowed to call addValue() more than once, or not at all. OptionsAssigner::appendValue() provides the same exception safety guarantee as this method, so it should be considered whether the implementation can be made strongly exception safe.

Implements gmx::AbstractOptionStorage.

template<typename T>

virtual std::string gmx::OptionStorageTemplate< T >::formatSingleValue ( const T & value ) const

protectedpure virtual

Formats a single value as a string.

Parameters

[in] value Value to format.

Returns: value formatted as a string.

The derived class must provide this method to format values a strings. Called by formatValue() to do the actual formatting.

Implemented in gmx::EnumOptionStorage, gmx::StringOptionStorage, gmx::FloatOptionStorage, gmx::DoubleOptionStorage, gmx::Int64OptionStorage, anonymous_namespace{abstractoptionstorage.cpp}::MockOptionStorage, gmx::IntegerOptionStorage, gmx::SelectionOptionStorage, gmx::BooleanOptionStorage, and gmx::FileNameOptionStorage.

template<typename T >

std::string gmx::OptionStorageTemplate< T >::formatValue ( int i ) const

virtual

Returns the i'th value formatted as a string.

If i is DefaultValueIfSetIndex, should format the default value if set (see OptionTemplate::defaultValueIfSet()).

OptionStorageTemplate implements handling of DefaultValueIfSetIndex in this method, as well as checking that i is a valid index. Derived classes must implement formatSingleValue() to provide the actual formatting for a value of type T.

Implements gmx::AbstractOptionStorage.

template<typename T>

virtual void gmx::OptionStorageTemplate< T >::processAll ( )

inlineprotectedvirtual

Performs validation and/or actions once all values have been added.

Exceptions

InvalidInputError if all provided values are not valid as a set.

This method is always called once.

If the method throws, implementation should take care to leave the option in a consistent, meaningful state. However, currently none of the implementations actually throw in any situation where the option may be left in an inconsistent state.

The implementation in OptionStorageTemplate does nothing.

Implements gmx::AbstractOptionStorage.

template<typename T >

void gmx::OptionStorageTemplate< T >::processSet ( )

protectedvirtual

Performs validation and/or actions once a set of values has been added.

Exceptions

InvalidInputError if the values in the set are not valid as a whole.

This method may be called multiple times if the underlying option can be specified multiple times. This method is not currently called if one of the convertValue() calls throwed.

Todo:: Improve the call semantics.

See Also: OptionStorageTemplate::processSetValues()

OptionStorageTemplate implements transaction support for a set of values in this method (see the class description), and provides a more detailed processSetValues() method that can be overridden in subclasses to process the actual values. Derived classes should override that method instead of this one if set value processing is necessary.

Implements gmx::AbstractOptionStorage.

template<typename T>

virtual void gmx::OptionStorageTemplate< T >::processSetValues ( ValueList * values )

inlineprotectedvirtual

Processes values for a set after all have been converted.

Parameters

[in,out] values Valid values in the set.

Exceptions

InvalidInputError if the values do not form a valid set.

This method is called after all convertValue() calls for a set. values contains all values that were validly converted by convertValue(). The derived class may alter the values, but should in such a case ensure that a correct number of values is produced. If the derived class throws, all values in values are discarded.

template<typename T >

void gmx::OptionStorageTemplate< T >::refreshValues ( )

protectedvirtual

Updates alternative store locations.

Derived classes should override this method if they implement alternative store locations, and copy/translate values from the values() vector to these alternative storages. They should also call the base class implementation as part of their implementation.

Should be called in derived classes if values are modified directly through the values() method, e.g., in processAll(). Does not need to be called if commitValues() is used.

Does not throw, and derived classes should not change that.

template<typename T>

void gmx::OptionStorageTemplate< T >::setDefaultValue ( const T & value )

protected

Sets the default value for the option.

Parameters

[in] value Default value to set.

Exceptions

std::bad_alloc if out of memory.

This method can be used from the derived class constructor to programmatically set a default value.

template<typename T>

void gmx::OptionStorageTemplate< T >::setDefaultValueIfSet ( const T & value )

protected

Sets the default value if set for the option.

Parameters

[in] value Default value to set.

Exceptions

std::bad_alloc if out of memory.

This method can be used from the derived class constructor to programmatically set a default value.

template<typename T>

virtual int gmx::OptionStorageTemplate< T >::valueCount ( ) const

inlinevirtual

Returns the number of option values added so far.

Implements gmx::AbstractOptionStorage.

template<typename T>

ValueList& gmx::OptionStorageTemplate< T >::values ( )

inlineprotected

Provides derived classes access to the current list of values.

The non-const variant should only be used from processAll() in derived classes if necessary, and refreshValues() should be called if any changes are made.

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

src/gromacs/options/abstractoption.h
src/gromacs/options/optionstoragetemplate.h

Description

template<typename T> class gmx::OptionStorageTemplate< T >

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation

template<typename T>
class gmx::OptionStorageTemplate< T >