Teuchos_ParameterList.hpp

Go to the documentation of this file.

// @HEADER
// ***********************************************************************
//
//                    Teuchos: Common Tools Package
//                 Copyright (2004) Sandia Corporation
//
// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
// license for use of this work by or on behalf of the U.S. Government.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Questions? Contact Michael A. Heroux (maherou@sandia.gov)
//
// ***********************************************************************
// @HEADER
 
 
#ifndef TEUCHOS_PARAMETER_LIST_H
#define TEUCHOS_PARAMETER_LIST_H
 
#include "Teuchos_ParameterListExceptions.hpp"
#include "Teuchos_ParameterEntry.hpp"
#include "Teuchos_StringIndexedOrderedValueObjectContainer.hpp"
#include "Teuchos_Assert.hpp"
#include "Teuchos_RCP.hpp"
#include "Teuchos_Array.hpp"
#include "Teuchos_map.hpp"
 
 
namespace Teuchos {
 
enum EValidateUsed {
  VALIDATE_USED_ENABLED   
  ,VALIDATE_USED_DISABLED 
};
 
enum EValidateDefaults {
  VALIDATE_DEFAULTS_ENABLED   
  ,VALIDATE_DEFAULTS_DISABLED 
};
 
class TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT ParameterList {
 
  typedef StringIndexedOrderedValueObjectContainer<ParameterEntry> params_t;
 
  typedef params_t::Iterator Iterator;
  
public:
 
 
 
  typedef params_t::ConstIterator ConstIterator;
 
  class PrintOptions {
  public:
    PrintOptions() : indent_(0), showTypes_(false), showFlags_(false), showDoc_(false) {}
    PrintOptions& indent(int _indent)        { indent_ = _indent; return *this; }
    PrintOptions& showTypes(bool _showTypes) { showTypes_ = _showTypes; return *this; }
    PrintOptions& showFlags(bool _showFlags) { showFlags_ = _showFlags; return *this; }
    PrintOptions& showDoc(bool _showDoc)     { showDoc_ = _showDoc; return *this; }
    PrintOptions& incrIndent(int indents)    { indent_ += indents; return *this; }
    int indent() const { return indent_; }
    bool showTypes() const { return showTypes_; }
    bool showFlags() const { return showFlags_; }
    bool showDoc() const { return showDoc_; }
    PrintOptions copy() const { return PrintOptions(*this); }
  private:
    int    indent_;
    bool   showTypes_;
    bool   showFlags_;
    bool   showDoc_;
  };
 
  
 
 
  ParameterList();
 
  ParameterList(const std::string &name);
  
  ParameterList(const ParameterList& source);
  
  virtual ~ParameterList();
 
  Ordinal numParams () const;
 
 
 
  ParameterList& setName( const std::string &name );
  
  ParameterList& operator= (const ParameterList& source);
  
  ParameterList& setParameters(const ParameterList& source);
  
  ParameterList& setParametersNotAlreadySet(const ParameterList& source);
 
  ParameterList& disableRecursiveValidation();
  
  template<typename T>
  ParameterList& set (std::string const& name, 
          T const& value, 
          std::string const& docString = "",
          RCP<const ParameterEntryValidator> const& validator = null);
 
  ParameterList& set(
    std::string const& name, char value[], std::string const& docString = "",
    RCP<const ParameterEntryValidator> const& validator = null
    );
 
  ParameterList& set(
    std::string const& name, const char value[], std::string const& docString = "",
    RCP<const ParameterEntryValidator> const& validator = null
    );
 
  ParameterList& set(
    std::string const& name, ParameterList const& value, std::string const& docString = ""
    );
 
  ParameterList& setEntry(const std::string& name, const ParameterEntry& entry);
 
 
 
  template<typename T>
  T& get(const std::string& name, T def_value);
 
  std::string& get(const std::string& name, char def_value[]);
  
  std::string& get(const std::string& name, const char def_value[]);
 
  template<typename T>
  T& get (const std::string& name);
 
  template<typename T>
  const T& get (const std::string& name) const;  
  
  template<typename T>
  inline
  T* getPtr(const std::string& name);
  
  template<typename T>
  inline
  const T* getPtr(const std::string& name) const;  
 
  // ToDo: Add getSafePtr() functions to return Ptr<T> instead of raw T*
  
  ParameterEntry& getEntry(const std::string& name);  
  
  inline
  const ParameterEntry& getEntry(const std::string& name) const;  
  
  inline
  ParameterEntry* getEntryPtr(const std::string& name);  
 
  // ToDo: Add function called getEntrySafePtr() to return Ptr<> as the main
  // implementation and deprecate getEntryPtr()
  
  inline
  const ParameterEntry* getEntryPtr(const std::string& name) const;  
 
  inline RCP<ParameterEntry> getEntryRCP(const std::string& name);  
  
  inline RCP<const ParameterEntry> getEntryRCP(const std::string& name) const;
 
 
 
 
  bool remove(
    std::string const& name, bool throwIfNotExists = true
    );
 
  
 
 
  ParameterList& sublist(
    const std::string& name, bool mustAlreadyExist = false
    ,const std::string& docString = ""
    );
  
  const ParameterList& sublist(const std::string& name) const;
 
  
 
 
  const std::string& name() const;
 
  bool isParameter (const std::string& name) const;
 
  bool isSublist (const std::string& name) const;
 
  template<typename T>
  bool isType (const std::string& name) const;
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS  
 
  template<typename T>
  bool isType(const std::string& name, T* ptr) const;
#endif
 
  
 
 
  void print() const;
 
  std::ostream& print(std::ostream& os, const PrintOptions &printOptions) const;
 
  std::ostream& print(std::ostream& os, int indent = 0, bool showTypes = false, bool showFlags = true ) const;
  
  void unused(std::ostream& os) const;
 
  std::string currentParametersString() const;
 
 
 
 
  inline ConstIterator begin() const;
 
  inline ConstIterator end() const;
  
  inline const std::string& name(ConstIterator i) const;
 
  inline const ParameterEntry& entry(ConstIterator i) const;
 
 
 
 
  void validateParameters(
    ParameterList const& validParamList,
    int const depth = 1000,
    EValidateUsed const validateUsed = VALIDATE_USED_ENABLED,
    EValidateDefaults const validateDefaults = VALIDATE_DEFAULTS_ENABLED
    ) const;
 
  void validateParametersAndSetDefaults(
    ParameterList const& validParamList,
    int const depth = 1000
    );
 
  
private: // Functions
 
  inline Iterator nonconstBegin();
  inline Iterator nonconstEnd();
  inline ParameterEntry& nonconstEntry(Iterator i);
  void validateEntryExists(const std::string &funcName, const std::string &name,
    const ParameterEntry *entry) const;
  // ToDo: Change above function to take Ptr<> instead of raw pointer.
  template<typename T>
  void validateEntryType(const std::string &funcName, const std::string &name,
    const ParameterEntry &entry ) const;
  void validateEntryIsList(const std::string &name, const ParameterEntry &entry) const;
  void validateMissingSublistMustExist(const std::string &baselist_name,
    const std::string &sublist_name, const bool mustAlreadyExist) const;
  void updateSubListNames(int depth = 0);
  
private: // Data members
 
  std::string name_;
 
//use pragmas to disable some false-positive warnings for windows sharedlibs export
//#ifdef _MSC_VER
//#pragma warning(push)
//#pragma warning(disable:4251)
//#endif
  params_t params_;
//#ifdef _MSC_VER
//#pragma warning(pop)
//#endif
 
  bool disableRecursiveValidation_;
 
};
 
 
inline
RCP<ParameterList> parameterList()
{
  return rcp(new ParameterList);
}
 
 
inline
RCP<ParameterList> parameterList(const std::string &name)
{
  return rcp(new ParameterList(name));
}
  
 
inline
RCP<ParameterList> parameterList(const ParameterList& source)
{
  return rcp(new ParameterList(source));
}
 
 
inline
RCP<ParameterList> createParameterList()
{
  return rcp(new ParameterList);
}
 
 
inline
RCP<ParameterList> createParameterList(const std::string &name)
{
  return rcp(new ParameterList(name));
}
 
 
template<>
class TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT TypeNameTraits<ParameterList> {
public:
  static std::string name() { return "ParameterList"; }
  static std::string concreteName( const ParameterList& /*t2*/ )
    { return name(); }
};
 
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool operator==( const ParameterList& list1, const ParameterList& list2 );
 
 
inline
bool operator!=( const ParameterList& list1, const ParameterList& list2 )
{
  return !( list1 == list2 );
}
 
 
TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValues( const ParameterList& list1, const ParameterList& list2,
    bool verbose = false);
 
 
// /////////////////////////////////////////////////////
// Inline and Template Function Definitions
 
 
inline
ParameterList& ParameterList::setName( const std::string &name_in )
{
  name_ = name_in;
  return *this;
}
 
 
// Set functions
 
 
template<typename T>
inline
ParameterList& ParameterList::set(
  std::string const& name_in, T const& value_in, std::string const& docString_in,
  RCP<const ParameterEntryValidator> const& validator_in
  )
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
    Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
    const std::string docString =
      (docString_in.length() ? docString_in : param->docString());
    const RCP<const ParameterEntryValidator> validator =
      (nonnull(validator_in) ? validator_in : param->validator());
     // Create temp param to validate before setting
    ParameterEntry param_new(value_in, false, false, docString, validator );
    if (nonnull(validator)) {
      validator->validate(param_new, name_in, this->name());
    }
    // Strong guarantee: (if exception is thrown, the value is not changed)
    *param = param_new;
  }
  else {
    ParameterEntry param_new(value_in, false, false, docString_in, validator_in);
    if (nonnull(param_new.validator())) {
      param_new.validator()->validate(param_new, name_in, this->name());
    }
    params_.setObj(name_in, param_new);
  }
  return *this;
}
 
 
inline
ParameterList& ParameterList::set(
  std::string const& name_in, char value[], std::string const& docString
  ,RCP<const ParameterEntryValidator> const& validator
  ) 
{ return set(name_in, std::string(value), docString, validator); }
 
 
inline
ParameterList& ParameterList::set(
  const std::string& name_in, const char value[], const std::string &docString
  ,RCP<const ParameterEntryValidator> const& validator
  ) 
{ return set( name_in, std::string(value), docString, validator ); }
 
 
inline
ParameterList& ParameterList::set(
  std::string const& name_in, ParameterList const& value, std::string const& /*docString*/
  )
{
  sublist(name_in) = value;
  return *this;
}
 
 
inline
ParameterList& ParameterList::setEntry(std::string const& name_in, ParameterEntry const& entry_in)
{
  params_.setObj(name_in, entry_in);
  return *this;
}
 
 
// Get functions
 
 
template<typename T>
T& ParameterList::get(const std::string& name_in, T def_value)
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  Ordinal param_idx = params_.getObjOrdinalIndex(name_in); 
  if (param_idx == SIOVOCB::getInvalidOrdinal()) {
    // Param does not exist
    param_idx = params_.setObj(name_in, ParameterEntry(def_value, true));
  }
  Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
  this->template validateEntryType<T>("get", name_in, *param);
  return getValue<T>(*param);
}
 
 
inline
std::string& ParameterList::get(const std::string& name_in, char def_value[])
{ return get(name_in, std::string(def_value)); }
 
 
inline
std::string& ParameterList::get(const std::string& name_in, const char def_value[])
{ return get(name_in, std::string(def_value)); }
 
 
template<typename T>
T& ParameterList::get(const std::string& name_in) 
{
  ParameterEntry *foundEntry = this->getEntryPtr(name_in);
  validateEntryExists("get",name_in,foundEntry);
  this->template validateEntryType<T>("get",name_in,*foundEntry);
  return getValue<T>(*foundEntry);
}
 
  
template<typename T>
const T& ParameterList::get(const std::string& name_in) const
{
  const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
  validateEntryExists("get",name_in,foundEntry);
  this->template validateEntryType<T>("get",name_in,*foundEntry);
  return getValue<T>(*foundEntry);
}
 
 
template<typename T>
inline
T* ParameterList::getPtr(const std::string& name_in) 
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
    const Ptr<ParameterEntry> param_ptr = params_.getNonconstObjPtr(param_idx);
    if (param_ptr->isType<T>()) {
      return &param_ptr->getValue<T>(0);
    }
    // Note: The above is inefficinet.  You have to do the dynamic_cast twice
    // (once to see if it is the type and once to do the cast).  This could be
    // made more efficinet by upgrading Teuchos::any to add a any_cast_ptr()
    // function but I don't think anyone actually uses this function.
    return 0;
  }
  return 0;
}
 
  
template<typename T>
inline
const T* ParameterList::getPtr(const std::string& name_in) const
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
    const Ptr<const ParameterEntry> param_ptr = params_.getObjPtr(param_idx);
    if (param_ptr->isType<T>()) {
      return &param_ptr->getValue<T>(0);
    }
    // Note: The above is inefficinet, see above non-const getPtr() function.
    return 0;
  }
  return 0;
}
 
 
inline
ParameterEntry& ParameterList::getEntry(const std::string& name_in)
{
  ParameterEntry *foundEntry = this->getEntryPtr(name_in);
  validateEntryExists("get", name_in, foundEntry);
  return *foundEntry;
}
 
  
inline
const ParameterEntry& ParameterList::getEntry(const std::string& name_in) const
{
  const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
  validateEntryExists("get", name_in, foundEntry);
  return *foundEntry;
}
 
 
inline
ParameterEntry*
ParameterList::getEntryPtr(const std::string& name_in)
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
    return &*params_.getNonconstObjPtr(param_idx);
  }
  return 0;
}
 
 
inline
const ParameterEntry*
ParameterList::getEntryPtr(const std::string& name_in) const
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
    return &*params_.getObjPtr(param_idx);
  }
  return 0;
}
 
 
inline RCP<ParameterEntry>
ParameterList::getEntryRCP(const std::string& name_in)
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
    return rcpFromPtr(params_.getNonconstObjPtr(param_idx));
  }
  return null;
}
 
 
inline RCP<const ParameterEntry>
ParameterList::getEntryRCP(const std::string& name_in) const
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
    return rcpFromPtr(params_.getObjPtr(param_idx));
  }
  return null;
}
 
 
// Attribute Functions
 
 
inline
const std::string& ParameterList::name() const
{
  return name_;
}
 
  
#ifndef DOXYGEN_SHOULD_SKIP_THIS
template<typename T>
bool ParameterList::isType(const std::string& name_in, T* /*ptr*/) const
{
  typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
    return params_.getObjPtr(param_idx)->isType<T>();
  }
  return false;
}
#endif
 
  
template<typename T>
bool ParameterList::isType(const std::string& name_in) const
{
  return this->isType(name_in, static_cast<T*>(0));
}
 
 
// Read-only access to the iterator
 
 
inline ParameterList::ConstIterator ParameterList::begin() const
{
  return params_.begin();
}
 
 
inline ParameterList::ConstIterator ParameterList::end() const
{
  return params_.end();
}
 
 
inline const std::string& ParameterList::name(ConstIterator i) const
{
  return (i->first);
}
 
 
inline const ParameterEntry& ParameterList::entry(ConstIterator i) const
{
  return (i->second);
}
 
 
// private
 
 
inline ParameterList::Iterator ParameterList::nonconstBegin()
{
  return params_.nonconstBegin();
}
 
 
inline ParameterList::Iterator ParameterList::nonconstEnd()
{
  return params_.nonconstEnd();
}
 
 
inline ParameterEntry& ParameterList::nonconstEntry(Iterator i)
{
  return (i->second);
}
 
 
template<typename T>
inline
void ParameterList::validateEntryType(
  const std::string &/*funcName*/, const std::string &name_in,
  const ParameterEntry &entry_in
  ) const
{
  TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
    entry_in.getAny().type() != typeid(T), Exceptions::InvalidParameterType
    ,"Error!  An attempt was made to access parameter \""<<name_in<<"\""
    " of type \""<<entry_in.getAny().typeName()<<"\""
    "\nin the parameter (sub)list \""<<this->name()<<"\""
    "\nusing the incorrect type \""<<TypeNameTraits<T>::name()<<"\"!"
    );
}
 
 
// //////////////////////////////////////
// Helper functions
 
  
template<typename T>
T& getParameter( ParameterList& l, const std::string& name )
{
  return l.template get<T>(name);
}
 
  
template<typename T>
inline
T& get( ParameterList& l, const std::string& name )
{
  return getParameter<T>(l,name);
}
 
  
template<typename T>
const T& getParameter( const ParameterList& l, const std::string& name )
{
  return l.template get<T>(name);
}
 
  
template<typename T>
inline
T* getParameterPtr( ParameterList& l, const std::string& name )
{
  return l.template getPtr<T>(name);
}
 
  
template<typename T>
inline
const T* getParameterPtr( const ParameterList& l, const std::string& name )
{
  return l.template getPtr<T>(name);
}
 
  
template<typename T>
inline
bool isParameterType( ParameterList& l, const std::string& name )
{
  return l.isType( name, (T*)NULL );
}
 
  
template<typename T>
inline
bool isParameterType( const ParameterList& l, const std::string& name )
{
  return l.isType( name, (T*)NULL );
}
 
  
template<typename T>
void setStringParameterFromArray(
  const std::string          &paramName
  ,const Array<T>       &array
  ,ParameterList        *paramList
  )
{
  TEUCHOS_TEST_FOR_EXCEPT(!paramList);
  paramList->set(paramName,toString(array));
}
 
  
template<typename T>
Array<T> getArrayFromStringParameter(
  const ParameterList   &paramList
  ,const std::string         &paramName
  ,const int            arrayDim        = -1
  ,const bool           mustExist       = true
  )
{
  std::string arrayStr;
  if(mustExist) {
    arrayStr = getParameter<std::string>(paramList,paramName);
  }
  else {
    const std::string
      *arrayStrPtr = getParameterPtr<std::string>(paramList,paramName);
    if(arrayStrPtr) {
      arrayStr = *arrayStrPtr;
    }
    else {
      return Array<T>(); // Return an empty array
    }
  }
  Array<T> a;
  try {
    a = fromStringToArray<T>(arrayStr);
  }
  catch( const InvalidArrayStringRepresentation&) {
    TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
      true, Exceptions::InvalidParameterValue
      ,"Error!  The parameter \""<<paramName<<"\"\n"
      "in the sublist \""<<paramList.name()<<"\"\n"
      "exists, but the std::string value:\n"
      "----------\n"
      <<arrayStr<<
      "\n----------\n"
      "is not a valid array represntation!"
      );
  }
  TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
    ( ( a.size()>0 && arrayDim>=0 ) && static_cast<int>(a.size())!=arrayDim )
    ,Exceptions::InvalidParameterValue
    ,"Error!  The parameter \""<<paramName<<"\"\n"
    "in the sublist \""<<paramList.name()<<"\"\n"
    "exists and is a valid array, but the dimension of\n"
    "the read in array a.size() = " << a.size() << "\n"
    "was not equal to the expected size arrayDim = " << arrayDim << "!"
    );
  return a;
}
 
 
inline
RCP<ParameterList> sublist(
  const RCP<ParameterList> &paramList, const std::string& name,
  bool mustAlreadyExist = false, const std::string& docString = ""
  )
{
  return rcpWithEmbeddedObjPostDestroy(
    &paramList->sublist(name, mustAlreadyExist, docString), paramList, false );
}
 
 
inline
RCP<const ParameterList> sublist(
  const RCP<const ParameterList> &paramList, const std::string& name
  )
{
  return rcpWithEmbeddedObjPostDestroy(
    &paramList->sublist(name), paramList, false );
}
 
  
inline std::ostream& operator<<(std::ostream& os, const ParameterList& l)
{
  return l.print(os);
}
 
  
} // end of Teuchos namespace
 
 
#endif