Gromacs  2024.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 | Protected Attributes | Friends
gmx::OptionTemplate< T, U > Class Template Referenceabstract

#include <gromacs/options/abstractoption.h>

+ Inheritance diagram for gmx::OptionTemplate< T, U >:
+ Collaboration diagram for gmx::OptionTemplate< T, U >:

Description

template<typename T, class U>
class gmx::OptionTemplate< T, U >

Templated base class for constructing concrete option settings classes.

Template Parameters
TAssignable type that stores a single option value.
UType of the derived class.

This template is used as a base class like this:

class ConcreteOption : public OptionTemplate<int, ConcreteOption>
{
*

All public functions in this class return *this casted to a reference to U. They do not throw.

For examples of how to use classes derived from this class, see the class documentation for Options.

Public Types

typedef T ValueType
 Type that stores a single option value.
 
typedef U MyClass
 Alias for the derived class type.
 

Public Member Functions

MyClassdescription (const char *descr)
 Sets a description for the option. More...
 
MyClasshidden (bool bHidden=true)
 Hides the option from normal help output.
 
MyClassrequired (bool bRequired=true)
 Requires the option to be specified explicitly. More...
 
MyClassallowMultiple (bool bMulti=true)
 Allows the option to be specified multiple times.
 
MyClassvalueCount (int count)
 Requires exactly count values for the option.
 
MyClassmultiValue (bool bMulti=true)
 Allows any number of values for the option.
 
MyClassdefaultValue (const T &defaultValue)
 Sets a default value for the option. More...
 
MyClassdefaultValueIfSet (const T &defaultValue)
 Sets a default value for the option when it is set. More...
 
MyClassstore (T *store)
 Stores value(s) in memory pointed by store. More...
 
MyClassstoreCount (int *countptr)
 Stores number of values in the value pointed by countptr. More...
 
MyClassstoreVector (std::vector< T > *store)
 Stores option values in the provided vector. More...
 
MyClassstoreIsSet (bool *store)
 Stores whether the option was explicitly set. More...
 

Protected Types

typedef OptionTemplate< T, U > MyBase
 Alias for the template class for use in base classes.
 

Protected Member Functions

 OptionTemplate (const char *name)
 Initializes the name and default values for an option.
 
const T * defaultValue () const
 Returns a pointer to user-specified default value, or NULL if there is none.
 
const T * defaultValueIfSet () const
 Returns a pointer to user-specified default value, or NULL if there is none.
 
T * store () const
 Returns a pointer to the storage location, or NULL if none specified.
 
std::vector< T > * storeVector () const
 Returns a pointer to the storage vector, or NULL if none specified.
 
MyClassme ()
 Returns *this casted into MyClass to reduce typing.
 
virtual AbstractOptionStoragecreateStorage (const OptionManagerContainer &managers) const =0
 Creates a default storage object for the option. More...
 
void setDescription (const char *descr)
 Sets the description for the option.
 
void setStoreIsSet (bool *store)
 Sets the storage location for whether the option is set.
 
void setFlag (OptionFlag flag)
 Sets a flag for the option.
 
void setFlag (OptionFlag flag, bool bSet)
 Sets or clears a flag for the option.
 
void clearFlag (OptionFlag flag)
 Clears a flag for the option.
 
bool isVector () const
 Returns true if the option is vector-valued.
 
void setVector ()
 Sets the option to be vector-valued. More...
 
void setValueCount (int count)
 Sets the required number of values for the option.
 

Protected Attributes

int minValueCount_
 Minimum number of values required for the option.
 
int maxValueCount_
 Maximum number of values allowed for the option.
 

Friends

class OptionStorageTemplate< T >
 Needed to initialize storage from this class without otherwise unnecessary accessors.
 

Member Function Documentation

virtual AbstractOptionStorage* gmx::AbstractOption::createStorage ( const OptionManagerContainer managers) const
protectedpure virtualinherited

Creates a default storage object for the option.

Parameters
[in]managersManager container (unused if the option does not use a manager).
Returns
The created storage object.
Exceptions
APIErrorif invalid option settings have been provided.

This method is called by Options::addOption() when initializing an option from the settings.

Derived classes should implement the method to create an actual storage object and populate it with correct values. They should also throw APIError if they detect problems.

Should only be called by Options::addOption().

The ownership of the return value is passed, but is not using a smart pointer to avoid introducing such a dependency in an installed header. The implementation will always consist of a single new call and returning that value, and the caller always immediately wraps the pointer in a smart pointer, so there is not exception safety issue.

template<typename T, class U>
MyClass& gmx::OptionTemplate< T, U >::defaultValue ( const T &  defaultValue)
inline

Sets a default value for the option.

Parameters
[in]defaultValueDefault value.

If the option is never set, the default value is copied to the assigned storage. Note that if the option is not set and there is no default value, the storage is not altered, which can also be used to provide a default value. The latter method has to be used if the option can take multiple values.

defaultValue is copied when the option is created.

template<typename T, class U>
MyClass& gmx::OptionTemplate< T, U >::defaultValueIfSet ( const T &  defaultValue)
inline

Sets a default value for the option when it is set.

Parameters
[in]defaultValueDefault value.

This value is used if the option is set, but no value is provided. If the option is never set, the value set with defaultValue() is used. Can only be used for options that accept a single value.

defaultValue is copied when the option is created.

template<typename T, class U>
MyClass& gmx::OptionTemplate< T, U >::description ( const char *  descr)
inline

Sets a description for the option.

Parameters
[in]descrDescription to set.

String in descr is copied when the option is created.

template<typename T, class U>
MyClass& gmx::OptionTemplate< T, U >::required ( bool  bRequired = true)
inline

Requires the option to be specified explicitly.

Note that if you specify defaultValue() together with required(), the user is not required to explicitly provide the option. In this case, required() only affects possible help output.

void gmx::AbstractOption::setVector ( )
inlineprotectedinherited

Sets the option to be vector-valued.

This method is provided for convenience to make management of value counts easier. In order to implement a vector-valued option, the class derived from AbstractOption should expose a method that calls this method, and the storage object derived from AbstractOptionStorage should check isVector(). If only a single value is provided, the storage object should fill the whole vector with that value.

The length of the vector (the value of maxValueCount_) must be fixed. The default length is 3 elements.

template<typename T, class U>
MyClass& gmx::OptionTemplate< T, U >::store ( T *  store)
inline

Stores value(s) in memory pointed by store.

Parameters
[in]storeStorage for option value(s).

The caller is responsible for allocating enough memory such that the any allowed number of values fits into the array pointed by store. If there is no maximum allowed number or if the maximum is inconveniently large, storeVector() should be used.

For information on when values are available in the storage, see storeVector().

The pointer provided should remain valid as long as the associated Options object exists.

template<typename T, class U>
MyClass& gmx::OptionTemplate< T, U >::storeCount ( int *  countptr)
inline

Stores number of values in the value pointed by countptr.

Parameters
[in]countptrStorage for the number of values.

For information on when values are available in the storage, see storeVector().

The pointers provided should remain valid as long as the associated Options object exists.

template<typename T, class U>
MyClass& gmx::OptionTemplate< T, U >::storeIsSet ( bool *  store)
inline

Stores whether the option was explicitly set.

Parameters
[in]storeVariable to store the flag in.

The value is set to false on creation of the option, and to true as soon as a value is assigned to the option. A default value does not set the flag to true, but assignment that uses defaultValueIfSet() does.

The pointer provided should remain valid as long as the associated Options object exists.

template<typename T, class U>
MyClass& gmx::OptionTemplate< T, U >::storeVector ( std::vector< T > *  store)
inline

Stores option values in the provided vector.

Parameters
[in]storeVector to store option values in.

Values are added to the vector after each successful set of values is parsed. Note that for some options, the value may be changed later, and is only guaranteed to be correct after Options::finish() has been called.

The pointer provided should remain valid as long as the associated Options object exists.


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