Teuchos::ParameterList Class Reference

Templated parameter list. More...

#include <Teuchos_ParameterList.hpp>

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

void setName (const std::string &name)

Set the name of *this list.

ParameterList & operator= (const ParameterList &source)

ParameterList & setParameters (const ParameterList &source)

template<typename T>

void set (const string &name, T value)

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

void set (const string &name, char value[])

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

void set (const string &name, const char value[])

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

void set (const string &name, ParameterList value)

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

void setEntry (const string &name, const ParameterEntry &entry)

Set a parameter directly as a ParameterEntry.

Get Functions

template<typename T>

T & get (const 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 string &name, char def_value[])

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

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

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

template<typename T>

T & get (const string &name)

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

template<typename T>

const T & get (const string &name) const

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

template<typename T>

T * getPtr (const 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 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 * getEntryPtr (const string &name)

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

const ParameterEntry * getEntryPtr (const string &name) const

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

Sublist Functions

ParameterList & sublist (const string &name, bool mustAlreadyExist=false)

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 exception is thrown.

const ParameterList & sublist (const 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 exception is thrown.

Attribute Functions

const std::string & name () const

Query the name of this parameter list.

bool isParameter (const string &name) const

Query the existence of a parameter.

bool isSublist (const string &name) const

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

template<typename T>

bool isType (const string &name) const

Query the existence and type of a parameter.

I/O Functions

ostream & print (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 (ostream &os) const

Print out unused parameters in the ParameterList.

std::string currentParametersString () const

Create a single formated 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 string & name (ConstIterator i) const

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

Validation Functions

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

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

Related Functions

(Note that these are not member functions.)

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.

template<typename T>

T & getParameter (ParameterList &l, const 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>

const T & getParameter (const ParameterList &l, const 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>

bool isParameterType (ParameterList &l, const 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 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.

RefCountPtr< ParameterList > sublist (const RefCountPtr< ParameterList > &paramList, const string &name, bool mustAlreadyExist=false)

Return a RCP to a sublist in another RCP-ed parameter list.

ostream & operator<< (ostream &os, const ParameterList &l)

Output stream operator for handling the printing of the parameter list.

Detailed Description

Templated parameter list.

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.

Note:

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

Examples:: ParameterList/cxx_main.cpp.

Definition at line 96 of file Teuchos_ParameterList.hpp.

Member Typedef Documentation

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

Parameter container const iterator typedef.

Definition at line 110 of file Teuchos_ParameterList.hpp.

Constructor & Destructor Documentation

Teuchos::ParameterList::ParameterList ( )

Constructor.

Definition at line 65 of file Teuchos_ParameterList.cpp.

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

Constructor.

Definition at line 69 of file Teuchos_ParameterList.cpp.

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

Copy Constructor.

Definition at line 73 of file Teuchos_ParameterList.cpp.

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

Deconstructor.

Definition at line 104 of file Teuchos_ParameterList.cpp.

Member Function Documentation

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

Set the name of *this list.

Definition at line 429 of file Teuchos_ParameterList.hpp.

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

Replace the current parameter list with source.
Note:
This also replaces the name returned by this->name()

Definition at line 79 of file Teuchos_ParameterList.cpp.

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.
Definition at line 88 of file Teuchos_ParameterList.cpp.

template<typename T>

void Teuchos::ParameterList::set ( const string & name,

T value

) [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 string map to are stored as strings internally.

Sets the parameter as "unused".

Examples:
ParameterList/cxx_main.cpp.

Definition at line 438 of file Teuchos_ParameterList.hpp.

void Teuchos::ParameterList::set ( const string & name,

char value[]

) [inline]

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

Definition at line 444 of file Teuchos_ParameterList.hpp.

void Teuchos::ParameterList::set ( const string & name,

const char value[]

)

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

void Teuchos::ParameterList::set ( const string & name,

ParameterList value

) [inline]

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

Definition at line 452 of file Teuchos_ParameterList.hpp.

void Teuchos::ParameterList::setEntry ( const 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

Definition at line 456 of file Teuchos_ParameterList.hpp.

template<typename T>

T & Teuchos::ParameterList::get ( const 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 string 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.

Definition at line 462 of file Teuchos_ParameterList.hpp.

std::string & Teuchos::ParameterList::get ( const string & name,

char def_value[]

) [inline]

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

Definition at line 480 of file Teuchos_ParameterList.hpp.

std::string& Teuchos::ParameterList::get ( const string & name,

const char def_value[]

)

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

template<typename T>

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

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

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

Definition at line 488 of file Teuchos_ParameterList.hpp.

template<typename T>

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

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

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

Definition at line 497 of file Teuchos_ParameterList.hpp.

template<typename T>

T * Teuchos::ParameterList::getPtr ( const 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" )

Definition at line 507 of file Teuchos_ParameterList.hpp.

template<typename T>

const T * Teuchos::ParameterList::getPtr ( const 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" )

Definition at line 517 of file Teuchos_ParameterList.hpp.

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

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

Definition at line 527 of file Teuchos_ParameterList.hpp.

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

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

Definition at line 537 of file Teuchos_ParameterList.hpp.

ParameterList & Teuchos::ParameterList::sublist ( const string & name,

bool mustAlreadyExist = false

)

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 exception is thrown.

Examples:
ParameterList/cxx_main.cpp.

Definition at line 150 of file Teuchos_ParameterList.cpp.

const ParameterList & Teuchos::ParameterList::sublist ( const 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 exception is thrown.

Definition at line 181 of file Teuchos_ParameterList.cpp.

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

Query the name of this parameter list.

Definition at line 548 of file Teuchos_ParameterList.hpp.

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

Query the existence of a parameter.

Returns:
"true" if a parameter with this name exists, else "false".

Examples:
ParameterList/cxx_main.cpp.

Definition at line 145 of file Teuchos_ParameterList.cpp.

bool Teuchos::ParameterList::isSublist ( const 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".

Examples:
ParameterList/cxx_main.cpp.

Definition at line 135 of file Teuchos_ParameterList.cpp.

template<typename T>

bool Teuchos::ParameterList::isType ( const 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" )

Definition at line 566 of file Teuchos_ParameterList.hpp.

ostream & Teuchos::ParameterList::print ( 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.

Definition at line 198 of file Teuchos_ParameterList.cpp.

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

Print out unused parameters in the ParameterList.

Examples:
ParameterList/cxx_main.cpp.

Definition at line 107 of file Teuchos_ParameterList.cpp.

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

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

Definition at line 117 of file Teuchos_ParameterList.cpp.

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

An iterator pointing to the first entry.

Definition at line 234 of file Teuchos_ParameterList.cpp.

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

An iterator pointing beyond the last entry.

Definition at line 239 of file Teuchos_ParameterList.cpp.

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

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

Definition at line 275 of file Teuchos_ParameterList.cpp.

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

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

Definition at line 265 of file Teuchos_ParameterList.cpp.

void Teuchos::ParameterList::validateParameters ( const ParameterList & validParamList,

const int depth = 1000,

const EValidateUsed validateUsed = VALIDATE_USED_ENABLED,

const EValidateDefaults validateDefaults = VALIDATE_DEFAULTS_ENABLED

) const

Validate the parameters is 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 exception of type Exceptions::InvalidParameter will be thrown which will contain an excellent error message returned by excpt.what().
A breath-first search is performed to validate all of the parameters in one sublist before moving into nested subslist.
Definition at line 282 of file Teuchos_ParameterList.cpp.

Friends And Related Function Documentation

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.

Definition at line 420 of file Teuchos_ParameterList.hpp.

template<typename T>

T & getParameter ( ParameterList & l,

const 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" )

Definition at line 608 of file Teuchos_ParameterList.hpp.

template<typename T>

const T & getParameter ( const ParameterList & l,

const 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" )

Definition at line 620 of file Teuchos_ParameterList.hpp.

template<typename T>

bool isParameterType ( ParameterList & l,

const 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" )

Definition at line 632 of file Teuchos_ParameterList.hpp.

template<typename T>

bool isParameterType ( const ParameterList & l,

const 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" )

Definition at line 644 of file Teuchos_ParameterList.hpp.

RefCountPtr< ParameterList > sublist ( const RefCountPtr< ParameterList > & paramList,

const string & name,

bool mustAlreadyExist = false

) [related]

Return a RCP to a sublist in another RCP-ed parameter list.

Definition at line 653 of file Teuchos_ParameterList.hpp.

ostream & operator<< ( ostream & os,

const ParameterList & l

) [related]

Output stream operator for handling the printing of the parameter list.

Definition at line 666 of file Teuchos_ParameterList.hpp.

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

Generated on Thu Sep 18 12:30:32 2008 for Teuchos - Trilinos Tools Package by

1.3.9.1


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
void	setName (const std::string &name)
	Set the name of `*this` list.
ParameterList &	operator= (const ParameterList &source)
ParameterList &	setParameters (const ParameterList &source)
template<typename T>
void	set (const string &name, T value)
	Sets different types of parameters. The type depends on the second entry.
void	set (const string &name, char value[])
	Template specialization for the case when a user sets the parameter with a character string in parenthesis.
void	set (const string &name, const char value[])
	Template specialization for the case when a user sets the parameter with a character string in parenthesis.
void	set (const string &name, ParameterList value)
	Template specialization for the case when a user sets the parameter with a ParameterList.
void	setEntry (const string &name, const ParameterEntry &entry)
	Set a parameter directly as a ParameterEntry.
Get Functions
template<typename T>
T &	get (const 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 string &name, char def_value[])
	Template specialization of get, where the nominal value is a character string in parenthesis. Both char* and string are stored as strings and return string values.
std::string &	get (const string &name, const char def_value[])
	Template specialization of get, where the nominal value is a character string in parenthesis. Both char* and string are stored as strings and return string values.
template<typename T>
T &	get (const string &name)
	Retrieves parameter `name` of type `T` from a list, an `Exceptions::InvalidParameter` exception is thrown if this parameter doesn't exist or is the wrong type.
template<typename T>
const T &	get (const string &name) const
	Retrieves parameter `name` of type `T` from a constant list, an `Exceptions::InvalidParameter` exception is thrown if this parameter doesn't exist or is the wrong type.
template<typename T>
T *	getPtr (const 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 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 *	getEntryPtr (const string &name)
	Retrieves the pointer for an entry with the name `name` if it exists.
const ParameterEntry *	getEntryPtr (const string &name) const
	Retrieves the pointer for a constant entry with the name `name` if it exists.
Sublist Functions
ParameterList &	sublist (const string &name, bool mustAlreadyExist=false)
	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 exception is thrown.
const ParameterList &	sublist (const 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 exception is thrown.
Attribute Functions
const std::string &	name () const
	Query the name of this parameter list.
bool	isParameter (const string &name) const
	Query the existence of a parameter.
bool	isSublist (const string &name) const
	Query the existence of a parameter and whether it is a parameter list.
template<typename T>
bool	isType (const string &name) const
	Query the existence and type of a parameter.
I/O Functions
ostream &	print (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 (ostream &os) const
	Print out unused parameters in the ParameterList.
std::string	currentParametersString () const
	Create a single formated 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 string &	name (ConstIterator i) const
	Access to name (i.e., returns i->first).
Validation Functions
void	validateParameters (const ParameterList &validParamList, const int depth=1000, const EValidateUsed validateUsed=VALIDATE_USED_ENABLED, const EValidateDefaults validateDefaults=VALIDATE_DEFAULTS_ENABLED) const
	Validate the parameters is this list given valid selections in the input list.
Related Functions
(Note that these are not member functions.)
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.
template<typename T>
T &	getParameter (ParameterList &l, const 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>
const T &	getParameter (const ParameterList &l, const 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>
bool	isParameterType (ParameterList &l, const 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 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.
RefCountPtr< ParameterList >	sublist (const RefCountPtr< ParameterList > &paramList, const string &name, bool mustAlreadyExist=false)
	Return a RCP to a sublist in another RCP-ed parameter list.
ostream &	operator<< (ostream &os, const ParameterList &l)
	Output stream operator for handling the printing of the parameter list.