Teuchos - Trilinos Tools Package: Teuchos::ParameterList Class Reference

List of all members.


Public Types
Public types
typedef Map::const_iterator	ConstIterator
	Parameter container const iterator typedef.
Public Member Functions
Constructors/Destructor.
	ParameterList ()
	Constructor.
	ParameterList (const std::string &name)
	Constructor.
	ParameterList (const ParameterList &source)
	Copy Constructor.
virtual	~ParameterList ()
	Deconstructor.
Set Functions
ParameterList &	setName (const std::string &name)
	Set the name of `*this` list.
ParameterList &	operator= (const ParameterList &source)
ParameterList &	setParameters (const ParameterList &source)
ParameterList &	setParametersNotAlreadySet (const ParameterList &source)
ParameterList &	disableRecursiveValidation ()
template<typename T>
ParameterList &	set (std::string const &name, T const &value, std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
	Sets different types of parameters. The type depends on the second entry.
ParameterList &	set (std::string const &name, char value[], std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
	Template specialization for the case when a user sets the parameter with a character std::string in parenthesis.
ParameterList &	set (std::string const &name, const char value[], std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
	Template specialization for the case when a user sets the parameter with a character std::string in parenthesis.
ParameterList &	set (std::string const &name, ParameterList const &value, std::string const &docString="")
	Template specialization for the case when a user sets the parameter with a ParameterList.
ParameterList &	setEntry (const std::string &name, const ParameterEntry &entry)
	Set a parameter directly as a ParameterEntry.
Get Functions
template<typename T>
T &	get (const std::string &name, T def_value)
	Retrieves parameter `name` of type `T` from list, if it exists, else the `def_value` is used to enter a new parameter into the list.
std::string &	get (const std::string &name, char def_value[])
	Template specialization of get, where the nominal value is a character std::string in parenthesis. Both char* and std::string are stored as strings and return std::string values.
std::string &	get (const std::string &name, const char def_value[])
	Template specialization of get, where the nominal value is a character std::string in parenthesis. Both char* and std::string are stored as strings and return std::string values.
template<typename T>
T &	get (const std::string &name)
	Retrieves parameter `name` of type `T` from a list, an `Exceptions::InvalidParameter` std::exception is thrown if this parameter doesn't exist (`Exceptions::InvalidParameterName`) or is the wrong type (`Exceptions::InvalidParameterName`).
template<typename T>
const T &	get (const std::string &name) const
	Retrieves parameter `name` of type `T` from a constant list, an `Exceptions::InvalidParameter` std::exception is thrown if this parameter doesn't exist (`Exceptions::InvalidParameterName`) or is the wrong type (`Exceptions::InvalidParameterName`).
template<typename T>
T *	getPtr (const std::string &name)
	Retrieves the pointer for parameter `name` of type `T` from a list. A null pointer is returned if this parameter doesn't exist or is the wrong type.
template<typename T>
const T *	getPtr (const std::string &name) const
	Retrieves the pointer for parameter `name` of type `T` from a constant list. A null pointer is returned if this parameter doesn't exist or is the wrong type.
ParameterEntry &	getEntry (const std::string &name)
	Retrieves an entry with the name `name`.
const ParameterEntry &	getEntry (const std::string &name) const
	Retrieves a const entry with the name `name`.
ParameterEntry *	getEntryPtr (const std::string &name)
	Retrieves the pointer for an entry with the name `name` if it exists.
const ParameterEntry *	getEntryPtr (const std::string &name) const
	Retrieves the pointer for a constant entry with the name `name` if it exists.
Parameter removal functions
bool	remove (std::string const &name, bool throwIfNotExists=true)
	Remove a parameter (does not depend on the type of the parameter).
Sublist Functions
ParameterList &	sublist (const std::string &name, bool mustAlreadyExist=false, const std::string &docString="")
	Creates an empty sublist and returns a reference to the sublist `name`. If the list already exists, returns reference to that sublist. If the name exists but is not a sublist, an std::exception is thrown.
const ParameterList &	sublist (const std::string &name) const
	Return a const reference to an existing sublist `name`. If the list does not already exist or the name exists but is not a sublist, an std::exception is thrown.
Attribute Functions
const std::string &	name () const
	Query the name of this parameter list.
bool	isParameter (const std::string &name) const
	Query the existence of a parameter.
bool	isSublist (const std::string &name) const
	Query the existence of a parameter and whether it is a parameter list.
template<typename T>
bool	isType (const std::string &name) const
	Query the existence and type of a parameter.
I/O Functions
std::ostream &	print (std::ostream &os, const PrintOptions &printOptions) const
	Printing method for parameter lists which takes an print options object.
std::ostream &	print (std::ostream &os, int indent=0, bool showTypes=false, bool showFlags=true) const
	Printing method for parameter lists. Indenting is used to indicate parameter list hierarchies.
void	unused (std::ostream &os) const
	Print out unused parameters in the ParameterList.
std::string	currentParametersString () const
	Create a single formated std::string of all of the zero-level parameters in this list.
Read-only access to the iterator
ConstIterator	begin () const
	An iterator pointing to the first entry.
ConstIterator	end () const
	An iterator pointing beyond the last entry.
const ParameterEntry &	entry (ConstIterator i) const
	Access to ParameterEntry (i.e., returns i->second).
const std::string &	name (ConstIterator i) const
	Access to name (i.e., returns i->first).
Validation Functions
void	validateParameters (ParameterList const &validParamList, int const depth=1000, EValidateUsed const validateUsed=VALIDATE_USED_ENABLED, EValidateDefaults const validateDefaults=VALIDATE_DEFAULTS_ENABLED) const
	Validate the parameters in this list given valid selections in the input list.
void	validateParametersAndSetDefaults (ParameterList const &validParamList, int const depth=1000)
	Validate the parameters in this list given valid selections in the input list and set defaults for those not set.
Related Functions
(Note that these are not member functions.)
enum	EValidateUsed
	More...
enum	EValidateDefaults
	More...
bool	operator== (const ParameterList &list1, const ParameterList &list2)
	Returns true if two parameter lists are the same.
bool	operator!= (const ParameterList &list1, const ParameterList &list2)
	Returns true if two parameter lists are not the same.
bool	haveSameValues (const ParameterList &list1, const ParameterList &list2)
	Returns true if two parameter lists have the same values.
template<typename T>
T &	getParameter (ParameterList &l, const std::string &name)
	A templated helper function for getting a parameter from a non-const list. This helper function prevents the need for giving a nominal value of the specific template type.
template<typename T>
T &	get (ParameterList &l, const std::string &name)
	A shorter name for `getParameter()`.
template<typename T>
const T &	getParameter (const ParameterList &l, const std::string &name)
	A templated helper function for getting a parameter from a const list. This helper function prevents the need for giving a nominal value of the specific template type.
template<typename T>
T *	getParameterPtr (ParameterList &l, const std::string &name)
	A templated helper function for getting a pointer to a parameter from a non-const list, if it exists. This helper function prevents the need for giving a nominal value of the specific template type.
template<typename T>
const T *	getParameterPtr (const ParameterList &l, const std::string &name)
	A templated helper function for getting a pointer to a parameter from a non-const list, if it exists. This helper function prevents the need for giving a nominal value of the specific template type.
template<typename T>
bool	isParameterType (ParameterList &l, const std::string &name)
	A templated helper function for determining the type of a parameter entry for a non-const list. This helper function avoids the need for giving a nominal value of the specific template type.
template<typename T>
bool	isParameterType (const ParameterList &l, const std::string &name)
	A templated helper function for determining the type of a parameter entry for a const list. This helper function avoids the need for giving a nominal value of the specific template type.
template<typename T>
void	setStringParameterFromArray (const std::string &paramName, const Array< T > &array, ParameterList *paramList)
	Set a std::string parameter representation of an array.
template<typename T>
Array< T >	getArrayFromStringParameter (const ParameterList &paramList, const std::string &paramName, const int arrayDim=-1, const bool mustExist=true)
	Get an Array object (with entries of type `T`) from a parameter holding a std::string representation of the array.
RCP< ParameterList >	sublist (const RCP< ParameterList > &paramList, const std::string &name, bool mustAlreadyExist=false)
	Return a RCP to a sublist in another RCP-ed parameter list.
RCP< const ParameterList >	sublist (const RCP< const ParameterList > &paramList, const std::string &name)
	Return a RCP to a sublist in another RCP-ed parameter list.
std::ostream &	operator<< (std::ostream &os, const ParameterList &l)
	Output stream operator for handling the printing of the parameter list.
template<class IntegralType>
void	setStringToIntegralParameter (std::string const &paramName, std::string const &defaultValue, std::string const &docString, ArrayView< const std::string > const &strings, ParameterList *paramList)
	Set up a std::string parameter that will use an embedded validator to allow the extraction of an integral value.
template<class IntegralType>
void	setStringToIntegralParameter (std::string const &paramName, std::string const &defaultValue, std::string const &docString, ArrayView< const std::string > const &strings, ArrayView< const IntegralType > const &integralValues, ParameterList *paramList)
	Set up a std::string parameter that will use an embedded validator to allow the extraction of an integral value from a list of integral values.
template<class IntegralType>
void	setStringToIntegralParameter (std::string const &paramName, std::string const &defaultValue, std::string const &docString, ArrayView< const std::string > const &strings, ArrayView< const std::string > const &stringsDocs, ArrayView< const IntegralType > const &integralValues, ParameterList *paramList)
	Set up a std::string parameter with documentation strings for each valid value that will use an embedded validator to allow the extraction of an integral value from a list of integral values.
template<class IntegralType>
IntegralType	getIntegralValue (ParameterList const &paramList, std::string const &paramName)
	Get an integral value for a parameter that is assumed to already be set.
template<class IntegralType>
std::string	getStringValue (ParameterList const &paramList, std::string const &paramName)
	Get a std::string value for a parameter that is assumed to already be set.
void	setIntParameter (std::string const &paramName, int const value, std::string const &docString, ParameterList *paramList, AnyNumberParameterEntryValidator::AcceptedTypes const &acceptedTypes=AnyNumberParameterEntryValidator::AcceptedTypes())
	Set an integer parameter that allows for (nearly) any input parameter type that is convertible to an int.
void	setDoubleParameter (std::string const &paramName, double const &value, std::string const &docString, ParameterList *paramList, AnyNumberParameterEntryValidator::AcceptedTypes const &acceptedTypes=AnyNumberParameterEntryValidator::AcceptedTypes())
	Set an double parameter that allows for (nearly) any input parameter type that is convertible to a double.
void	setNumericStringParameter (std::string const &paramName, std::string const &value, std::string const &docString, ParameterList *paramList, AnyNumberParameterEntryValidator::AcceptedTypes const &acceptedTypes=AnyNumberParameterEntryValidator::AcceptedTypes())
	Set an numeric parameter preferred as a std::string that allows for (nearly) any input parameter type that is convertible to a std::string.
int	getIntParameter (ParameterList const &paramList, std::string const &paramName)
	Get an integer parameter.
double	getDoubleParameter (ParameterList const &paramList, std::string const &paramName)
	Get double integer parameter.
std::string	getNumericStringParameter (ParameterList const &paramList, std::string const &paramName)
	Get std::string numeric parameter.
Classes
class	PrintOptions
	Utility class for setting and passing in print options. More...

Detailed Description

Parameters can be added and retreived with the templated "get" and "set" functions. These parameters can any data type which uses value sementics (e.g. double, float, int, *double, *float, *int, ...) which includes other parameter lists, allowing for a hierarchy of parameter lists. These parameters can also be pointers to vectors or functions.

Member Typedef Documentation

typedef Map::const_iterator Teuchos::ParameterList::ConstIterator

Parameter container const iterator typedef.

Constructor & Destructor Documentation

Teuchos::ParameterList::ParameterList ( )

Constructor.

Teuchos::ParameterList::ParameterList ( const std::string & name )

Constructor.

Teuchos::ParameterList::ParameterList ( const ParameterList & source )

Copy Constructor.

Teuchos::ParameterList::~ParameterList ( ) [virtual]

Deconstructor.

Member Function Documentation

ParameterList & Teuchos::ParameterList::setName ( const std::string & name ) [inline]

Set the name of *this list.

ParameterList & Teuchos::ParameterList::operator= ( const ParameterList & source )

Replace the current parameter list with source.

Note:: This also replaces the name returned by this->name()

ParameterList & Teuchos::ParameterList::setParameters ( const ParameterList & source )

Set the parameters in source.

Note, this function will set the parameters and sublists from source into *this but will not result in parameters being removed from *this. Parameters in *this with the same names as those in source will be overwritten.

ParameterList & Teuchos::ParameterList::setParametersNotAlreadySet ( const ParameterList & source )

Set the parameters in source that are not already set in *this.

Note, this function will set the parameters and sublists from source into *this but will not result in parameters being removed from *this or in parameters already set in *this being overrided. Parameters in *this with the same names as those in source will not be overwritten.

ParameterList & Teuchos::ParameterList::disableRecursiveValidation ( )

Disallow recusive validation when this sublist is used in a valid parameter list.

This function should be called when setting a sublist in a valid parameter list which is broken off to be passed to another object. The other object should validate its own list.

template<typename T>

ParameterList & Teuchos::ParameterList::set	(	std::string const &	name,
		T const &	value,
		std::string const &	docString = `""`,
		RCP< const ParameterEntryValidator > const &	validator = `null`
	)			`[inline]`

Sets different types of parameters. The type depends on the second entry.

Note:

Use static_cast<T>() when the type is ambiguous.
Both char* and std::string std::map to are stored as strings internally.
Sets the parameter as "unused".

Examples:: ParameterList/cxx_main.cpp.

ParameterList & Teuchos::ParameterList::set	(	std::string const &	name,
		char	value[],
		std::string const &	docString = `""`,
		RCP< const ParameterEntryValidator > const &	validator = `null`
	)			`[inline]`

Template specialization for the case when a user sets the parameter with a character std::string in parenthesis.

ParameterList& Teuchos::ParameterList::set	(	std::string const &	name,
		const char	value[],
		std::string const &	docString = `""`,
		RCP< const ParameterEntryValidator > const &	validator = `null`
	)

Template specialization for the case when a user sets the parameter with a character std::string in parenthesis.

ParameterList & Teuchos::ParameterList::set	(	std::string const &	name,
		ParameterList const &	value,
		std::string const &	docString = `""`
	)			`[inline]`

Template specialization for the case when a user sets the parameter with a ParameterList.

ParameterList & Teuchos::ParameterList::setEntry	(	const std::string &	name,
		const ParameterEntry &	entry
	)			`[inline]`

Set a parameter directly as a ParameterEntry.

Note:: This is required to preserve the isDefault value when reading back from XML. KL 7 August 2004

template<typename T>

T & Teuchos::ParameterList::get	(	const std::string &	name,
		T	def_value
	)

Retrieves parameter name of type T from list, if it exists, else the def_value is used to enter a new parameter into the list.

Note:

Use the static_cast<T>() when the type is ambiguous.
Both char* and std::string std::map to are stored as strings internally.
Sets the parameter as "used".
Exception is thrown if name exists, but is not of type T.

Examples:: ParameterList/cxx_main.cpp.

std::string & Teuchos::ParameterList::get	(	const std::string &	name,
		char	def_value[]
	)			`[inline]`

Template specialization of get, where the nominal value is a character std::string in parenthesis. Both char* and std::string are stored as strings and return std::string values.

std::string& Teuchos::ParameterList::get	(	const std::string &	name,
		const char	def_value[]
	)

Template specialization of get, where the nominal value is a character std::string in parenthesis. Both char* and std::string are stored as strings and return std::string values.

template<typename T>

T & Teuchos::ParameterList::get ( const std::string & name )

Retrieves parameter name of type T from a list, an Exceptions::InvalidParameter std::exception is thrown if this parameter doesn't exist (Exceptions::InvalidParameterName) or is the wrong type (Exceptions::InvalidParameterName).

Note:: The syntax for calling this method is: list.template get<int>( "Iters" )

template<typename T>

const T & Teuchos::ParameterList::get ( const std::string & name ) const

Retrieves parameter name of type T from a constant list, an Exceptions::InvalidParameter std::exception is thrown if this parameter doesn't exist (Exceptions::InvalidParameterName) or is the wrong type (Exceptions::InvalidParameterName).

Note:: The syntax for calling this method is: list.template get<int>( "Iters" )

template<typename T>

T * Teuchos::ParameterList::getPtr ( const std::string & name ) [inline]

Retrieves the pointer for parameter name of type T from a list. A null pointer is returned if this parameter doesn't exist or is the wrong type.

Note:: The syntax for calling this method is: list.template getPtr<int>( "Iters" )

template<typename T>

const T * Teuchos::ParameterList::getPtr ( const std::string & name ) const [inline]

Retrieves the pointer for parameter name of type T from a constant list. A null pointer is returned if this parameter doesn't exist or is the wrong type.

Note:: The syntax for calling this method is: list.template getPtr<int>( "Iters" )

ParameterEntry & Teuchos::ParameterList::getEntry ( const std::string & name ) [inline]

Retrieves an entry with the name name.

Throws Exceptions::InvalidParameterName if this parameter does not exist.

const ParameterEntry & Teuchos::ParameterList::getEntry ( const std::string & name ) const [inline]

Retrieves a const entry with the name name.

Throws Exceptions::InvalidParameterName if this parameter does not exist.

ParameterEntry * Teuchos::ParameterList::getEntryPtr ( const std::string & name ) [inline]

Retrieves the pointer for an entry with the name name if it exists.

const ParameterEntry * Teuchos::ParameterList::getEntryPtr ( const std::string & name ) const [inline]

Retrieves the pointer for a constant entry with the name name if it exists.

bool Teuchos::ParameterList::remove	(	std::string const &	name,
		bool	throwIfNotExists = `true`
	)

Remove a parameter (does not depend on the type of the parameter).

Parameters:

	name	[in] The name of the parameter to remove
	throwIfNotExists	[in] If `true` then if the parameter with the name `name` does not exist then a std::exception will be thrown!

Returns:: Returns true if the parameter was removed, and false if the parameter was not removed (false return value possible only if throwIfExists==false).

ParameterList & Teuchos::ParameterList::sublist	(	const std::string &	name,
		bool	mustAlreadyExist = `false`,
		const std::string &	docString = `""`
	)

Creates an empty sublist and returns a reference to the sublist name. If the list already exists, returns reference to that sublist. If the name exists but is not a sublist, an std::exception is thrown.

Examples:: ParameterList/cxx_main.cpp.

const ParameterList & Teuchos::ParameterList::sublist ( const std::string & name ) const

Return a const reference to an existing sublist name. If the list does not already exist or the name exists but is not a sublist, an std::exception is thrown.

const std::string & Teuchos::ParameterList::name ( ) const [inline]

Query the name of this parameter list.

bool Teuchos::ParameterList::isParameter ( const std::string & name ) const

Query the existence of a parameter.

Returns:: "true" if a parameter with this name exists, else "false". Warning, this function should almost never be used! Instead, consider using getEntryPtr() instead.

Examples:: ParameterList/cxx_main.cpp.

bool Teuchos::ParameterList::isSublist ( const std::string & name ) const

Query the existence of a parameter and whether it is a parameter list.

Returns:: "true" if a parameter with this name exists and is itself a parameter list, else "false". Warning, this function should almost never be used! Instead, consider using getEntryPtr() instead.

Examples:: ParameterList/cxx_main.cpp.

template<typename T>

bool Teuchos::ParameterList::isType ( const std::string & name ) const

Query the existence and type of a parameter.

Returns:: "true" is a parameter with this name exists and is of type T, else "false".

Note:: The syntax for calling this method is: list.template isType<int>( "Iters" ) . Warning, this function should almost never be used! Instead, consider using getEntryPtr() instead.

std::ostream & Teuchos::ParameterList::print	(	std::ostream &	os,
		const PrintOptions &	printOptions
	)			const

Printing method for parameter lists which takes an print options object.

std::ostream & Teuchos::ParameterList::print	(	std::ostream &	os,
		int	indent = `0`,
		bool	showTypes = `false`,
		bool	showFlags = `true`
	)			const

Printing method for parameter lists. Indenting is used to indicate parameter list hierarchies.

void Teuchos::ParameterList::unused ( std::ostream & os ) const

Print out unused parameters in the ParameterList.

std::string Teuchos::ParameterList::currentParametersString ( ) const

Create a single formated std::string of all of the zero-level parameters in this list.

ParameterList::ConstIterator Teuchos::ParameterList::begin ( ) const

An iterator pointing to the first entry.

ParameterList::ConstIterator Teuchos::ParameterList::end ( ) const

An iterator pointing beyond the last entry.

const ParameterEntry & Teuchos::ParameterList::entry ( ConstIterator i ) const

Access to ParameterEntry (i.e., returns i->second).

const std::string & Teuchos::ParameterList::name ( ConstIterator i ) const

Access to name (i.e., returns i->first).

void Teuchos::ParameterList::validateParameters	(	ParameterList const &	validParamList,
		int const	depth = `1000`,
		EValidateUsed const	validateUsed = `VALIDATE_USED_ENABLED`,
		EValidateDefaults const	validateDefaults = `VALIDATE_DEFAULTS_ENABLED`
	)			const

Validate the parameters in this list given valid selections in the input list.

Parameters:

	validParamList	[in] This is the list that the parameters and sublist in `*this` are compared against.
	depth	[in] Determines the number of levels of depth that the validation will recurse into. A value of `dpeth=0` means that only the top level parameters and sublists will be checked. Default: `depth = large number`.
	validateUsed	[in] Determines if parameters that have been used are checked against those in `validParamList`. Default: `validateDefaults = VALIDATE_DEFAULTS_ENABLED`.
	validateDefaults	[in] Determines if parameters set at their default values using `get(name,defaultVal)` are checked against those in `validParamList`. Default: `validateDefaults = VALIDATE_DEFAULTS_ENABLED`.

If a parameter in *this is not found in validParamList then an std::exception of type Exceptions::InvalidParameterName will be thrown which will contain an excellent error message returned by excpt.what(). If the parameter exists but has the wrong type, then an std::exception type Exceptions::InvalidParameterType will be thrown. If the parameter exists and has the right type, but the value is not valid then an std::exception type Exceptions::InvalidParameterValue will be thrown.

Recursive validation stops when:

The maxinum depth is reached
A sublist note in validParamList has been marked with the disableRecursiveValidation() function, or
There are not more parameters or sublists left in *this

A breath-first search is performed to validate all of the parameters in one sublist before moving into nested subslist.

void Teuchos::ParameterList::validateParametersAndSetDefaults	(	ParameterList const &	validParamList,
		int const	depth = `1000`
	)

Validate the parameters in this list given valid selections in the input list and set defaults for those not set.

Parameters:

	validParamList	[in] This is the list that the parameters and sublist in `*this` are compared against.
	depth	[in] Determines the number of levels of depth that the validation will recurse into. A value of `dpeth=0` means that only the top level parameters and sublists will be checked. Default: `depth = large number`.

If a parameter in *this is not found in validParamList then an std::exception of type Exceptions::InvalidParameterName will be thrown which will contain an excellent error message returned by excpt.what(). If the parameter exists but has the wrong type, then an std::exception type Exceptions::InvalidParameterType will be thrown. If the parameter exists and has the right type, but the value is not valid then an std::exception type Exceptions::InvalidParameterValue will be thrown. If a parameter in validParamList does not exist in *this, then it will be set at its default value as determined by validParamList.

Recursive validation stops when:

The maxinum depth is reached
A sublist note in validParamList has been marked with the disableRecursiveValidation() function, or
There are not more parameters or sublists left in *this

A breath-first search is performed to validate all of the parameters in one sublist before moving into nested subslist.

Friends And Related Function Documentation

enum EValidateUsed [related]

enum EValidateDefaults [related]

bool operator==	(	const ParameterList &	list1,
		const ParameterList &	list2
	)			`[related]`

Returns true if two parameter lists are the same.

bool operator!=	(	const ParameterList &	list1,
		const ParameterList &	list2
	)			`[related]`

Returns true if two parameter lists are not the same.

bool haveSameValues	(	const ParameterList &	list1,
		const ParameterList &	list2
	)			`[related]`

Returns true if two parameter lists have the same values.

Two parameter lists may have the same values but may not be identical. For example, two parameters can have the same values but not have the same documentation strings or the same validators.

template<typename T>

T & getParameter	(	ParameterList &	l,
		const std::string &	name
	)			`[related]`

A templated helper function for getting a parameter from a non-const list. This helper function prevents the need for giving a nominal value of the specific template type.

Note:: The syntax for calling this function is: getParameter<int>( list, "Iters" )

template<typename T>

T & get	(	ParameterList &	l,
		const std::string &	name
	)			`[related]`

A shorter name for getParameter().

Note:: The syntax for calling this function is: get<int>( list, "Iters" )

template<typename T>

const T & getParameter	(	const ParameterList &	l,
		const std::string &	name
	)			`[related]`

A templated helper function for getting a parameter from a const list. This helper function prevents the need for giving a nominal value of the specific template type.

Note:: The syntax for calling this function is: getParameter<int>( list, "Iters" )

template<typename T>

T * getParameterPtr	(	ParameterList &	l,
		const std::string &	name
	)			`[related]`

A templated helper function for getting a pointer to a parameter from a non-const list, if it exists. This helper function prevents the need for giving a nominal value of the specific template type.

Note:: The syntax for calling this function is: getParameterPtr<int>(list,"Iters")

template<typename T>

const T * getParameterPtr	(	const ParameterList &	l,
		const std::string &	name
	)			`[related]`

A templated helper function for getting a pointer to a parameter from a non-const list, if it exists. This helper function prevents the need for giving a nominal value of the specific template type.

Note:: The syntax for calling this function is: getParameterPtr<int>(list,"Iters")

template<typename T>

bool isParameterType	(	ParameterList &	l,
		const std::string &	name
	)			`[related]`

A templated helper function for determining the type of a parameter entry for a non-const list. This helper function avoids the need for giving a nominal value of the specific template type.

Note:: The syntax for calling this function is: isParameterType<int>( list, "Iters" )

template<typename T>

bool isParameterType	(	const ParameterList &	l,
		const std::string &	name
	)			`[related]`

A templated helper function for determining the type of a parameter entry for a const list. This helper function avoids the need for giving a nominal value of the specific template type.

Note:: The syntax for calling this function is: isParameterType<int>( list, "Iters" )

template<typename T>

void setStringParameterFromArray	(	const std::string &	paramName,
		const Array< T > &	array,
		ParameterList *	paramList
	)			`[related]`

Set a std::string parameter representation of an array.

Parameters:

	paramName	[in] The name of the parameter containing the std::string representation of the array.
	array	[in] The array that will be set as a std::string parameter.
	paramList	[in/out] The parameter list that the array will be set on.

template<typename T>

Array< T > getArrayFromStringParameter	(	const ParameterList &	paramList,
		const std::string &	paramName,
		const int	arrayDim = `-1`,
		const bool	mustExist = `true`
	)			`[related]`

Get an Array object (with entries of type T) from a parameter holding a std::string representation of the array.

Parameters:

	paramList	[in] The parameter list to extract the parameter array from.
	paramName	[in] The name of the parameter containing the std::string representation of the array.
	arrayDim	[in] If `arrayDim >= 0`, then the read in array must be equal to this dimension, or an std::exception will be thrown. If `arrayDim < 0`, then an array of any dimension will be returned. The default is `-1` and therefore no array length validation will be performed.
	mustExist	[in] If `mustExist==true`, then the parameter `paramName` must exist and must contain a valid array, or an std::exception is thrown. If `mustExist==false`, and if the parameter `paramName` does not exist or contains an empty array std::string value, then an empty array object will be returned.

Returns:: an array object if an std::exception is not thrown. If mustExist==false and the parameter does not exist, then an empty array object will be returned. If mustExist==true and arrayDim < 0, then if the parameter paramName exists and its array value is valid, then the converted array, of any size, will be returned. If mustExist==true and arrayDim >= 0 then an array of dimension arrayDim will be returned if an std::exception is not thrown.

Exceptions:

Exceptions::InvalidParameterName will be thrown if mustExist==true and the parameter paramName does not exist in paramList
Exceptions::InvalidParameterType will be thrown if the parameter exists but does not have a value type of std::string.
Exceptions::InvalidParameterValue will be thrown in the following cases:
- If the parameter paramName exists but the array in std::string form is not formated correctly.
- If arrayDim >= 0 and the read in array dimension dies not equal arrayDim

Detailed Description:

This function allows Array<T> objects to be read in from a parameter with a std::string representation of the array. The templated function Teuchos::fromStringToArray() (see documentation for Teuchos::Array) is used to parse the std::string representation and return the array object (see this function's documentation for details on what the formatting of the array std::string must be and what can be handled and what can not be handled.

RCP< ParameterList > sublist	(	const RCP< ParameterList > &	paramList,
		const std::string &	name,
		bool	mustAlreadyExist = `false`
	)			`[related]`

RCP< const ParameterList > sublist	(	const RCP< const ParameterList > &	paramList,
		const std::string &	name
	)			`[related]`

std::ostream & operator<<	(	std::ostream &	os,
		const ParameterList &	l
	)			`[related]`

void setStringToIntegralParameter	(	std::string const &	paramName,
		std::string const &	defaultValue,
		std::string const &	docString,
		ArrayView< const std::string > const &	strings,
		ParameterList *	paramList
	)			`[related]`

IntegralType getIntegralValue	(	ParameterList const &	paramList,
		std::string const &	paramName
	)			`[related]`

std::string getStringValue	(	ParameterList const &	paramList,
		std::string const &	paramName
	)			`[related]`

void setIntParameter	(	std::string const &	paramName,
		int const	value,
		std::string const &	docString,
		ParameterList *	paramList,
		AnyNumberParameterEntryValidator::AcceptedTypes const &	acceptedTypes = `AnyNumberParameterEntryValidator::AcceptedTypes()`
	)			`[related]`

void setDoubleParameter	(	std::string const &	paramName,
		double const &	value,
		std::string const &	docString,
		ParameterList *	paramList,
		AnyNumberParameterEntryValidator::AcceptedTypes const &	acceptedTypes = `AnyNumberParameterEntryValidator::AcceptedTypes()`
	)			`[related]`

void setNumericStringParameter	(	std::string const &	paramName,
		std::string const &	value,
		std::string const &	docString,
		ParameterList *	paramList,
		AnyNumberParameterEntryValidator::AcceptedTypes const &	acceptedTypes = `AnyNumberParameterEntryValidator::AcceptedTypes()`
	)			`[related]`

int getIntParameter	(	ParameterList const &	paramList,
		std::string const &	paramName
	)			`[related]`

double getDoubleParameter	(	ParameterList const &	paramList,
		std::string const &	paramName
	)			`[related]`

std::string getNumericStringParameter	(	ParameterList const &	paramList,
		std::string const &	paramName
	)			`[related]`

Teuchos::ParameterList Class Reference

Public Types

Public Member Functions

Related Functions

Classes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation