Gromacs  2020.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Types | Public Member Functions | Protected Types | Protected Member Functions
gmx::OptionStorageTemplateSimple< T > Class Template Referenceabstract

#include <gromacs/options/optionstoragetemplate.h>

+ Inheritance diagram for gmx::OptionStorageTemplateSimple< T >:
+ Collaboration diagram for gmx::OptionStorageTemplateSimple< T >:

Description

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

Simplified option storage template for options that have one-to-one value conversion.

Template Parameters
TAssignable type that stores a single option value.

To implement an option that always map a single input value to a single output value, derive from this class instead of OptionStorageTemplate. This class implements convertValue() in terms of two new virtual methods: initConverter() and processValue().

To specify how different types of values need to be converted, implement initConverter(). To do common post-processing of the values after conversion, but before they are added to the underlying storage, override processValue().

Public Types

typedef
OptionStorageTemplateSimple< 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

std::string typeString () const override=0
 Returns a short string describing the type of the option.
 
int valueCount () const override
 Returns the number of option values added so far. More...
 
std::vector< AnydefaultValues () const override
 Returns the default value(s) of the option. More...
 
std::vector< std::string > defaultValuesAsStrings () const override
 Returns the default value(s) of the option as strings. More...
 
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 OptionInfooptionInfo ()=0
 Returns an option info object corresponding to this option.
 
virtual std::string formatExtraDescription () const
 Formats additional description for the option. 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 Any &value)
 Adds a new value for the option. 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 Types

typedef
OptionValueConverterSimple< T > 
ConverterType
 Alias for the converter parameter type for initConverter().
 
typedef std::unique_ptr
< IOptionValueStore< T > > 
StorePointer
 Smart pointer for managing the final storage interface.
 

Protected Member Functions

template<class U >
 OptionStorageTemplateSimple (const OptionTemplate< T, U > &settings, OptionFlags staticFlags=OptionFlags())
 Initializes the storage.
 
 OptionStorageTemplateSimple (const AbstractOption &settings, typename OptionStorageTemplate< T >::StorePointer store)
 Initializes the storage.
 
std::vector< AnynormalizeValues (const std::vector< Any > &values) const override
 Converts given values to native representation for this option. More...
 
virtual void initConverter (ConverterType *converter)=0
 Specifies how different types are converted. More...
 
virtual T processValue (const T &value) const
 Post-processes a value after conversion to the output type. More...
 
virtual Any normalizeValue (const T &value) const
 Converts a single value to normalized type. More...
 
void clearSet () override
 Removes all values from temporary storage for a set. More...
 
virtual void processSetValues (ValueList *values)
 Processes values for a set after all have been converted. More...
 
void processSet () override
 Performs validation and/or actions once a set of values has been added. More...
 
void processAll () override
 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 addValue (const T &value)
 Adds a value to a temporary storage. More...
 
void commitValues ()
 Commits values added with addValue(). 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...
 
ArrayRef< T > values ()
 Provides derived classes access to the current list of values. More...
 
ArrayRef< const T > values () const
 Provides derived classes access to the current list of values.
 
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...
 

Member Function Documentation

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

Adds a value to a temporary storage.

Parameters
[in]valueValue to add. A copy is made.
Exceptions
std::bad_allocif out of memory.
InvalidInputErrorif 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.

void gmx::AbstractOptionStorage::appendValue ( const Any value)
inherited

Adds a new value for the option.

Parameters
[in]valueValue to convert.
Exceptions
InvalidInputErrorif value cannot be converted, or if there are too many values.

This method should only be called between startSet() and finishSet().

template<typename T >
void gmx::OptionStorageTemplate< T >::clearSet ( )
overrideprotectedvirtualinherited

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 ( )
protectedinherited

Commits values added with addValue().

Exceptions
std::bad_allocif 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 clearSet() if it is successful.

template<typename T >
std::vector< Any > gmx::OptionStorageTemplate< T >::defaultValues ( ) const
overridevirtualinherited

Returns the default value(s) of the option.

The returned values should all be of the same type, but returning each as a separate any is currently simpler.

Currently, this can only be called before option values have been assigned.

Implements gmx::AbstractOptionStorage.

template<typename T >
std::vector< std::string > gmx::OptionStorageTemplate< T >::defaultValuesAsStrings ( ) const
overridevirtualinherited

Returns the default value(s) of the option as strings.

If there is no default value, but defaultValueIfSet() is set, that is returned instead.

Currently, this can only be called before option values have been assigned.

OptionStorageTemplate implements handling of defaultValueIfSet() cases and composing the vector. Derived classes must implement formatSingleValue() to provide the actual formatting for a value of type T.

Implements gmx::AbstractOptionStorage.

void gmx::AbstractOptionStorage::finish ( )
inherited

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

Exceptions
InvalidInputErrorif the option is required but not set, or if all valid values together are invalid as a set.

This method should be called after all values have been provided with appendValue().

void gmx::AbstractOptionStorage::finishSet ( )
inherited

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

Exceptions
InvalidInputErrorif too few values have been provided, or if the valid values since previous startSet() are invalid as a set.

If the parameter is specified multiple times, finishSet() should be called after the values for each instance.

virtual std::string gmx::AbstractOptionStorage::formatExtraDescription ( ) const
inlinevirtualinherited

Formats additional description for the option.

If this method returns a non-empty string, it is appended to the plain description when printing help texts. The default implementation returns an empty string.

template<typename T>
virtual std::string gmx::OptionStorageTemplate< T >::formatSingleValue ( const T &  value) const
protectedpure virtualinherited

Formats a single value as a string.

Parameters
[in]valueValue to format.
Returns
value formatted as a string.

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

template<typename T>
virtual void gmx::OptionStorageTemplateSimple< T >::initConverter ( ConverterType converter)
protectedpure virtual

Specifies how different types are converted.

See OptionValueConverterSimple for more details.

bool gmx::AbstractOptionStorage::isBoolean ( ) const
inherited

Returns true if the option is a boolean option.

This is used to optionally support an alternative syntax where an option provided with no value sets the value to true and an option prefixed with "no" clears the value.

template<typename T>
virtual Any gmx::OptionStorageTemplateSimple< T >::normalizeValue ( const T &  value) const
inlineprotectedvirtual

Converts a single value to normalized type.

Parameters
[in]valueValue after conversion.
Returns
Value to store for the option.

This can be overridden to serialize a different type than T when using the option with KeyValueTreeObject.

template<typename T>
std::vector<Any> gmx::OptionStorageTemplateSimple< T >::normalizeValues ( const std::vector< Any > &  values) const
inlineoverrideprotectedvirtual

Converts given values to native representation for this option.

For example, strings are parsed to the type that is actually used to store the options.

The return value only depends on the option type, not on the current value of the option, and the current value in the option is not changed.

Implements gmx::AbstractOptionStorage.

template<typename T>
void gmx::OptionStorageTemplate< T >::processAll ( )
inlineoverrideprotectedvirtualinherited

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

Exceptions
InvalidInputErrorif 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 ( )
overrideprotectedvirtualinherited

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

Exceptions
InvalidInputErrorif 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)
inlineprotectedvirtualinherited

Processes values for a set after all have been converted.

Parameters
[in,out]valuesValid values in the set.
Exceptions
InvalidInputErrorif 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>
virtual T gmx::OptionStorageTemplateSimple< T >::processValue ( const T &  value) const
inlineprotectedvirtual

Post-processes a value after conversion to the output type.

Parameters
[in]valueValue after conversion.
Returns
Value to store for the option.

The default implementation only provides an identity mapping.

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

Sets the default value for the option.

Parameters
[in]valueDefault value to set.
Exceptions
std::bad_allocif 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)
protectedinherited

Sets the default value if set for the option.

Parameters
[in]valueDefault value to set.
Exceptions
std::bad_allocif out of memory.

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

void gmx::AbstractOptionStorage::setMaxValueCount ( int  count)
protectedinherited

Sets a new maximum number of values required in one set.

Parameters
[in]countNew maximum number of values (must be > 0, or -1 for no limit).
Exceptions
InvalidInputErrorif already provided values violate the limit.

If values have already been provided, it is checked that there are not too many.

Cannot be called for options with efOption_MultipleTimes set, because it is impossible to check the requirement after the values have been set. If attempted, will assert.

void gmx::AbstractOptionStorage::setMinValueCount ( int  count)
protectedinherited

Sets a new minimum number of values required in one set.

Parameters
[in]countNew minimum number of values (must be > 0).
Exceptions
InvalidInputErrorif already provided values violate the limit.

If values have already been provided, it is checked that there are enough.

Cannot be called for options with efOption_MultipleTimes set, because it is impossible to check the requirement after the values have been set. If attempted, will assert.

void gmx::AbstractOptionStorage::startSet ( )
inherited

Starts adding a new set of values for the option.

Exceptions
InvalidInputErrorif option is specified multiple times, but is not specified to accept it.

If the parameter is specified multiple times, startSet() should be called before the values for each instance.

Strong exception safety guarantee.

void gmx::AbstractOptionStorage::startSource ( )
inherited

Starts adding values from a new source for the option.

This marks the vurrent value of the option as a default value, causing next call to startSet() to clear it. This allows values from the new source to overwrite old values.

This method does not throw.

template<typename T>
int gmx::OptionStorageTemplate< T >::valueCount ( ) const
inlineoverridevirtualinherited

Returns the number of option values added so far.

Implements gmx::AbstractOptionStorage.

template<typename T>
ArrayRef<T> gmx::OptionStorageTemplate< T >::values ( )
inlineprotectedinherited

Provides derived classes access to the current list of values.

The non-const any should only be used from processAll() in derived classes if necessary.


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