Teuchos - Trilinos Tools Package Version of the Day
Related Functions
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

List of all members.

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$.
 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.
 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.
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.
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.
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.
IntegralType getIntegralValue (ParameterList &paramList, const std::string &paramName, const std::string &defaultValue) const
 Get the integer enum value for the given parameter.
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.
ValidStringsList getStringDocs () const
 Get a pointer to the array containing all the documentation strings.
const std::string & getDefaultParameterName () const
 Get the name of the default parameter for the validator.
std::string validateString (const std::string &str, const std::string &paramName="", const std::string &sublistName="") const
 Validate the std::string and pass it on.
bool isCaseSensitive () const
 Whether this validator is case sensitive.
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.
ValidStringsList validStringValues () const
 
void validate (ParameterEntry const &entry, std::string const &paramName, std::string const &sublistName) const
 Validate the given ParameterEntry.

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).
template<class IntegralType >
RCP
< StringToIntegralParameterEntryValidator
< IntegralType > > 
stringToIntegralParameterEntryValidator (ArrayView< const std::string > const &strings, std::string const &defaultParameterName, const bool caseSensitive)
 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)
 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)
 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)
 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)
 Nonmember constructor (see implementation).

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 88 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 2125 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 2148 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 2180 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 2222 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 2244 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 2266 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 2280 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 2294 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 2308 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 2315 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 2322 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 289 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 2343 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 2375 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:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines