Teuchos_ParameterList.hpp

Go to the documentation of this file.
00001 // @HEADER
00002 // ***********************************************************************
00003 // 
00004 //                    Teuchos: Common Tools Package
00005 //                 Copyright (2004) Sandia Corporation
00006 // 
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 // 
00010 // This library is free software; you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as
00012 // published by the Free Software Foundation; either version 2.1 of the
00013 // License, or (at your option) any later version.
00014 //  
00015 // This library is distributed in the hope that it will be useful, but
00016 // WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00018 // Lesser General Public License for more details.
00019 //  
00020 // You should have received a copy of the GNU Lesser General Public
00021 // License along with this library; if not, write to the Free Software
00022 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00023 // USA
00024 // Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
00025 // 
00026 // ***********************************************************************
00027 // @HEADER
00028 
00029 
00030 #ifndef TEUCHOS_PARAMETER_LIST_H
00031 #define TEUCHOS_PARAMETER_LIST_H
00032 
00037 #include "Teuchos_ParameterEntry.hpp" // class data element 
00038 #include "Teuchos_TestForException.hpp"
00039 #include "Teuchos_RefCountPtr.hpp"
00040 #include "Teuchos_ConfigDefs.hpp"
00041 #include "Teuchos_map.hpp"
00042 
00047 namespace Teuchos {
00048 
00052 enum EValidateUsed {
00053   VALIDATE_USED_ENABLED   /*< \brief Validate that parameters in <tt>*this</tt> list
00054                               set using the default value are present in
00055                               the validation list */
00056   ,VALIDATE_USED_DISABLED /*< \brief Do not validate that parameters in <tt>*this</tt> list
00057                               set using the default value are present in
00058                               the validation list */
00059 };
00060 
00064 enum EValidateDefaults {
00065   VALIDATE_DEFAULTS_ENABLED   /*< \brief Validate that parameters in <tt>*this</tt> list
00066                                   set using the default value are present in
00067                                    the validation list */
00068   ,VALIDATE_DEFAULTS_DISABLED /*< \brief Do not validate that parameters in <tt>*this</tt> list
00069                                   set using the default value are present in
00070                                   the validation list */
00071 };
00072 
00073 namespace Exceptions {
00074 
00078 class InvalidParameter : public std::logic_error
00079 {public: InvalidParameter(const std::string& what_arg) : std::logic_error(what_arg) {}};
00080 
00081 } // namespace Exceptions
00082 
00096 class ParameterList {
00097 
00099   typedef Teuchos::map<string, ParameterEntry> Map;
00100 
00102   typedef Map::iterator Iterator;
00103   
00104 public:
00105 
00107 
00108 
00110   typedef Map::const_iterator ConstIterator;
00111 
00113   
00115 
00116 
00118   ParameterList();
00119 
00121   ParameterList(const std::string &name);
00122   
00124   ParameterList(const ParameterList& source);
00125   
00127   virtual ~ParameterList();
00128 
00130   
00132 
00133 
00136   void setName( const std::string &name );
00137   
00141   ParameterList& operator=(const ParameterList& source);
00142   
00150   ParameterList& setParameters(const ParameterList& source);
00151   
00160   template<typename T>
00161   void set(const string& name, T value);
00162 
00166   void set(const string& name, char value[]);
00167 
00171   void set(const string& name, const char value[]);
00172 
00175   void set(const string& name, ParameterList value);
00176 
00181   void setEntry(const string& name, const ParameterEntry& entry);
00182 
00184   
00186 
00187   
00198   template<typename T>
00199   T& get(const string& name, T def_value);
00200 
00204   std::string& get(const string& name, char def_value[]);
00205   
00209   std::string& get(const string& name, const char def_value[]);
00210   
00216   template<typename T>
00217   T& get(const string& name);
00218   
00224   template<typename T>
00225   const T& get(const string& name) const;  
00226   
00232   template<typename T>
00233   T* getPtr(const string& name);
00234   
00240   template<typename T>
00241   const T* getPtr(const string& name) const;  
00242   
00245   ParameterEntry* getEntryPtr(const string& name);  
00246   
00249   const ParameterEntry* getEntryPtr(const string& name) const;  
00250 
00252   
00254 
00255 
00261   ParameterList& sublist(const string& name, bool mustAlreadyExist = false);
00262   
00267   const ParameterList& sublist(const string& name) const;
00268 
00270   
00272 
00273 
00275   const std::string& name() const;
00276 
00280   bool isParameter(const string& name) const;
00281   
00286   bool isSublist(const string& name) const;
00287   
00293   template<typename T>
00294   bool isType(const string& name) const;
00295 
00296 #ifndef DOXYGEN_SHOULD_SKIP_THIS  
00297 
00302   template<typename T>
00303   bool isType(const string& name, T* ptr) const;
00304 #endif
00305 
00307   
00309 
00310 
00313   ostream& print(ostream& os, int indent = 0, bool showTypes = false, bool showFlags = true ) const;
00314   
00316   void unused(ostream& os) const;
00317 
00319   std::string currentParametersString() const;
00320 
00322 
00324 
00325 
00327   ConstIterator begin() const ;
00328 
00330   ConstIterator end() const ;
00331 
00333   const ParameterEntry& entry(ConstIterator i) const;
00334   
00336   const string& name(ConstIterator i) const;
00337 
00339 
00341 
00342 
00370   void validateParameters(
00371     const ParameterList        &validParamList
00372     ,const int                 depth            = 1000
00373     ,const EValidateUsed       validateUsed     = VALIDATE_USED_ENABLED
00374     ,const EValidateDefaults   validateDefaults = VALIDATE_DEFAULTS_ENABLED
00375     ) const;
00376 
00378   
00379 private: // Functions
00380   
00382   ParameterEntry& entry(Iterator i);
00384   void validateEntryExists( const std::string &funcName, const std::string &name, const ParameterEntry *entry ) const;
00386   template<typename T>
00387   void validateEntryType( const std::string &funcName, const std::string &name, const ParameterEntry &entry ) const;
00389   void updateSubListNames(int depth = 0);
00390   
00391 private: // Data members
00392 
00394   std::string name_;
00396   Map params_;
00397 };
00398 
00403 template<>
00404 class TypeNameTraits<ParameterList> {
00405 public:
00406   static std::string name() { return "ParameterList"; }
00407 };
00408 
00413 bool operator==( const ParameterList& list1, const ParameterList& list2 );
00414 
00419 inline
00420 bool operator!=( const ParameterList& list1, const ParameterList& list2 )
00421 {
00422   return !( list1 == list2 );
00423 }
00424 
00425 // /////////////////////////////////////////////////////
00426 // Inline and Template Function Definitions
00427 
00428 inline
00429 void ParameterList::setName( const std::string &name )
00430 {
00431   name_ = name;
00432 }
00433 
00434 // Set functions
00435  
00436 template<typename T>
00437 inline
00438 void ParameterList::set(const string& name, T value)
00439 {
00440   params_[name].setValue(value);
00441 }
00442 
00443 inline
00444 void ParameterList::set(const string& name, char value[]) 
00445 { set( name, std::string(value) ); }
00446 
00447 inline
00448 void ParameterList::set(const string& name, const char value[]) 
00449 { set( name, std::string(value) ); }
00450 
00451 inline
00452 void ParameterList::set(const string& name, ParameterList value)
00453 { sublist(name) = value; }
00454 
00455 inline
00456 void ParameterList::setEntry(const string& name, const ParameterEntry& entry)
00457 {params_[name] = entry;}
00458 
00459 // Get functions
00460 
00461 template<typename T>
00462 T& ParameterList::get(const string& name, T def_value)
00463 {
00464   ConstIterator i = params_.find(name);
00465     
00466   // The parameter was not found, add it to the list
00467   if (i == params_.end()) {
00468     params_[name].setValue(def_value, true);
00469     i = params_.find(name);
00470   } else {
00471     // The parameter was found, make sure it is the same type as T.
00472     this->template validateEntryType<T>("get",name,entry(i));
00473   }
00474 
00475   // Return the value of the parameter
00476   return getValue<T>(entry(i));
00477 }
00478 
00479 inline
00480 std::string& ParameterList::get(const string& name, char def_value[])
00481 { return get(name, std::string(def_value)); }
00482 
00483 inline
00484 std::string& ParameterList::get(const string& name, const char def_value[])
00485 { return get(name, std::string(def_value)); }
00486 
00487 template<typename T>
00488 T& ParameterList::get(const string& name) 
00489 {
00490   ParameterEntry *entry = this->getEntryPtr(name);
00491   validateEntryExists("get",name,entry);
00492   this->template validateEntryType<T>("get",name,*entry);
00493   return getValue<T>(*entry);
00494 }
00495   
00496 template<typename T>
00497 const T& ParameterList::get(const string& name) const
00498 {
00499   const ParameterEntry *entry = this->getEntryPtr(name);
00500   validateEntryExists("get",name,entry);
00501   this->template validateEntryType<T>("get",name,*entry);
00502   return getValue<T>(*entry);
00503 }
00504 
00505 template<typename T>
00506 inline
00507 T* ParameterList::getPtr(const string& name) 
00508 {
00509   ConstIterator i = params_.find(name);
00510   if ( i == params_.end() || entry(i).getAny().type() != typeid(T) )
00511     return NULL;
00512   return &getValue<T>(entry(i));
00513 }
00514   
00515 template<typename T>
00516 inline
00517 const T* ParameterList::getPtr(const string& name) const
00518 {
00519   ConstIterator i = params_.find(name);
00520   if ( i == params_.end() || entry(i).getAny().type() != typeid(T) )
00521     return NULL;
00522   return &getValue<T>(entry(i));
00523 }
00524 
00525 inline
00526 ParameterEntry*
00527 ParameterList::getEntryPtr(const string& name)
00528 {
00529   Map::iterator i = params_.find(name);
00530   if ( i == params_.end() )
00531     return NULL;
00532   return &entry(i);
00533 }
00534 
00535 inline
00536 const ParameterEntry*
00537 ParameterList::getEntryPtr(const string& name) const
00538 {
00539   ConstIterator i = params_.find(name);
00540   if ( i == params_.end() )
00541     return NULL;
00542   return &entry(i);
00543 }
00544 
00545 // Attribute Functions
00546 
00547 inline
00548 const std::string& ParameterList::name() const
00549 {
00550   return name_;
00551 }
00552   
00553 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00554 template<typename T>
00555 bool ParameterList::isType(const string& name, T* ptr) const
00556 {
00557   ConstIterator i = params_.find(name);
00558   // If parameter doesn't exist, return false.
00559   if (i == params_.end()) 
00560     return false;
00561   return entry(i).getAny().type() == typeid(T);
00562 }
00563 #endif
00564   
00565 template<typename T>
00566 bool ParameterList::isType(const string& name) const
00567 {
00568   ConstIterator i = params_.find(name);
00569   // If parameter doesn't exist, return false.
00570   if (i == params_.end()) 
00571     return false;
00572   return entry(i).getAny().type() == typeid(T);
00573 }
00574 
00575 // private
00576 
00577 inline
00578 void ParameterList::validateEntryExists( const std::string &funcName, const std::string &name, const ParameterEntry *entry ) const
00579 {
00580   TEST_FOR_EXCEPTION(
00581     entry==NULL, Exceptions::InvalidParameter,
00582     funcName<<"(...): Error!  The parameter \""<<name<<"\" does not exist in the parameter (sub)list \""<<this->name()<<"\"."
00583     "  The current parameters set in (sub)list \""<<this->name()<<"\" are " << this->currentParametersString() << "!"
00584     );
00585 }
00586 
00587 template<typename T>
00588 void ParameterList::validateEntryType( const std::string &funcName, const std::string &name, const ParameterEntry &entry ) const
00589 {
00590   TEST_FOR_EXCEPTION(
00591     entry.getAny().type() != typeid(T), Exceptions::InvalidParameter,
00592     funcName<<"(...): Error!  An attempt was made to access parameter \""<<name<<"\""
00593     " of type \""<<entry.getAny().type().name()<<"\" in the parameter (sub)list \""<<this->name()<<"\""
00594     " using the incorrect type \""<<typeid(T).name()<<"\"!"
00595     );
00596 }
00597 
00598 // //////////////////////////////////////
00599 // Helper functions
00600   
00607 template<typename T>
00608 T& getParameter( ParameterList& l, const string& name )
00609 {
00610   return l.template get<T>(name);
00611 }
00612   
00619 template<typename T>
00620 const T& getParameter( const ParameterList& l, const string& name )
00621 {
00622   return l.template get<T>(name);
00623 }
00624   
00631 template<typename T>
00632 bool isParameterType( ParameterList& l, const string& name )
00633 {
00634   return l.isType( name, (T*)NULL );
00635 }
00636   
00643 template<typename T>
00644 bool isParameterType( const ParameterList& l, const string& name )
00645 {
00646   return l.isType( name, (T*)NULL );
00647 }
00648 
00652 inline
00653 RefCountPtr<ParameterList> sublist(
00654   const RefCountPtr<ParameterList> &paramList, const string& name, bool mustAlreadyExist = false
00655   )
00656 {
00657   RefCountPtr<ParameterList>
00658     sublist = Teuchos::rcp(&paramList->sublist(name,mustAlreadyExist),false);
00659   set_extra_data(paramList,"masterParamList",&sublist);
00660   return sublist;
00661 }
00662   
00666 inline ostream& operator<<(ostream& os, const ParameterList& l)
00667 {
00668   return l.print(os);
00669 }
00670   
00671 } // end of Teuchos namespace
00672 
00673 #endif
00674 
00675 

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