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 >:

[legend]

Private Types
typedef std::map< std::string, IntegralType >	map_t

typedef std::map< IntegralType, std::string >	inv_map_t

Private Member Functions
void	init (const ArrayView< const std::string > &strings, const ArrayView< const IntegralType > &integralValues)
	Auxiliary method to simplify constructors. More...

void	setValidValues (ArrayView< const std::string > const &strings, ArrayView< const std::string > const *stringsDocs=NULL)

	StringToIntegralParameterEntryValidator ()

Static Private Member Functions
static std::string	upperCase (const std::string s)
	Return an upper-case copy of the string s. More...

Private Attributes
std::string	defaultParameterName_

std::string	validValues_

ValidStringsList	validStringValues_

ValidStringsList	validStringValuesDocs_

map_t	map_

inv_map_t	inv_map_

const bool	caseSensitive_

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...

Related Functions inherited from Teuchos::Describable
DescribableStreamManipulatorState	describe (const Describable &describable, const EVerbosityLevel verbLevel=Describable::verbLevel_default)
	Describable output stream manipulator. More...

std::ostream &	operator<< (std::ostream &os, const DescribableStreamManipulatorState &d)
	Output stream operator for Describable manipulator. More...

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...

Additional Inherited Members
Public Types inherited from Teuchos::ParameterEntryValidator
typedef unsigned int	ValidatorID

typedef RCP< const Array < std::string > >	ValidStringsList

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...

double	convertStringToDouble (std::string str) const

int	convertStringToInt (std::string str) const

int	convertStringToLongLong (std::string str) const

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...

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

IntegralType The 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 60 of file Teuchos_StandardParameterEntryValidators.hpp.

Member Typedef Documentation

template<class IntegralType>

typedef std::map<std::string,IntegralType> Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::map_t

private

Definition at line 305 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType>

typedef std::map<IntegralType,std::string> Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::inv_map_t

private

Definition at line 307 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 2411 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 2428 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 2445 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType>

Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::StringToIntegralParameterEntryValidator ( )

private

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 2501 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 2523 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 2571 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 2585 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 2599 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 2606 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 2613 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 261 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >

const std::string Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::getXMLTypeName ( ) const

virtual

Implements Teuchos::ParameterEntryValidator.

Definition at line 2629 of file Teuchos_StandardParameterEntryValidators.hpp.

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 2634 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >

ParameterEntryValidator::ValidStringsList Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::validStringValues ( ) const

virtual

Implements Teuchos::ParameterEntryValidator.

Definition at line 2659 of file Teuchos_StandardParameterEntryValidators.hpp.

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 2666 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType>

void Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::init	(	const ArrayView< const std::string > &	strings,
		const ArrayView< const IntegralType > &	integralValues
	)

private

Auxiliary method to simplify constructors.

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[]`.

Definition at line 2468 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType >

void Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::setValidValues	(	ArrayView< const std::string > const &	strings,
		ArrayView< const std::string > const *	stringsDocs = `NULL`
	)

private

Definition at line 2692 of file Teuchos_StandardParameterEntryValidators.hpp.

template<class IntegralType>

static std::string Teuchos::StringToIntegralParameterEntryValidator< IntegralType >::upperCase ( const std::string s )

inlinestaticprivate

Return an upper-case copy of the string s.

Definition at line 335 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
	)

template<class IntegralType >

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

template<class IntegralType >

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

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
	)

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
	)

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
	)