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.
// 
// This library is free software; you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as
// published by the Free Software Foundation; either version 2.1 of the
// License, or (at your option) any later version.
//  
// This library is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//  
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
// USA
// Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
// 
// ***********************************************************************
// @HEADER


#ifndef TEUCHOS_PARAMETER_LIST_H
#define TEUCHOS_PARAMETER_LIST_H

#include "Teuchos_ParameterEntry.hpp" // class data element 
#include "Teuchos_TestForException.hpp"
#include "Teuchos_RefCountPtr.hpp"
#include "Teuchos_ConfigDefs.hpp"
#include "Teuchos_map.hpp"

namespace Teuchos {

enum EValidateUsed {
  VALIDATE_USED_ENABLED   /*< \brief Validate that parameters in <tt>*this</tt> list
                              set using the default value are present in
                              the validation list */
  ,VALIDATE_USED_DISABLED /*< \brief Do not validate that parameters in <tt>*this</tt> list
                              set using the default value are present in
                              the validation list */
};

enum EValidateDefaults {
  VALIDATE_DEFAULTS_ENABLED   /*< \brief Validate that parameters in <tt>*this</tt> list
                                  set using the default value are present in
                                   the validation list */
  ,VALIDATE_DEFAULTS_DISABLED /*< \brief Do not validate that parameters in <tt>*this</tt> list
                                  set using the default value are present in
                                  the validation list */
};

namespace Exceptions {

class InvalidParameter : public std::logic_error
{public: InvalidParameter(const std::string& what_arg) : std::logic_error(what_arg) {}};

} // namespace Exceptions

class ParameterList {

  typedef Teuchos::map<string, ParameterEntry> Map;

  typedef Map::iterator Iterator;
  
public:



  typedef Map::const_iterator ConstIterator;

  


  ParameterList();

  ParameterList(const std::string &name);
  
  ParameterList(const ParameterList& source);
  
  virtual ~ParameterList();

  


  void setName( const std::string &name );
  
  ParameterList& operator=(const ParameterList& source);
  
  ParameterList& setParameters(const ParameterList& source);
  
  template<typename T>
  void set(const string& name, T value);

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

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

  void set(const string& name, ParameterList value);

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

  

  
  template<typename T>
  T& get(const string& name, T def_value);

  std::string& get(const string& name, char def_value[]);
  
  std::string& get(const string& name, const char def_value[]);
  
  template<typename T>
  T& get(const string& name);
  
  template<typename T>
  const T& get(const string& name) const;  
  
  template<typename T>
  T* getPtr(const string& name);
  
  template<typename T>
  const T* getPtr(const string& name) const;  
  
  ParameterEntry* getEntryPtr(const string& name);  
  
  const ParameterEntry* getEntryPtr(const string& name) const;  

  


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

  


  const std::string& name() const;

  bool isParameter(const string& name) const;
  
  bool isSublist(const string& name) const;
  
  template<typename T>
  bool isType(const string& name) const;

#ifndef DOXYGEN_SHOULD_SKIP_THIS  

  template<typename T>
  bool isType(const string& name, T* ptr) const;
#endif

  


  ostream& print(ostream& os, int indent = 0, bool showTypes = false, bool showFlags = true ) const;
  
  void unused(ostream& os) const;

  std::string currentParametersString() const;




  ConstIterator begin() const ;

  ConstIterator end() const ;

  const ParameterEntry& entry(ConstIterator i) const;
  
  const string& name(ConstIterator i) const;




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

  
private: // Functions
  
  ParameterEntry& entry(Iterator i);
  void validateEntryExists( const std::string &funcName, const std::string &name, const ParameterEntry *entry ) const;
  template<typename T>
  void validateEntryType( const std::string &funcName, const std::string &name, const ParameterEntry &entry ) const;
  void updateSubListNames(int depth = 0);
  
private: // Data members

  std::string name_;
  Map params_;
};

template<>
class TypeNameTraits<ParameterList> {
public:
  static std::string name() { return "ParameterList"; }
};

bool operator==( const ParameterList& list1, const ParameterList& list2 );

inline
bool operator!=( const ParameterList& list1, const ParameterList& list2 )
{
  return !( list1 == list2 );
}

// /////////////////////////////////////////////////////
// Inline and Template Function Definitions

inline
void ParameterList::setName( const std::string &name )
{
  name_ = name;
}

// Set functions
 
template<typename T>
inline
void ParameterList::set(const string& name, T value)
{
  params_[name].setValue(value);
}

inline
void ParameterList::set(const string& name, char value[]) 
{ set( name, std::string(value) ); }

inline
void ParameterList::set(const string& name, const char value[]) 
{ set( name, std::string(value) ); }

inline
void ParameterList::set(const string& name, ParameterList value)
{ sublist(name) = value; }

inline
void ParameterList::setEntry(const string& name, const ParameterEntry& entry)
{params_[name] = entry;}

// Get functions

template<typename T>
T& ParameterList::get(const string& name, T def_value)
{
  ConstIterator i = params_.find(name);
    
  // The parameter was not found, add it to the list
  if (i == params_.end()) {
    params_[name].setValue(def_value, true);
    i = params_.find(name);
  } else {
    // The parameter was found, make sure it is the same type as T.
    this->template validateEntryType<T>("get",name,entry(i));
  }

  // Return the value of the parameter
  return getValue<T>(entry(i));
}

inline
std::string& ParameterList::get(const string& name, char def_value[])
{ return get(name, std::string(def_value)); }

inline
std::string& ParameterList::get(const string& name, const char def_value[])
{ return get(name, std::string(def_value)); }

template<typename T>
T& ParameterList::get(const string& name) 
{
  ParameterEntry *entry = this->getEntryPtr(name);
  validateEntryExists("get",name,entry);
  this->template validateEntryType<T>("get",name,*entry);
  return getValue<T>(*entry);
}
  
template<typename T>
const T& ParameterList::get(const string& name) const
{
  const ParameterEntry *entry = this->getEntryPtr(name);
  validateEntryExists("get",name,entry);
  this->template validateEntryType<T>("get",name,*entry);
  return getValue<T>(*entry);
}

template<typename T>
inline
T* ParameterList::getPtr(const string& name) 
{
  ConstIterator i = params_.find(name);
  if ( i == params_.end() || entry(i).getAny().type() != typeid(T) )
    return NULL;
  return &getValue<T>(entry(i));
}
  
template<typename T>
inline
const T* ParameterList::getPtr(const string& name) const
{
  ConstIterator i = params_.find(name);
  if ( i == params_.end() || entry(i).getAny().type() != typeid(T) )
    return NULL;
  return &getValue<T>(entry(i));
}

inline
ParameterEntry*
ParameterList::getEntryPtr(const string& name)
{
  Map::iterator i = params_.find(name);
  if ( i == params_.end() )
    return NULL;
  return &entry(i);
}

inline
const ParameterEntry*
ParameterList::getEntryPtr(const string& name) const
{
  ConstIterator i = params_.find(name);
  if ( i == params_.end() )
    return NULL;
  return &entry(i);
}

// Attribute Functions

inline
const std::string& ParameterList::name() const
{
  return name_;
}
  
#ifndef DOXYGEN_SHOULD_SKIP_THIS
template<typename T>
bool ParameterList::isType(const string& name, T* ptr) const
{
  ConstIterator i = params_.find(name);
  // If parameter doesn't exist, return false.
  if (i == params_.end()) 
    return false;
  return entry(i).getAny().type() == typeid(T);
}
#endif
  
template<typename T>
bool ParameterList::isType(const string& name) const
{
  ConstIterator i = params_.find(name);
  // If parameter doesn't exist, return false.
  if (i == params_.end()) 
    return false;
  return entry(i).getAny().type() == typeid(T);
}

// private

inline
void ParameterList::validateEntryExists( const std::string &funcName, const std::string &name, const ParameterEntry *entry ) const
{
  TEST_FOR_EXCEPTION(
    entry==NULL, Exceptions::InvalidParameter,
    funcName<<"(...): Error!  The parameter \""<<name<<"\" does not exist in the parameter (sub)list \""<<this->name()<<"\"."
    "  The current parameters set in (sub)list \""<<this->name()<<"\" are " << this->currentParametersString() << "!"
    );
}

template<typename T>
void ParameterList::validateEntryType( const std::string &funcName, const std::string &name, const ParameterEntry &entry ) const
{
  TEST_FOR_EXCEPTION(
    entry.getAny().type() != typeid(T), Exceptions::InvalidParameter,
    funcName<<"(...): Error!  An attempt was made to access parameter \""<<name<<"\""
    " of type \""<<entry.getAny().type().name()<<"\" in the parameter (sub)list \""<<this->name()<<"\""
    " using the incorrect type \""<<typeid(T).name()<<"\"!"
    );
}

// //////////////////////////////////////
// Helper functions
  
template<typename T>
T& getParameter( ParameterList& l, const string& name )
{
  return l.template get<T>(name);
}
  
template<typename T>
const T& getParameter( const ParameterList& l, const string& name )
{
  return l.template get<T>(name);
}
  
template<typename T>
bool isParameterType( ParameterList& l, const string& name )
{
  return l.isType( name, (T*)NULL );
}
  
template<typename T>
bool isParameterType( const ParameterList& l, const string& name )
{
  return l.isType( name, (T*)NULL );
}

inline
RefCountPtr<ParameterList> sublist(
  const RefCountPtr<ParameterList> &paramList, const string& name, bool mustAlreadyExist = false
  )
{
  RefCountPtr<ParameterList>
    sublist = Teuchos::rcp(&paramList->sublist(name,mustAlreadyExist),false);
  set_extra_data(paramList,"masterParamList",&sublist);
  return sublist;
}
  
inline ostream& operator<<(ostream& os, const ParameterList& l)
{
  return l.print(os);
}
  
} // end of Teuchos namespace

#endif

---