Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Private Types | Private Member Functions | Private Attributes | Related Functions | List of all members
Teuchos::ParameterList Class Reference

A list of parameters of arbitrary type. More...

#include <Teuchos_ParameterList.hpp>

Classes

class  PrintOptions
 Utility class for setting and passing in print options. More...
 

Private Types

typedef
StringIndexedOrderedValueObjectContainer
< ParameterEntry
params_t
 Internal data-structure. More...
 
typedef params_t::Iterator Iterator
 Parameter container iterator typedef. More...
 

Private Member Functions

Iterator nonconstBegin ()
 An iterator pointing to the first entry. More...
 
Iterator nonconstEnd ()
 An iterator pointing beyond the last entry. More...
 
ParameterEntrynonconstEntry (Iterator i)
 Access to ParameterEntry (i.e., returns i->second) More...
 
void validateEntryExists (const std::string &funcName, const std::string &name, const ParameterEntry *entry) const
 Validate that a parameter exists. More...
 
template<typename T >
void validateEntryType (const std::string &funcName, const std::string &name, const ParameterEntry &entry) const
 Validate that a type is the same. More...
 
void validateEntryIsList (const std::string &name, const ParameterEntry &entry) const
 Validate a sublist param is indeed a sublist. More...
 
void validateMissingSublistMustExist (const std::string &baselist_name, const std::string &sublist_name, const bool mustAlreadyExist) const
 Throw a sublist does not exist exception. More...
 
void updateSubListNames (int depth=0)
 Update sublist names recursively. More...
 

Private Attributes

std::string name_ = "ANONYMOUS"
 Name of the (sub)list. More...
 
params_t params_
 Parameter list. More...
 
bool disableRecursiveValidation_ = false
 Validate into list or not. More...
 
bool disableRecursiveModification_ = false
 Modify into list or not. More...
 
bool disableRecursiveReconciliation_ = false
 Reconcile into list or not. More...
 
RCP< const ParameterListModifiermodifier_ = null
 

Related Functions

(Note that these are not member functions.)

enum  EValidateUsed { VALIDATE_USED_ENABLED, VALIDATE_USED_DISABLED }
 Validation used enum. More...
 
enum  EValidateDefaults { VALIDATE_DEFAULTS_ENABLED, VALIDATE_DEFAULTS_DISABLED }
 Validation defaults enum. More...
 
RCP< ParameterListparameterList ()
 Nonmember constructor. More...
 
RCP< ParameterListparameterList (const std::string &name)
 Nonmember constructor. More...
 
RCP< ParameterListparameterList (const ParameterList &source)
 Nonmember constructor. More...
 
RCP< ParameterListcreateParameterList ()
 Nonmember constructor. More...
 
RCP< ParameterListcreateParameterList (const std::string &name)
 Nonmember constructor. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
bool 
operator== (const ParameterList &list1, const ParameterList &list2)
 Returns true if two parameter lists are the same. More...
 
bool operator!= (const ParameterList &list1, const ParameterList &list2)
 Returns true if two parameter lists are not the same. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
bool 
haveSameModifiers (const ParameterList &list1, const ParameterList &list2)
 Returns true if two parameter lists have the same modifiers. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
bool 
haveSameValues (const ParameterList &list1, const ParameterList &list2, bool verbose=false)
 Returns true if two parameter lists have the same values. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
bool 
haveSameValuesSorted (const ParameterList &list1, const ParameterList &list2, bool verbose=false)
 Returns true if two parameter lists have the same values independent of ordering. More...
 
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. More...
 
template<typename T >
T & get (ParameterList &l, const std::string &name)
 A shorter name for getParameter(). More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
template<typename T >
void setStringParameterFromArray (const std::string &paramName, const Array< T > &array, ParameterList *paramList)
 Set a std::string parameter representation of an array. More...
 
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. More...
 
template<typename T >
bool replaceParameterWithArray (const std::string &paramName, const std::string &newName, ParameterList &pl)
 Replace a parameter with an array containing the parameter. More...
 
RCP< ParameterListsublist (const RCP< ParameterList > &paramList, const std::string &name, bool mustAlreadyExist=false, const std::string &docString="")
 Return a RCP to a sublist in another RCP-ed parameter list. More...
 
RCP< const ParameterListsublist (const RCP< const ParameterList > &paramList, const std::string &name)
 Return a RCP to a sublist in another RCP-ed parameter list. More...
 
std::ostream & operator<< (std::ostream &os, const ParameterList &l)
 Output stream operator for handling the printing of the parameter list. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
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. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
setLongLongParameter (std::string const &paramName, long long 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. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
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. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
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. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
int 
getIntParameter (ParameterList const &paramList, std::string const &paramName)
 Get an integer parameter. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
long long 
getLongLongParameter (ParameterList const &paramList, std::string const &paramName)
 Get a long long parameter. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
double 
getDoubleParameter (ParameterList const &paramList, std::string const &paramName)
 Get double integer parameter. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
std::string 
getNumericStringParameter (ParameterList const &paramList, std::string const &paramName)
 Get std::string numeric parameter. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
updateParametersFromXmlFile (const std::string &xmlFileName, const Ptr< ParameterList > &paramList)
 Reads XML parameters from a file and updates those already in the given parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
RCP< ParameterList
getParametersFromXmlFile (const std::string &xmlFileName)
 Reads XML parameters from a file and return them in a new parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
RCP< ParameterList
getParametersFromXmlFile (const std::string &xmlFileName, RCP< DependencySheet > depSheet)
 Reads XML parameters from a file and return them in a new parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
updateParametersFromXmlString (const std::string &xmlStr, const Ptr< ParameterList > &paramList, bool overwrite=true)
 Reads XML parameters from a std::string and updates those already in the given parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
RCP< ParameterList
getParametersFromXmlString (const std::string &xmlStr)
 Reads XML parameters from a std::string and return them in a new parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
RCP< ParameterList
getParametersFromXmlString (const std::string &xmlStr, RCP< DependencySheet > depSheet)
 Reads XML parameters from a std::string and return them in a new parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
writeParameterListToXmlOStream (const ParameterList &paramList, std::ostream &xmlOut, RCP< const DependencySheet > depSheet=null)
 Write parameters and sublists in XML format to an std::ostream. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
writeParameterListToXmlFile (const ParameterList &paramList, const std::string &xmlFileName, RCP< const DependencySheet > depSheet=null)
 Write parameters and sublist to an XML file. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
updateParametersFromYamlFile (const std::string &yamlFileName, const Ptr< ParameterList > &paramList)
 Reads Yaml parameters from a file and updates those already in the given parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
RCP< ParameterList
getParametersFromYamlFile (const std::string &yamlFileName)
 Reads Yaml parameters from a file and return them in a new parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
updateParametersFromYamlString (const std::string &yamlStr, const Ptr< ParameterList > &paramList, bool overwrite, const std::string &name="")
 Reads Yaml parameters from a std::string and updates those already in the given parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
RCP< ParameterList
getParametersFromYamlString (const std::string &yamlStr)
 Reads Yaml parameters from a std::string and return them in a new parameter list. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
writeParameterListToYamlOStream (const ParameterList &paramList, std::ostream &yamlOut)
 Write parameters and sublists in Yaml format to an std::ostream. More...
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
void 
writeParameterListToYamlFile (const ParameterList &paramList, const std::string &yamlFileName)
 Write parameters and sublist to an Yaml file. More...
 
TEUCHOSCOMM_LIB_DLL_EXPORT void updateParametersAndBroadcast (const Ptr< ParameterList > &inParamList, const Ptr< ParameterList > &ParamList, const Comm< int > &comm, int root, bool overwrite=true)
 On processor rank = root, broadcast the inParamList to all other processors. Then update the given parameter list with these values. More...
 
TEUCHOSCOMM_LIB_DLL_EXPORT void updateParametersFromXmlFileAndBroadcast (const std::string &xmlFileName, const Ptr< ParameterList > &paramList, const Comm< int > &comm, bool overwrite=true)
 On processor rank = 0, reads XML parameters from a file and broadcasts them to all other processors. Then updates the given parameter list with these values. More...
 
TEUCHOSCOMM_LIB_DLL_EXPORT void updateParametersFromYamlFileAndBroadcast (const std::string &yamlFileName, const Teuchos::Ptr< Teuchos::ParameterList > &paramList, const Teuchos::Comm< int > &comm, bool overwrite=true)
 On processor rank = 0, reads Yaml parameters from a file and broadcasts them to all other processors. Then updates the given parameter list with these values. More...
 

Public types

typedef params_t::ConstIterator ConstIterator
 Parameter container const iterator typedef. More...
 

Constructors/Destructor/Info.

 ParameterList ()=default
 Constructor. More...
 
 ParameterList (const std::string &name, RCP< const ParameterListModifier > const &modifier=null)
 Constructor that names the entire parameter list. More...
 
 ParameterList (const ParameterList &source)
 Copy constructor. More...
 
virtual ~ParameterList ()
 Destructor. More...
 

Set Functions

ParameterListsetName (const std::string &name)
 Set the name of *this list. More...
 
ParameterListoperator= (const ParameterList &source)
 Replace the current parameter list with source. More...
 
void setModifier (RCP< const ParameterListModifier > const &modifier)
 
ParameterListsetParameters (const ParameterList &source)
 
ParameterListsetParametersNotAlreadySet (const ParameterList &source)
 
ParameterListdisableRecursiveValidation ()
 
ParameterListdisableRecursiveModification ()
 
ParameterListdisableRecursiveReconciliation ()
 
ParameterListdisableRecursiveAll ()
 
template<typename T >
ParameterListset (std::string const &name, T &&value, std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
 Templated set method. More...
 
template<typename T , typename S , typename = std::enable_if_t<std::is_convertible_v<S, std::remove_const_t<T>>>>
ParameterListset (std::string const &name, const S &value, std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
 
ParameterListset (std::string const &name, char value[], std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
 Specialization of set() for a parameter which is a char[]. More...
 
ParameterListset (std::string const &name, const char value[], std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
 Specialization of set() for a parameter which is a const char[]. More...
 
ParameterListset (std::string const &name, ParameterList const &value, std::string const &docString="")
 Specialization of set() for a parameter which is itself a ParameterList. More...
 
template<typename U , typename = std::enable_if_t<std::is_same_v<std::decay_t<U>, ParameterEntry>>>
ParameterListsetEntry (const std::string &name, U &&entry)
 Set a parameter directly as a ParameterEntry. More...
 
template<typename T >
void recursivelySetValidator (RCP< const ParameterEntryValidator > const &validator, int const depth=1000)
 Recursively attach a validator to parameters of type T. More...
 

Get Functions

template<typename T >
T & get (const std::string &name, T def_value)
 Return the parameter's value, or the default value if it is not there. More...
 
std::string & get (const std::string &name, char def_value[])
 Specialization of get(), where the nominal value is a character string. Both char* and std::string are stored as strings and return std::string values. More...
 
std::string & get (const std::string &name, const char def_value[])
 Specialization of get(), where the nominal value is a character string. Both char* and std::string are stored as strings and return std::string values. More...
 
template<typename T >
T & get (const std::string &name)
 Get a nonconst reference to the parameter. More...
 
template<typename T >
const T & get (const std::string &name) const
 Get a const reference to the parameter. More...
 
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. More...
 
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. More...
 
ParameterEntrygetEntry (const std::string &name)
 Retrieves an entry with the name name. More...
 
const ParameterEntrygetEntry (const std::string &name) const
 Retrieves a const entry with the name name. More...
 
ParameterEntrygetEntryPtr (const std::string &name)
 Retrieves the pointer for an entry with the name name if it exists. More...
 
const ParameterEntrygetEntryPtr (const std::string &name) const
 Retrieves the pointer for a constant entry with the name name if it exists. More...
 
RCP< ParameterEntrygetEntryRCP (const std::string &name)
 Retrieves the RCP for an entry with the name name if it exists. More...
 
RCP< const ParameterEntrygetEntryRCP (const std::string &name) const
 Retrieves the RCP for a constant entry with the name name if it exists. More...
 
RCP< const ParameterListModifiergetModifier () const
 Return the optional modifier object. More...
 

Parameter removal functions

bool remove (std::string const &name, bool throwIfNotExists=true)
 Remove a parameter (does not depend on the type of the parameter). More...
 

Sublist Functions

ParameterListsublist (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. More...
 
ParameterListsublist (const std::string &name, RCP< const ParameterListModifier > const &modifier, const std::string &docString="")
 Creates an empty sublist with an optional modifier and returns a reference to the sublist name. If a list or parameter with the same name already exists then an std::exception is thrown. More...
 
const ParameterListsublist (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. More...
 

Attribute Functions

const std::string & name () const
 The name of this ParameterList. More...
 
bool isParameter (const std::string &name) const
 Whether the given parameter exists in this list. More...
 
bool isSublist (const std::string &name) const
 Whether the given sublist exists in this list. More...
 
template<typename T >
bool isType (const std::string &name) const
 Whether the given parameter exists in this list and has type T. More...
 
Ordinal numParams () const
 Get the number of stored parameters. More...
 

I/O Functions

void print () const
 Print function to use in debugging in a debugger. More...
 
std::ostream & print (std::ostream &os, const PrintOptions &printOptions) const
 Printing method for parameter lists which takes an print options object. More...
 
std::ostream & print (std::ostream &os, int indent=0, bool showTypes=false, bool showFlags=true, bool showDefault=true) const
 Printing method for parameter lists. Indenting is used to indicate parameter list hierarchies. More...
 
void unused (std::ostream &os) const
 Print out unused parameters in the ParameterList. More...
 
std::string currentParametersString () const
 Create a single formated std::string of all of the zero-level parameters in this list. More...
 

Read-only access to the iterator

ConstIterator begin () const
 An iterator pointing to the first entry. More...
 
ConstIterator end () const
 An iterator pointing beyond the last entry. More...
 
const std::string & name (ConstIterator i) const
 Access to name (i.e., returns i->first) More...
 
const ParameterEntryentry (ConstIterator i) const
 Access to ParameterEntry (i.e., returns i->second) More...
 

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. More...
 
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. More...
 
void modifyParameterList (ParameterList &validParamList, int const depth=1000)
 Modify the valid parameter list prior to validation. More...
 
void reconcileParameterList (ParameterList &validParamList, const bool left_to_right=true)
 Reconcile a parameter list after validation. More...
 

Detailed Description

A list of parameters of arbitrary type.

Summary

A ParameterList is a map from parameter name (a string) to its value. The value may have any type with value semantics (see explanation and examples below). This includes another ParameterList, which allows a ParameterList to encode a hierarchy of parameters. Different entries in the same ParameterList may have values of different types.

Users may add a parameter using one of the get() methods, and retrieve its value (given the parameter's name) using one of the set() methods. If the compiler gets confused when you use one of the templated methods, you might have to help it by specifying the type explicitly, or by casting the input object (using e.g., static_cast). There are also methods for iterating through all the parameters in a list, and for validating parameters using validators that you may define for each parameter.

Value semantics

A type has value semantics when it can be passed around as a value. This means that it has an assignment operator and a copy constructor, and that the latter creates "new objects" (rather than references that modify a single object). Types with value semantics include double, float, int, std::string, and similar types.

Paradoxically, pointers like double* also have value semantics. While the pointer is a reference to an object (e.g., an array of double), the pointer itself is a value (an address in memory). The same holds for Teuchos' reference-counted pointer and array classes (RCP resp. ArrayRCP). While it is valid to store pointers ("raw" or reference-counted) in a ParameterList, be aware that this hinders serialization. For example, a double* could encode a single double or an array of double. The pointer itself does not encode the length of the array. A ParameterList serializer has no way to know what the double* means. ParameterList does not forbid you from storing objects that cannot be correctly serialized, so you have to know whether or not this concerns you.

Definition at line 101 of file Teuchos_ParameterList.hpp.

Member Typedef Documentation

Internal data-structure.

Definition at line 104 of file Teuchos_ParameterList.hpp.

Parameter container iterator typedef.

Definition at line 107 of file Teuchos_ParameterList.hpp.

Parameter container const iterator typedef.

Definition at line 115 of file Teuchos_ParameterList.hpp.

Constructor & Destructor Documentation

Teuchos::ParameterList::ParameterList ( )
default

Constructor.

Teuchos::ParameterList::ParameterList ( const std::string &  name,
RCP< const ParameterListModifier > const &  modifier = null 
)

Constructor that names the entire parameter list.

Definition at line 49 of file Teuchos_ParameterList.cpp.

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

Copy constructor.

Definition at line 55 of file Teuchos_ParameterList.cpp.

Teuchos::ParameterList::~ParameterList ( )
virtual

Destructor.

Definition at line 66 of file Teuchos_ParameterList.cpp.

Member Function Documentation

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

Set the name of *this list.

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

void Teuchos::ParameterList::setModifier ( RCP< const ParameterListModifier > const &  modifier)

Definition at line 90 of file Teuchos_ParameterList.cpp.

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

Set the parameters in source.

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

Definition at line 97 of file Teuchos_ParameterList.cpp.

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.

Definition at line 116 of file Teuchos_ParameterList.cpp.

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.

Definition at line 144 of file Teuchos_ParameterList.cpp.

ParameterList & Teuchos::ParameterList::disableRecursiveModification ( )

Disallow recursive modification when this sublist is used in a modified parameter list.

This function should be called when setting a sublist in a modified parameter list which is broken off to be passed to another object. The other object should modify its own list. The parameter list can still be modified using a direct call to its modify method.

Definition at line 151 of file Teuchos_ParameterList.cpp.

ParameterList & Teuchos::ParameterList::disableRecursiveReconciliation ( )

Disallow recursive reconciliation when this sublist is used in a reconciled parameter list.

This function should be called when setting a sublist in a reconciled parameter list which is broken off to be passed to another object. The other object should reconcile its own list. The parameter list can still be reconciled using a direct call to its reconcile method.

Definition at line 158 of file Teuchos_ParameterList.cpp.

ParameterList & Teuchos::ParameterList::disableRecursiveAll ( )

Disallow all recursive modification, validation, and reconciliation when this sublist is used in a parameter list.

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

Definition at line 165 of file Teuchos_ParameterList.cpp.

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

Templated set method.

Parameters
name[in] The parameter's name.
value[in] The parameter's value. This determines the template parameter T. In most cases, you will not need to specify the type T explicitly; the compiler will infer it from this argument.
docString[in] Documentation string for the parameter.
validator[in] Validator for the parameter. If not specified, it defaults to null, the trivial validator (every value passes validation).
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".

Definition at line 934 of file Teuchos_ParameterList.hpp.

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Note
This fallback is necessary to support legacy use cases that specify the type of the parameter at the call site, and the type is hence not deduced.

Definition at line 967 of file Teuchos_ParameterList.hpp.

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

Specialization of set() for a parameter which is a char[].

This version of set() copies the given character array to an std::string and stores it that way in the ParameterList.

Definition at line 976 of file Teuchos_ParameterList.hpp.

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

Specialization of set() for a parameter which is a const char[].

This version of set() copies the given character array to an std::string and stores it that way in the ParameterList.

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

Specialization of set() for a parameter which is itself a ParameterList.

We call the input ParameterList a sublist of *this.

Definition at line 992 of file Teuchos_ParameterList.hpp.

template<typename U , typename >
ParameterList & Teuchos::ParameterList::setEntry ( const std::string &  name,
U &&  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 1003 of file Teuchos_ParameterList.hpp.

template<typename T >
void Teuchos::ParameterList::recursivelySetValidator ( RCP< const ParameterEntryValidator > const &  validator,
int const  depth = 1000 
)

Recursively attach a validator to parameters of type T.

Parameters
depth[in] Determines the number of levels of depth that the validator attachment will recurse into.

Definition at line 1010 of file Teuchos_ParameterList.hpp.

template<typename T >
T & Teuchos::ParameterList::get ( const std::string &  name,
def_value 
)

Return the parameter's value, or the default value if it is not there.

If the parameter with the given name exists in this ParameterList and has type T, return the parameter's value. If the parameter exists but does not have type T, throw an exception. Otherwise, if the parameter does not exist, add it to the list with value def_value, and return def_value.

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

Definition at line 1032 of file Teuchos_ParameterList.hpp.

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

Specialization of get(), where the nominal value is a character string. Both char* and std::string are stored as strings and return std::string values.

Definition at line 1047 of file Teuchos_ParameterList.hpp.

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

Specialization of get(), where the nominal value is a character string. 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)

Get a nonconst reference to the parameter.

Parameters
name[in] The name of the parameter.

If the given parameter is not in the list at all, this method throws Exceptions::InvalidParameter. If the parameter is in the list but does not have type T, this method throws Exceptions::InvalidParameterType. Both exceptions are subclasses of Exceptions::InvalidParameter.

You may use the returned reference to modify the parameter's value in the list directly.

When you call this method, you must specify the type T explicitly. For example:

const int x = 42;
plist.set ("The Answer", x);
// ...
const int y = plist.get<int> ("The Answer");

If the type T is itself a template parameter in your code, you must use the template keyword. For example:

template<class T>
T& getMyParameter (Teuchos::ParameterList& plist) {
return plist.template get<T> ("My Parameter");
}

Definition at line 1057 of file Teuchos_ParameterList.hpp.

template<typename T >
const T & Teuchos::ParameterList::get ( const std::string &  name) const

Get a const reference to the parameter.

Parameters
name[in] The name of the parameter.

If the given parameter is not in the list at all, this method throws Exceptions::InvalidParameter. If the parameter is in the list but does not have type T, this method throws Exceptions::InvalidParameterType. Both exceptions are subclasses of Exceptions::InvalidParameter.

When you call this method, you must specify the type T explicitly. For example:

const int x = 42;
plist.set ("The Answer", x);
// ...
const int y = plist.get<int> ("The Answer");

If the type T is itself a template parameter in your code, you must use the template keyword. For example:

template<class T>
const T& getMyParameter (const Teuchos::ParameterList& plist) {
return plist.template get<T> ("My Parameter");
}

Definition at line 1067 of file Teuchos_ParameterList.hpp.

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

Definition at line 1078 of file Teuchos_ParameterList.hpp.

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

Definition at line 1099 of file Teuchos_ParameterList.hpp.

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.

Definition at line 1116 of file Teuchos_ParameterList.hpp.

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.

Definition at line 1125 of file Teuchos_ParameterList.hpp.

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

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

Definition at line 1135 of file Teuchos_ParameterList.hpp.

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.

Definition at line 1148 of file Teuchos_ParameterList.hpp.

RCP< ParameterEntry > Teuchos::ParameterList::getEntryRCP ( const std::string &  name)
inline

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

Definition at line 1160 of file Teuchos_ParameterList.hpp.

RCP< const ParameterEntry > Teuchos::ParameterList::getEntryRCP ( const std::string &  name) const
inline

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

Definition at line 1172 of file Teuchos_ParameterList.hpp.

RCP< const ParameterListModifier > Teuchos::ParameterList::getModifier ( ) const
inline

Return the optional modifier object.

Definition at line 1184 of file Teuchos_ParameterList.hpp.

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 throwIfNotExists==false).

Definition at line 225 of file Teuchos_ParameterList.cpp.

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.

Definition at line 244 of file Teuchos_ParameterList.cpp.

ParameterList & Teuchos::ParameterList::sublist ( const std::string &  name,
RCP< const ParameterListModifier > const &  modifier,
const std::string &  docString = "" 
)

Creates an empty sublist with an optional modifier and returns a reference to the sublist name. If a list or parameter with the same name already exists then an std::exception is thrown.

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

Definition at line 296 of file Teuchos_ParameterList.cpp.

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

The name of this ParameterList.

Definition at line 1192 of file Teuchos_ParameterList.hpp.

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

Whether the given parameter exists in this list.

Return true if a parameter with name name exists in this list, else return false.

Definition at line 214 of file Teuchos_ParameterList.cpp.

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

Whether the given sublist exists in this list.

Return true if a parameter with name name exists in this list, and is itself a ParameterList. Otherwise, return false.

Definition at line 203 of file Teuchos_ParameterList.cpp.

template<typename T >
bool Teuchos::ParameterList::isType ( const std::string &  name) const

Whether the given parameter exists in this list and has type T.

Return true if a parameter with name name exists in this list and has type T. Otherwise, return false.

Definition at line 1213 of file Teuchos_ParameterList.hpp.

Ordinal Teuchos::ParameterList::numParams ( ) const

Get the number of stored parameters.

Definition at line 70 of file Teuchos_ParameterList.cpp.

void Teuchos::ParameterList::print ( ) const

Print function to use in debugging in a debugger.

Prints to *VerboseObjectBase::getDefaultOStream() so it will print well in parallel.

Definition at line 312 of file Teuchos_ParameterList.cpp.

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

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

Definition at line 318 of file Teuchos_ParameterList.cpp.

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

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

Definition at line 377 of file Teuchos_ParameterList.cpp.

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

Print out unused parameters in the ParameterList.

Definition at line 174 of file Teuchos_ParameterList.cpp.

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

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

Definition at line 185 of file Teuchos_ParameterList.cpp.

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

An iterator pointing to the first entry.

Definition at line 1222 of file Teuchos_ParameterList.hpp.

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

An iterator pointing beyond the last entry.

Definition at line 1228 of file Teuchos_ParameterList.hpp.

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

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

Definition at line 1234 of file Teuchos_ParameterList.hpp.

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

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

Definition at line 1240 of file Teuchos_ParameterList.hpp.

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

Definition at line 383 of file Teuchos_ParameterList.cpp.

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

Definition at line 575 of file Teuchos_ParameterList.cpp.

void Teuchos::ParameterList::modifyParameterList ( ParameterList validParamList,
int const  depth = 1000 
)

Modify the valid parameter list prior to validation.

Parameters
validModifiedParamList[in,out] The parameter list used as a template for validation.
depth[in] Determines the number of levels of depth that the modification will recurse into. A value of depth=0 means that only the top level parameters and sublists will be checked. Default: depth = large number.

We loop over the valid parameter list in this modification routine. This routine adds and/or removes fields in the valid parameter list to match the structure of the parameter list about to be validated. After completion, both parameter lists should have the same fields or else an error will be thrown during validation.

Definition at line 484 of file Teuchos_ParameterList.cpp.

void Teuchos::ParameterList::reconcileParameterList ( ParameterList validParamList,
const bool  left_to_right = true 
)

Reconcile a parameter list after validation.

Parameters
validParamList[in,out] The parameter list used as a template for validation.
left_to_right[in] Sweep through the parameter list tree from left to right.

We loop through the valid parameter list in reverse breadth-first order in this reconciliation routine. This routine assumes that the reconciliation routine won't create new sublists as it traverses the parameter list.

Definition at line 518 of file Teuchos_ParameterList.cpp.

ParameterList::Iterator Teuchos::ParameterList::nonconstBegin ( )
inlineprivate

An iterator pointing to the first entry.

Definition at line 1249 of file Teuchos_ParameterList.hpp.

ParameterList::Iterator Teuchos::ParameterList::nonconstEnd ( )
inlineprivate

An iterator pointing beyond the last entry.

Definition at line 1255 of file Teuchos_ParameterList.hpp.

ParameterEntry & Teuchos::ParameterList::nonconstEntry ( Iterator  i)
inlineprivate

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

Definition at line 1261 of file Teuchos_ParameterList.hpp.

void Teuchos::ParameterList::validateEntryExists ( const std::string &  funcName,
const std::string &  name,
const ParameterEntry entry 
) const
private

Validate that a parameter exists.

Definition at line 722 of file Teuchos_ParameterList.cpp.

template<typename T >
void Teuchos::ParameterList::validateEntryType ( const std::string &  funcName,
const std::string &  name,
const ParameterEntry entry 
) const
inlineprivate

Validate that a type is the same.

Definition at line 1269 of file Teuchos_ParameterList.hpp.

void Teuchos::ParameterList::validateEntryIsList ( const std::string &  name,
const ParameterEntry entry 
) const
private

Validate a sublist param is indeed a sublist.

Definition at line 737 of file Teuchos_ParameterList.cpp.

void Teuchos::ParameterList::validateMissingSublistMustExist ( const std::string &  baselist_name,
const std::string &  sublist_name,
const bool  mustAlreadyExist 
) const
private

Throw a sublist does not exist exception.

Definition at line 748 of file Teuchos_ParameterList.cpp.

void Teuchos::ParameterList::updateSubListNames ( int  depth = 0)
private

Update sublist names recursively.

Definition at line 705 of file Teuchos_ParameterList.cpp.

Friends And Related Function Documentation

enum EValidateUsed
related

Validation used enum.

Enumerator
VALIDATE_USED_ENABLED 

Validate that parameters in *this list set using the default value are present in the validation list

VALIDATE_USED_DISABLED 

Do not validate that parameters in *this list set using the default value are present in the validation list

Definition at line 37 of file Teuchos_ParameterList.hpp.

enum EValidateDefaults
related

Validation defaults enum.

Enumerator
VALIDATE_DEFAULTS_ENABLED 

Validate that parameters in *this list set using the default value are present in the validation list

VALIDATE_DEFAULTS_DISABLED 

Do not validate that parameters in *this list set using the default value are present in the validation list

Definition at line 49 of file Teuchos_ParameterList.hpp.

RCP< ParameterList > parameterList ( )
related

Nonmember constructor.

Definition at line 793 of file Teuchos_ParameterList.hpp.

RCP< ParameterList > parameterList ( const std::string &  name)
related

Nonmember constructor.

Definition at line 804 of file Teuchos_ParameterList.hpp.

RCP< ParameterList > parameterList ( const ParameterList source)
related

Nonmember constructor.

Definition at line 815 of file Teuchos_ParameterList.hpp.

RCP< ParameterList > createParameterList ( )
related

Nonmember constructor.

Definition at line 826 of file Teuchos_ParameterList.hpp.

RCP< ParameterList > createParameterList ( const std::string &  name)
related

Nonmember constructor.

Definition at line 837 of file Teuchos_ParameterList.hpp.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT 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 868 of file Teuchos_ParameterList.hpp.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameModifiers ( const ParameterList list1,
const ParameterList list2 
)
related

Returns true if two parameter lists have the same modifiers.

Recursively compares the modifiers in two parameter lists for equality.Return true if a modified parameter list has the same modifiers as the modified parameter list being used as input.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValues ( const ParameterList list1,
const ParameterList list2,
bool  verbose = false 
)
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.

Note
This function respects ordering of the ParameterList entries; the same values in a different order will result in false.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValuesSorted ( const ParameterList list1,
const ParameterList list2,
bool  verbose = false 
)
related

Returns true if two parameter lists have the same values independent of ordering.

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.

Note
This function does not respect ordering of the ParameterList entries; the same values in a different order will result in true.
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" )

Definition at line 1295 of file Teuchos_ParameterList.hpp.

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

Definition at line 1308 of file Teuchos_ParameterList.hpp.

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

Definition at line 1321 of file Teuchos_ParameterList.hpp.

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

Definition at line 1336 of file Teuchos_ParameterList.hpp.

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

Definition at line 1351 of file Teuchos_ParameterList.hpp.

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

Definition at line 1365 of file Teuchos_ParameterList.hpp.

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

Definition at line 1379 of file Teuchos_ParameterList.hpp.

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.

Definition at line 1397 of file Teuchos_ParameterList.hpp.

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:

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.

Definition at line 1473 of file Teuchos_ParameterList.hpp.

template<typename T >
bool replaceParameterWithArray ( const std::string &  paramName,
const std::string &  newName,
ParameterList pl 
)
related

Replace a parameter with an array containing the parameter.

Parameters
paramName[in] The name of the parameter to be placed in an array.
newName[in] The name of the new parameter containing the old parameter in an array.
pl[in,out] The parameter list pl containing paramName.
Returns
Returns true if the parameter paramName exists in pl.

Definition at line 1536 of file Teuchos_ParameterList.hpp.

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

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

Definition at line 1563 of file Teuchos_ParameterList.hpp.

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

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

Definition at line 1577 of file Teuchos_ParameterList.hpp.

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

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

Definition at line 1589 of file Teuchos_ParameterList.hpp.

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 
)
related

Set up a std::string parameter that will use an embedded validator to allow the extraction of an integral value.

The function getIntegralValue() can then be used to extract the integral value of the std::string parameter. In this case, the integral value returned will just be the zero-based index of the std::string value in the list strings.

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 
)
related

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.

The function getIntegralValue() can then be used to extract the integral value of the std::string parameter. In this case, the integral value return will just be the zero-based index of the std::string value in the list strings.

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 
)
related

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.

The function getIntegralValue() can then be used to extract the integral value of the std::string parameter. In this case, the integral value return will just be the zero-based index of the std::string value in the list strings.

template<class IntegralType >
IntegralType getIntegralValue ( ParameterList const &  paramList,
std::string const &  paramName 
)
related

Get an integral value for a parameter that is assumed to already be set.

This function does a dynamic cast to get the underlying validator of type StringToIntegralParameterEntryValidator<IntegralType>. If this dynamic cast fails then an Exceptions::InvalidParameterType std::exception is thrown with an excellent error message.

template<class IntegralType >
std::string getStringValue ( ParameterList const &  paramList,
std::string const &  paramName 
)
related

Get a std::string value for a parameter that is assumed to already be set.

This function does a dynamic cast to get the underlying valiator of type StringToIntegralParameterEntryValidator<IntegralValue>. The default type for IntegralValue is int. If this dynamic cast failes then an Exceptions::InvalidParameterType std::exception is thrown with an excellent error message.

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

Set an integer parameter that allows for (nearly) any input parameter type that is convertible to an int.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void setLongLongParameter ( std::string const &  paramName,
long long const  value,
std::string const &  docString,
ParameterList paramList,
AnyNumberParameterEntryValidator::AcceptedTypes const &  acceptedTypes = AnyNumberParameterEntryValidator::AcceptedTypes() 
)
related

Set an integer parameter that allows for (nearly) any input parameter type that is convertible to an int.

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

Set an double parameter that allows for (nearly) any input parameter type that is convertible to a double.

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

Set an numeric parameter preferred as a std::string that allows for (nearly) any input parameter type that is convertible to a std::string.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT int getIntParameter ( ParameterList const &  paramList,
std::string const &  paramName 
)
related

Get an integer parameter.

If the underlying parameter type is already an integer, then all is good. However, if it is not, then a AnyNumberParameterEntryValidator object is looked for to extract the type correctly. If no validator is attached to the entry, then a new AnyNumberParameterEntryValidator object will be created that that will allow the conversion from any supported type.

The parameter must exist or an Exceptions::InvalidParameterName object will be thrown. The parameters type must be acceptable, or an Exceptions::InvalidParameterType object will be thown.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT long long getLongLongParameter ( ParameterList const &  paramList,
std::string const &  paramName 
)
related

Get a long long parameter.

If the underlying parameter type is already a long long, then all is good. However, if it is not, then a AnyNumberParameterEntryValidator object is looked for to extract the type correctly. If no validator is attached to the entry, then a new AnyNumberParameterEntryValidator object will be created that that will allow the conversion from any supported type.

The parameter must exist or an Exceptions::InvalidParameterName object will be thrown. The parameters type must be acceptable, or an Exceptions::InvalidParameterType object will be thown.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT double getDoubleParameter ( ParameterList const &  paramList,
std::string const &  paramName 
)
related

Get double integer parameter.

If the underlying parameter type is already a double, then all is good. However, if it is not, then a AnyNumberParameterEntryValidator object is looked for to extract the type correctly. If no validator is attached to the entry, then a new AnyNumberParameterEntryValidator object will be created that that will allow the conversion from any supported type.

The parameter must exist or an Exceptions::InvalidParameterName object will be thrown. The parameters type must be acceptable, or an Exceptions::InvalidParameterType object will be thown.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT std::string getNumericStringParameter ( ParameterList const &  paramList,
std::string const &  paramName 
)
related

Get std::string numeric parameter.

If the underlying parameter type is already a std::string, then all is good. However, if it is not, then a AnyNumberParameterEntryValidator object is looked for to extract the type correctly. If no validator is attached to the entry, then a new AnyNumberParameterEntryValidator object will be created that that will allow the conversion from any supported type.

The parameter must exist or an Exceptions::InvalidParameterName object will be thrown. The parameters type must be acceptable, or an Exceptions::InvalidParameterType object will be thown.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void updateParametersFromXmlFile ( const std::string &  xmlFileName,
const Ptr< ParameterList > &  paramList 
)
related

Reads XML parameters from a file and updates those already in the given parameter list.

Parameters
xmlFileName[in] The file name containing XML parameter list specification.
paramList[in/out] On input, *paramList may be empty or contain some parameters and sublists. On output, parameters and sublist from the file xmlFileName will be set or overide those in *paramList.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT RCP< ParameterList > getParametersFromXmlFile ( const std::string &  xmlFileName)
related

Reads XML parameters from a file and return them in a new parameter list.

Parameters
xmlFileName[in] The file name containing XML parameter list specification.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT RCP< ParameterList > getParametersFromXmlFile ( const std::string &  xmlFileName,
RCP< DependencySheet depSheet 
)
related

Reads XML parameters from a file and return them in a new parameter list.

Parameters
xmlFileName[in] The file name containing XML parameter list specification.
depSheet[out] The Dependency Sheet into which Dependencies should be placed.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void updateParametersFromXmlString ( const std::string &  xmlStr,
const Ptr< ParameterList > &  paramList,
bool  overwrite = true 
)
related

Reads XML parameters from a std::string and updates those already in the given parameter list.

Parameters
xmlStr[in] String containing XML parameter list specification.
paramList[in/out] On input, *paramList may be empty or contain some parameters and sublists. On output, parameters and sublist from the file xmlStr will be set or override (or not) those in *paramList depending on the overwrite parameter.
overwrite[in] If true, parameters and sublists in the xmlStr will override those in paramList. If false, any value set in paramList will be kept, only values not set will be updated.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT RCP< ParameterList > getParametersFromXmlString ( const std::string &  xmlStr)
related

Reads XML parameters from a std::string and return them in a new parameter list.

Parameters
xmlStr[in] String containing XML parameter list specification.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT RCP< ParameterList > getParametersFromXmlString ( const std::string &  xmlStr,
RCP< DependencySheet depSheet 
)
related

Reads XML parameters from a std::string and return them in a new parameter list.

Parameters
xmlStr[in] String containing XML parameter list specification.
depSheet[in] The Dependency Sheet into which Dependencies should be placed.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void writeParameterListToXmlOStream ( const ParameterList paramList,
std::ostream &  xmlOut,
RCP< const DependencySheet depSheet = null 
)
related

Write parameters and sublists in XML format to an std::ostream.

Parameters
paramList[in] Contains the parameters and sublists that will be written to file.
xmlOut[in] The stream that will get the XML output.
depSheet[in] The Dependency Sheet which should be written out.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void writeParameterListToXmlFile ( const ParameterList paramList,
const std::string &  xmlFileName,
RCP< const DependencySheet depSheet = null 
)
related

Write parameters and sublist to an XML file.

Parameters
paramList[in] Contains the parameters and sublists that will be written to file.
xmlFileName[in] The file name that will be create to contain the XML version of the parameter list specification.
depSheet[in] The Dependency Sheet which should be written out.
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void updateParametersFromYamlFile ( const std::string &  yamlFileName,
const Ptr< ParameterList > &  paramList 
)
related

Reads Yaml parameters from a file and updates those already in the given parameter list.

Parameters
yamlFileName[in] The file name containing Yaml parameter list specification.
paramList[in/out] On input, *paramList may be empty or contain some parameters and sublists. On output, parameters and sublist from the file yamlFileName will be set or overide those in *paramList.

Definition at line 1084 of file Teuchos_YamlParser.cpp.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT RCP< ParameterList > getParametersFromYamlFile ( const std::string &  yamlFileName)
related

Reads Yaml parameters from a file and return them in a new parameter list.

Parameters
yamlFileName[in] The file name containing Yaml parameter list specification.

Definition at line 1133 of file Teuchos_YamlParser.cpp.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void updateParametersFromYamlString ( const std::string &  yamlStr,
const Ptr< ParameterList > &  paramList,
bool  overwrite,
const std::string &  name = "" 
)
related

Reads Yaml parameters from a std::string and updates those already in the given parameter list.

Parameters
yamlStr[in] String containing Yaml parameter list specification.
paramList[in/out] On input, *paramList may be empty or contain some parameters and sublists. On output, parameters and sublist from the file yamlStr will be set or override (or not) those in *paramList depending on the overwrite parameter.
overwrite[in] If true, parameters and sublists in the yamlStr will override those in paramList. If false, any value set in paramList will be kept, only values not set will be updated.

Definition at line 1114 of file Teuchos_YamlParser.cpp.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT RCP< ParameterList > getParametersFromYamlString ( const std::string &  yamlStr)
related

Reads Yaml parameters from a std::string and return them in a new parameter list.

Parameters
yamlStr[in] String containing Yaml parameter list specification.

Definition at line 1138 of file Teuchos_YamlParser.cpp.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void writeParameterListToYamlOStream ( const ParameterList paramList,
std::ostream &  yamlOut 
)
related

Write parameters and sublists in Yaml format to an std::ostream.

Parameters
paramList[in] Contains the parameters and sublists that will be written to file.
yamlOut[in] The stream that will get the Yaml output.

Definition at line 1144 of file Teuchos_YamlParser.cpp.

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void writeParameterListToYamlFile ( const ParameterList paramList,
const std::string &  yamlFileName 
)
related

Write parameters and sublist to an Yaml file.

Parameters
paramList[in] Contains the parameters and sublists that will be written to file.
yamlFileName[in] The file name that will be create to contain the Yaml version of the parameter list specification.

Definition at line 1152 of file Teuchos_YamlParser.cpp.

TEUCHOSCOMM_LIB_DLL_EXPORT void updateParametersAndBroadcast ( const Ptr< ParameterList > &  inParamList,
const Ptr< ParameterList > &  ParamList,
const Comm< int > &  comm,
int  root,
bool  overwrite = true 
)
related

On processor rank = root, broadcast the inParamList to all other processors. Then update the given parameter list with these values.

Parameters
inParamList[in] On input, *inParamList may be empty or contain some parameters and sublists. This list is only used on rank = root.
paramList[in/out] On input, *paramList may be empty or contain some parameters and sublists. On output, parameters and sublist from rank = root will be set or override (or not) those in *paramList depending on the overwrite parameter.
comm[in] A Comm object used to broadcast the xml.
root[in] The rank which will broadcast the list.
overwrite[in] If true, parameters and sublists in the inParamList will override those in paramList. If false, any value set in paramList will be kept, only values not set will be updated.
TEUCHOSCOMM_LIB_DLL_EXPORT void updateParametersFromXmlFileAndBroadcast ( const std::string &  xmlFileName,
const Ptr< ParameterList > &  paramList,
const Comm< int > &  comm,
bool  overwrite = true 
)
related

On processor rank = 0, reads XML parameters from a file and broadcasts them to all other processors. Then updates the given parameter list with these values.

Parameters
xmlFileName[in] The file name containing XML parameter list specification.
paramList[in/out] On input, *paramList may be empty or contain some parameters and sublists. On output, parameters and sublist from the file xmlFileName will be set or override (or not) those in *paramList depending on the overwrite parameter.
comm[in] A Comm object used to broadcast the xml.
overwrite[in] If true, parameters and sublists in the xmlStr will override those in paramList. If false, any value set in paramList will be kept, only values not set will be updated.
TEUCHOSCOMM_LIB_DLL_EXPORT void updateParametersFromYamlFileAndBroadcast ( const std::string &  yamlFileName,
const Teuchos::Ptr< Teuchos::ParameterList > &  paramList,
const Teuchos::Comm< int > &  comm,
bool  overwrite = true 
)
related

On processor rank = 0, reads Yaml parameters from a file and broadcasts them to all other processors. Then updates the given parameter list with these values.

Parameters
xmlFileName[in] The file name containing Yaml parameter list specification.
paramList[in/out] On input, *paramList may be empty or contain some parameters and sublists. On output, parameters and sublist from the file xmlFileName will be set or override (or not) those in *paramList depending on the overwrite parameter.
comm[in] A Comm object used to broadcast the xml.
overwrite[in] If true, parameters and sublists in the xmlStr will override those in paramList. If false, any value set in paramList will be kept, only values not set will be updated.

Member Data Documentation

std::string Teuchos::ParameterList::name_ = "ANONYMOUS"
private

Name of the (sub)list.

Definition at line 762 of file Teuchos_ParameterList.hpp.

params_t Teuchos::ParameterList::params_
private

Parameter list.

Definition at line 770 of file Teuchos_ParameterList.hpp.

bool Teuchos::ParameterList::disableRecursiveValidation_ = false
private

Validate into list or not.

Definition at line 776 of file Teuchos_ParameterList.hpp.

bool Teuchos::ParameterList::disableRecursiveModification_ = false
private

Modify into list or not.

Definition at line 779 of file Teuchos_ParameterList.hpp.

bool Teuchos::ParameterList::disableRecursiveReconciliation_ = false
private

Reconcile into list or not.

Definition at line 782 of file Teuchos_ParameterList.hpp.

RCP<const ParameterListModifier> Teuchos::ParameterList::modifier_ = null
private

Definition at line 784 of file Teuchos_ParameterList.hpp.


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