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.
ParameterListoperator= (const ParameterList &source)
ParameterListsetParameters (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.
ParameterEntrygetEntryPtr (const string &name)
 Retrieves the pointer for an entry with the name name if it exists.
const ParameterEntrygetEntryPtr (const string &name) const
 Retrieves the pointer for a constant entry with the name name if it exists.
Sublist Functions
ParameterListsublist (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 ParameterListsublist (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 ParameterEntryentry (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< ParameterListsublist (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:
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,
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,
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 doxygen 1.3.9.1