Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Related Functions | List of all members
Teuchos::StringToIntegralParameterEntryValidator< IntegralType > Class Template Reference

Standard implementation of a ParameterEntryValidator that maps from a list of strings to an enum or integer value. More...

#include <Teuchos_StandardParameterEntryValidators.hpp>

Inheritance diagram for Teuchos::StringToIntegralParameterEntryValidator< IntegralType >:
Teuchos::ParameterEntryValidator Teuchos::Describable Teuchos::LabeledObject

Public Member Functions

Constructors
 StringToIntegralParameterEntryValidator (const ArrayView< const std::string > &strings, const std::string &defaultParameterName, const bool caseSensitive=true)
 Construct with a mapping from strings to the enum or integer values $0, 1, \dots, n-1$. More...
 
 StringToIntegralParameterEntryValidator (const ArrayView< const std::string > &strings, const ArrayView< const IntegralType > &integralValues, std::string const &defaultParameterName, const bool caseSensitive=true)
 Construct with a mapping from strings to specified enum or integer values. More...
 
 StringToIntegralParameterEntryValidator (const ArrayView< const std::string > &strings, const ArrayView< const std::string > &stringsDocs, const ArrayView< const IntegralType > &integralValues, const std::string &defaultParameterName, const bool caseSensitive=true)
 Construct with a mapping from strings (with documentation) to specified enum or integer values, and include documentation. More...
 
Validated lookup functions
IntegralType getIntegralValue (const std::string &str, const std::string &paramName="", const std::string &sublistName="") const
 For a string value, find its corresponding enum or integer value. More...
 
IntegralType getIntegralValue (const ParameterEntry &entry, const std::string &paramName="", const std::string &sublistName="", const bool activeQuery=true) const
 Find the enum or integer value for the given ParameterEntry. More...
 
std::string getStringValue (const ParameterEntry &entry, const std::string &paramName="", const std::string &sublistName="", const bool activeQuery=true) const
 Find the string value for the given ParameterEntry. More...
 
IntegralType getIntegralValue (ParameterList &paramList, const std::string &paramName, const std::string &defaultValue) const
 Get the integer enum value for the given parameter. More...
 
std::string getStringValue (ParameterList &paramList, const std::string &paramName, const std::string &defaultValue) const
 Lookup a parameter from a parameter list, validate the std::string value, and return the std::string value. More...
 
ValidStringsList getStringDocs () const
 Get a pointer to the array containing all the documentation strings. More...
 
const std::string & getDefaultParameterName () const
 Get the name of the default parameter for the validator. More...
 
std::string validateString (const std::string &str, const std::string &paramName="", const std::string &sublistName="") const
 Validate the std::string and pass it on. More...
 
bool isCaseSensitive () const
 Whether this validator is case sensitive. More...
 
Implementation of ParameterEntryValidator
const std::string getXMLTypeName () const
 
void printDoc (std::string const &docString, std::ostream &out) const
 Print documentation to the given output string. More...
 
ValidStringsList validStringValues () const
 
void validate (ParameterEntry const &entry, std::string const &paramName, std::string const &sublistName) const
 Validate the given ParameterEntry. More...
 
- Public Member Functions inherited from Teuchos::ParameterEntryValidator
 ParameterEntryValidator ()
 Default Constructor. More...
 
virtual void validateAndModify (std::string const &paramName, std::string const &sublistName, ParameterEntry *entry) const
 Validate and perhaps modify a parameter entry's value. More...
 
- Public Member Functions inherited from Teuchos::Describable
virtual std::string description () const
 Return a simple one-line description of this object. More...
 
virtual void describe (FancyOStream &out, const EVerbosityLevel verbLevel=verbLevel_default) const
 Print the object with some verbosity level to a FancyOStream. More...
 
void describe (std::ostream &out, const EVerbosityLevel verbLevel=verbLevel_default) const
 Version of describe() that takes an std::ostream instead of a FancyOStream. More...
 
virtual ~Describable ()
 Destructor (marked virtual for memory safety of derived classes). More...
 
- Public Member Functions inherited from Teuchos::LabeledObject
 LabeledObject ()
 Construct with an empty label. More...
 
virtual ~LabeledObject ()
 
virtual void setObjectLabel (const std::string &objectLabel)
 Set the object label (see LabeledObject). More...
 
virtual std::string getObjectLabel () const
 Get the object label (see LabeledObject). More...
 

Related Functions

(Note that these are not member functions.)

template<class IntegralType >
RCP
< StringToIntegralParameterEntryValidator
< IntegralType > > 
stringToIntegralParameterEntryValidator (ArrayView< const std::string > const &strings, std::string const &defaultParameterName)
 Nonmember constructor (see implementation). More...
 
template<class IntegralType >
RCP
< StringToIntegralParameterEntryValidator
< IntegralType > > 
stringToIntegralParameterEntryValidator (ArrayView< const std::string > const &strings, std::string const &defaultParameterName, const bool caseSensitive)
 Nonmember constructor (see implementation). More...
 
template<class IntegralType >
RCP
< StringToIntegralParameterEntryValidator
< IntegralType > > 
stringToIntegralParameterEntryValidator (ArrayView< const std::string > const &strings, ArrayView< const IntegralType > const &integralValues, std::string const &defaultParameterName)
 Nonmember constructor (see implementation). More...
 
template<class IntegralType >
RCP
< StringToIntegralParameterEntryValidator
< IntegralType > > 
stringToIntegralParameterEntryValidator (ArrayView< const std::string > const &strings, ArrayView< const IntegralType > const &integralValues, std::string const &defaultParameterName, const bool caseSensitive)
 Nonmember constructor (see implementation). More...
 
template<class IntegralType >
RCP
< StringToIntegralParameterEntryValidator
< IntegralType > > 
stringToIntegralParameterEntryValidator (ArrayView< const std::string > const &strings, ArrayView< const std::string > const &stringsDocs, ArrayView< const IntegralType > const &integralValues, std::string const &defaultParameterName)
 Nonmember constructor (see implementation). More...
 
template<class IntegralType >
RCP
< StringToIntegralParameterEntryValidator
< IntegralType > > 
stringToIntegralParameterEntryValidator (ArrayView< const std::string > const &strings, ArrayView< const std::string > const &stringsDocs, ArrayView< const IntegralType > const &integralValues, std::string const &defaultParameterName, const bool caseSensitive)
 Nonmember constructor (see implementation). More...
 

Additional Inherited Members

- Public Types inherited from Teuchos::ParameterEntryValidator
typedef unsigned int ValidatorID
 
typedef RCP< const Array
< std::string > > 
ValidStringsList
 
- Static Public Attributes inherited from Teuchos::Describable
static const EVerbosityLevel verbLevel_default = VERB_DEFAULT
 Default value for the verbLevel argument of describe(). More...
 

Detailed Description

template<class IntegralType>
class Teuchos::StringToIntegralParameterEntryValidator< IntegralType >

Standard implementation of a ParameterEntryValidator that maps from a list of strings to an enum or integer value.

Template Parameters
IntegralTypeThe enum or integer type of the result.

This class is useful for developers who are defining parameters in a ParameterList. Suppose that you want to define a parameter in a ParameterList with an enum value. Enum values do not come with a standard string representation. This makes it hard to read a ParameterList. Users would rather see the enum names, not integers. If you instead set a parameter with this validator, users can provide string names for the enum values, and the validator will automatically convert them to their enum values.

All constructors and nonmember "constructors" have the option make validation case insensitive. Validation is case sensitive by default. Case sensitivity applies only to the string values of the parameter, not the parameter's name. We implement case insensitivity by converting all strings to uppercase using the prevailing locale.

Teuchos uses StringToIntegralValidatorXMLConverter to convert this validator to and from an XML representation. Please see the documentation of that class to learn about the XML representation of this validator.

Definition at line 92 of file Teuchos_StandardParameterEntryValidators.hpp.

Constructor & Destructor Documentation

template<class IntegralType >
Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::StringToIntegralParameterEntryValidator ( const ArrayView< const std::string > &  strings,
const std::string &  defaultParameterName,
const bool  caseSensitive = true 
)

Construct with a mapping from strings to the enum or integer values $0, 1, \dots, n-1$.

All input arrays (one array, in this case) are copied.

Parameters
strings[in] Array of unique names for the enum or integer values. These are the strings which users will see and use when setting parameters. strings[i] will be associated with the enum or integer value i.
defaultParameterName[in] The default name of the parameter (used in error messages).
caseSensitive[in] Whether validation will be case sensitive. The default is true (case sensitive) Case will be determined based on the prevailing locale.

Definition at line 2408 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType>
Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::StringToIntegralParameterEntryValidator ( const ArrayView< const std::string > &  strings,
const ArrayView< const IntegralType > &  integralValues,
std::string const &  defaultParameterName,
const bool  caseSensitive = true 
)

Construct with a mapping from strings to specified enum or integer values.

All input arrays are copied.

Parameters
strings[in] Array of unique names for the enum or integer values. These are the strings which users will see and use when setting parameters. strings[i] will be associated with the enum or integer value integralValues[i].
integralValues[in] Array of the enum or integer values associated with strings[].
defaultParameterName[in] The default name of the parameter (used in error messages).
caseSensitive[in] Whether validation will be case sensitive. The default is true (case sensitive). Case will be determined based on the prevailing locale.
Precondition
strings.size() == integralValues.size()

Definition at line 2431 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType>
Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::StringToIntegralParameterEntryValidator ( const ArrayView< const std::string > &  strings,
const ArrayView< const std::string > &  stringsDocs,
const ArrayView< const IntegralType > &  integralValues,
const std::string &  defaultParameterName,
const bool  caseSensitive = true 
)

Construct with a mapping from strings (with documentation) to specified enum or integer values, and include documentation.

All input arrays are copied.

Parameters
strings[in] Array of unique names for the enum or integer values. These are the strings which users will see and use when setting parameters. strings[i] will be associated with the enum or integer value integralValues[i].
stringsDocs[in] Array of documentation strings for each string value above. stringsDocs[i] is the documentation for strings[i].
integralValues[in] Array of the enum or integer values associated with strings[].
defaultParameterName[in] The default name of the parameter (used in error messages).
caseSensitive[in] Whether validation will be case sensitive. The default is true (case sensitive). Case will be determined based on the prevailing locale.
Precondition
strings.size() == stringDocs.size()
strings.size() == integralValues.size()

Definition at line 2463 of file Teuchos_StandardParameterEntryValidators.hpp.

Member Function Documentation

template<class IntegralType >
IntegralType Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getIntegralValue ( const std::string &  str,
const std::string &  paramName = "",
const std::string &  sublistName = "" 
) const

For a string value, find its corresponding enum or integer value.

Parameters
str[in] String value to look up.
paramName[in] Optional parameter name; used to generate error messages.

If the std::string name str is invalid, this method will throw std::exception with a descriptive error message.

Definition at line 2505 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
IntegralType Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getIntegralValue ( const ParameterEntry entry,
const std::string &  paramName = "",
const std::string &  sublistName = "",
const bool  activeQuery = true 
) const

Find the enum or integer value for the given ParameterEntry.

Parameters
entry[in] Entry in the ParameterList. This results from calling the ParameterList's getEntry() method, using the parameter's name.
paramName[in] Optional parameter name; used to generate error messages.
sublistName[in] The name of the sublist.
activeQuery[in] If true, then this lookup will be recorded as an active query, which will set the parameter's isUsed flag to true.

Definition at line 2527 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
std::string Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getStringValue ( const ParameterEntry entry,
const std::string &  paramName = "",
const std::string &  sublistName = "",
const bool  activeQuery = true 
) const

Find the string value for the given ParameterEntry.

Parameters
entry[in] Entry in the ParameterList. This results from calling the ParameterList's getEntry() method, using the parameter's name.
paramName[in] Optional parameter name; used to generate error messages.
sublistName[in] The name of the sublist.
activeQuery[in] If true, then this lookup will be recorded as an active query, which will set the parameter's isUsed flag to true.

Definition at line 2549 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
IntegralType Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getIntegralValue ( ParameterList paramList,
const std::string &  paramName,
const std::string &  defaultValue 
) const

Get the integer enum value for the given parameter.

Look up a parameter from a parameter list, map from the std::string value in the ParameterEntry object to its corresponding integer enum value, and return the integer enum value.

Definition at line 2563 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
std::string Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getStringValue ( ParameterList paramList,
const std::string &  paramName,
const std::string &  defaultValue 
) const

Lookup a parameter from a parameter list, validate the std::string value, and return the std::string value.

Definition at line 2577 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
ParameterEntryValidator::ValidStringsList Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getStringDocs ( ) const

Get a pointer to the array containing all the documentation strings.

Returns
A point to the array containing all the documentation strings.

Definition at line 2591 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
const std::string & Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getDefaultParameterName ( ) const

Get the name of the default parameter for the validator.

Returns
The name of the default parameter for the validator.

Definition at line 2598 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
std::string Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::validateString ( const std::string &  str,
const std::string &  paramName = "",
const std::string &  sublistName = "" 
) const

Validate the std::string and pass it on.

Parameters
str[in] String that is being used to lookup the corresponding integral value.
name[in] Optional name that will be used to generate error messages.

If the std::string name str does not exist, the an std::exception will be thrown with a very descriptive error message.

Definition at line 2605 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType>
bool Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::isCaseSensitive ( ) const
inline

Whether this validator is case sensitive.

Case sensitivity is with respect to the string names, not the parameter name.

Definition at line 293 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
const std::string Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getXMLTypeName ( ) const
virtual
template<class IntegralType >
void Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::printDoc ( std::string const &  docString,
std::ostream &  out 
) const
virtual

Print documentation to the given output string.

Implements Teuchos::ParameterEntryValidator.

Definition at line 2626 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >
ParameterEntryValidator::ValidStringsList Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::validStringValues ( ) const
virtual
template<class IntegralType >
void Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::validate ( ParameterEntry const &  entry,
std::string const &  paramName,
std::string const &  sublistName 
) const
virtual

Validate the given ParameterEntry.

Implements Teuchos::ParameterEntryValidator.

Definition at line 2658 of file Teuchos_StandardParameterEntryValidators.hpp.

Friends And Related Function Documentation

template<class IntegralType >
RCP< StringToIntegralParameterEntryValidator< IntegralType > > stringToIntegralParameterEntryValidator ( ArrayView< const std::string > const &  strings,
std::string const &  defaultParameterName 
)
related

Nonmember constructor (see implementation).

template<class IntegralType >
RCP< StringToIntegralParameterEntryValidator< IntegralType > > stringToIntegralParameterEntryValidator ( ArrayView< const std::string > const &  strings,
std::string const &  defaultParameterName,
const bool  caseSensitive 
)
related

Nonmember constructor (see implementation).

template<class IntegralType >
RCP< StringToIntegralParameterEntryValidator< IntegralType > > stringToIntegralParameterEntryValidator ( ArrayView< const std::string > const &  strings,
ArrayView< const IntegralType > const &  integralValues,
std::string const &  defaultParameterName 
)
related

Nonmember constructor (see implementation).

template<class IntegralType >
RCP< StringToIntegralParameterEntryValidator< IntegralType > > stringToIntegralParameterEntryValidator ( ArrayView< const std::string > const &  strings,
ArrayView< const IntegralType > const &  integralValues,
std::string const &  defaultParameterName,
const bool  caseSensitive 
)
related

Nonmember constructor (see implementation).

template<class IntegralType >
RCP< StringToIntegralParameterEntryValidator< IntegralType > > stringToIntegralParameterEntryValidator ( ArrayView< const std::string > const &  strings,
ArrayView< const std::string > const &  stringsDocs,
ArrayView< const IntegralType > const &  integralValues,
std::string const &  defaultParameterName 
)
related

Nonmember constructor (see implementation).

template<class IntegralType >
RCP< StringToIntegralParameterEntryValidator< IntegralType > > stringToIntegralParameterEntryValidator ( ArrayView< const std::string > const &  strings,
ArrayView< const std::string > const &  stringsDocs,
ArrayView< const IntegralType > const &  integralValues,
std::string const &  defaultParameterName,
const bool  caseSensitive 
)
related

Nonmember constructor (see implementation).


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