Teuchos - Trilinos Tools Package Version of the Day
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 // Redistribution and use in source and binary forms, with or without
00011 // modification, are permitted provided that the following conditions are
00012 // met:
00013 //
00014 // 1. Redistributions of source code must retain the above copyright
00015 // notice, this list of conditions and the following disclaimer.
00016 //
00017 // 2. Redistributions in binary form must reproduce the above copyright
00018 // notice, this list of conditions and the following disclaimer in the
00019 // documentation and/or other materials provided with the distribution.
00020 //
00021 // 3. Neither the name of the Corporation nor the names of the
00022 // contributors may be used to endorse or promote products derived from
00023 // this software without specific prior written permission.
00024 //
00025 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
00026 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00027 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00028 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
00029 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00030 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00031 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00032 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00033 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00034 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00035 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00036 //
00037 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
00038 //
00039 // ***********************************************************************
00040 // @HEADER
00041 
00042 
00043 #ifndef TEUCHOS_PARAMETER_LIST_H
00044 #define TEUCHOS_PARAMETER_LIST_H
00045 
00050 #include "Teuchos_ParameterListExceptions.hpp"
00051 #include "Teuchos_ParameterEntry.hpp"
00052 #include "Teuchos_StringIndexedOrderedValueObjectContainer.hpp"
00053 #include "Teuchos_Assert.hpp"
00054 #include "Teuchos_RCP.hpp"
00055 #include "Teuchos_Array.hpp"
00056 #include "Teuchos_map.hpp"
00057 
00058 
00063 namespace Teuchos {
00064 
00068 enum EValidateUsed {
00069   VALIDATE_USED_ENABLED   /*< \brief Validate that parameters in <tt>*this</tt> list
00070                               set using the default value are present in
00071                               the validation list */
00072   ,VALIDATE_USED_DISABLED /*< \brief Do not validate that parameters in <tt>*this</tt> list
00073                               set using the default value are present in
00074                               the validation list */
00075 };
00076 
00080 enum EValidateDefaults {
00081   VALIDATE_DEFAULTS_ENABLED   /*< \brief Validate that parameters in <tt>*this</tt> list
00082                                   set using the default value are present in
00083                                    the validation list */
00084   ,VALIDATE_DEFAULTS_DISABLED /*< \brief Do not validate that parameters in <tt>*this</tt> list
00085                                   set using the default value are present in
00086                                   the validation list */
00087 };
00088 
00102 class TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT ParameterList {
00103 
00105   typedef StringIndexedOrderedValueObjectContainer<ParameterEntry> params_t;
00106 
00108   typedef params_t::Iterator Iterator;
00109   
00110 public:
00111 
00113 
00114 
00116   typedef params_t::ConstIterator ConstIterator;
00117 
00119   class PrintOptions {
00120   public:
00121     PrintOptions() : indent_(0), showTypes_(false), showFlags_(false), showDoc_(false) {}
00122     PrintOptions& indent(int _indent)        { indent_ = _indent; return *this; }
00123     PrintOptions& showTypes(bool _showTypes) { showTypes_ = _showTypes; return *this; }
00124     PrintOptions& showFlags(bool _showFlags) { showFlags_ = _showFlags; return *this; }
00125     PrintOptions& showDoc(bool _showDoc)     { showDoc_ = _showDoc; return *this; }
00126     PrintOptions& incrIndent(int indents)    { indent_ += indents; return *this; }
00127     int indent() const { return indent_; }
00128     bool showTypes() const { return showTypes_; }
00129     bool showFlags() const { return showFlags_; }
00130     bool showDoc() const { return showDoc_; }
00131     PrintOptions copy() const { return PrintOptions(*this); }
00132   private:
00133     int    indent_;
00134     bool   showTypes_;
00135     bool   showFlags_;
00136     bool   showDoc_;
00137   };
00138 
00140   
00142 
00143 
00145   ParameterList();
00146 
00148   ParameterList(const std::string &name);
00149   
00151   ParameterList(const ParameterList& source);
00152   
00154   virtual ~ParameterList();
00155 
00157   Ordinal numParams() const;
00158 
00160   
00162 
00163 
00166   ParameterList& setName( const std::string &name );
00167   
00171   ParameterList& operator=(const ParameterList& source);
00172   
00180   ParameterList& setParameters(const ParameterList& source);
00181   
00191   ParameterList& setParametersNotAlreadySet(const ParameterList& source);
00192 
00200   ParameterList& disableRecursiveValidation();
00201   
00210   template<typename T>
00211   ParameterList& set(
00212     std::string const& name, T const& value, std::string const& docString = "",
00213     RCP<const ParameterEntryValidator> const& validator = null
00214     );
00215 
00219   ParameterList& set(
00220     std::string const& name, char value[], std::string const& docString = "",
00221     RCP<const ParameterEntryValidator> const& validator = null
00222     );
00223 
00227   ParameterList& set(
00228     std::string const& name, const char value[], std::string const& docString = "",
00229     RCP<const ParameterEntryValidator> const& validator = null
00230     );
00231 
00234   ParameterList& set(
00235     std::string const& name, ParameterList const& value, std::string const& docString = ""
00236     );
00237 
00242   ParameterList& setEntry(const std::string& name, const ParameterEntry& entry);
00243 
00245   
00247 
00248   
00259   template<typename T>
00260   T& get(const std::string& name, T def_value);
00261 
00265   std::string& get(const std::string& name, char def_value[]);
00266   
00270   std::string& get(const std::string& name, const char def_value[]);
00271   
00279   template<typename T>
00280   T& get(const std::string& name);
00281   
00289   template<typename T>
00290   const T& get(const std::string& name) const;  
00291   
00297   template<typename T>
00298   inline
00299   T* getPtr(const std::string& name);
00300   
00306   template<typename T>
00307   inline
00308   const T* getPtr(const std::string& name) const;  
00309 
00310   // ToDo: Add getSafePtr() functions to return Ptr<T> instead of raw T*
00311   
00317   ParameterEntry& getEntry(const std::string& name);  
00318   
00324   inline
00325   const ParameterEntry& getEntry(const std::string& name) const;  
00326   
00329   inline
00330   ParameterEntry* getEntryPtr(const std::string& name);  
00331 
00332   // ToDo: Add function called getEntrySafePtr() to return Ptr<> as the main
00333   // implementation and deprecate getEntryPtr()
00334   
00337   inline
00338   const ParameterEntry* getEntryPtr(const std::string& name) const;  
00339 
00342   inline RCP<ParameterEntry> getEntryRCP(const std::string& name);  
00343   
00346   inline RCP<const ParameterEntry> getEntryRCP(const std::string& name) const;
00347 
00349 
00351 
00352  
00366   bool remove(
00367     std::string const& name, bool throwIfNotExists = true
00368     );
00369 
00371   
00373 
00374 
00380   ParameterList& sublist(
00381     const std::string& name, bool mustAlreadyExist = false
00382     ,const std::string& docString = ""
00383     );
00384   
00389   const ParameterList& sublist(const std::string& name) const;
00390 
00392   
00394 
00395 
00397   const std::string& name() const;
00398 
00405   bool isParameter(const std::string& name) const;
00406   
00412   bool isSublist(const std::string& name) const;
00413   
00420   template<typename T>
00421   bool isType(const std::string& name) const;
00422 
00423 #ifndef DOXYGEN_SHOULD_SKIP_THIS  
00424 
00434   template<typename T>
00435   bool isType(const std::string& name, T* ptr) const;
00436 #endif
00437 
00439   
00441 
00442 
00448   void print() const;
00449 
00452   std::ostream& print(std::ostream& os, const PrintOptions &printOptions) const;
00453 
00456   std::ostream& print(std::ostream& os, int indent = 0, bool showTypes = false, bool showFlags = true ) const;
00457   
00459   void unused(std::ostream& os) const;
00460 
00462   std::string currentParametersString() const;
00463 
00465 
00467 
00468 
00470   inline ConstIterator begin() const;
00471 
00473   inline ConstIterator end() const;
00474   
00476   inline const std::string& name(ConstIterator i) const;
00477 
00479   inline const ParameterEntry& entry(ConstIterator i) const;
00480 
00482 
00484 
00485 
00530   void validateParameters(
00531     ParameterList const& validParamList,
00532     int const depth = 1000,
00533     EValidateUsed const validateUsed = VALIDATE_USED_ENABLED,
00534     EValidateDefaults const validateDefaults = VALIDATE_DEFAULTS_ENABLED
00535     ) const;
00536 
00574   void validateParametersAndSetDefaults(
00575     ParameterList const& validParamList,
00576     int const depth = 1000
00577     );
00578 
00580   
00581 private: // Functions
00582 
00584   inline Iterator nonconstBegin();
00586   inline Iterator nonconstEnd();
00588   inline ParameterEntry& nonconstEntry(Iterator i);
00590   void validateEntryExists(const std::string &funcName, const std::string &name,
00591     const ParameterEntry *entry) const;
00592   // ToDo: Change above function to take Ptr<> instead of raw pointer.
00594   template<typename T>
00595   void validateEntryType(const std::string &funcName, const std::string &name,
00596     const ParameterEntry &entry ) const;
00598   void validateEntryIsList(const std::string &name, const ParameterEntry &entry) const;
00600   void validateMissingSublistMustExist(const std::string &baselist_name,
00601     const std::string &sublist_name, const bool mustAlreadyExist) const;
00603   void updateSubListNames(int depth = 0);
00604   
00605 private: // Data members
00606 
00608   std::string name_;
00609 
00611 //use pragmas to disable some false-positive warnings for windows sharedlibs export
00612 //#ifdef _MSC_VER
00613 //#pragma warning(push)
00614 //#pragma warning(disable:4251)
00615 //#endif
00616   params_t params_;
00617 //#ifdef _MSC_VER
00618 //#pragma warning(pop)
00619 //#endif
00620 
00622   bool disableRecursiveValidation_;
00623 
00624 };
00625 
00626 
00631 inline
00632 RCP<ParameterList> parameterList()
00633 {
00634   return rcp(new ParameterList);
00635 }
00636 
00637 
00642 inline
00643 RCP<ParameterList> parameterList(const std::string &name)
00644 {
00645   return rcp(new ParameterList(name));
00646 }
00647   
00648 
00653 inline
00654 RCP<ParameterList> parameterList(const ParameterList& source)
00655 {
00656   return rcp(new ParameterList(source));
00657 }
00658 
00659 
00664 inline
00665 RCP<ParameterList> createParameterList()
00666 {
00667   return rcp(new ParameterList);
00668 }
00669 
00670 
00675 inline
00676 RCP<ParameterList> createParameterList(const std::string &name)
00677 {
00678   return rcp(new ParameterList(name));
00679 }
00680 
00681 
00686 template<>
00687 class TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT TypeNameTraits<ParameterList> {
00688 public:
00689   static std::string name() { return "ParameterList"; }
00690   static std::string concreteName( const ParameterList& /*t2*/ )
00691     { return name(); }
00692 };
00693 
00694 
00699 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool operator==( const ParameterList& list1, const ParameterList& list2 );
00700 
00701 
00706 inline
00707 bool operator!=( const ParameterList& list1, const ParameterList& list2 )
00708 {
00709   return !( list1 == list2 );
00710 }
00711 
00712 
00724 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValues( const ParameterList& list1, const ParameterList& list2 );
00725 
00726 
00727 // /////////////////////////////////////////////////////
00728 // Inline and Template Function Definitions
00729 
00730 
00731 inline
00732 ParameterList& ParameterList::setName( const std::string &name_in )
00733 {
00734   name_ = name_in;
00735   return *this;
00736 }
00737 
00738 
00739 // Set functions
00740 
00741 
00742 template<typename T>
00743 inline
00744 ParameterList& ParameterList::set(
00745   std::string const& name_in, T const& value_in, std::string const& docString_in,
00746   RCP<const ParameterEntryValidator> const& validator_in
00747   )
00748 {
00749   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00750   const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
00751   if (param_idx != SIOVOCB::getInvalidOrdinal()) {
00752     Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
00753     const std::string docString =
00754       (docString_in.length() ? docString_in : param->docString());
00755     const RCP<const ParameterEntryValidator> validator =
00756       (nonnull(validator_in) ? validator_in : param->validator());
00757      // Create temp param to validate before setting
00758     ParameterEntry param_new(value_in, false, false, docString, validator );
00759     if (nonnull(validator)) {
00760       validator->validate(param_new, name_in, this->name());
00761     }
00762     // Strong guarantee: (if exception is thrown, the value is not changed)
00763     *param = param_new;
00764   }
00765   else {
00766     ParameterEntry param_new(value_in, false, false, docString_in, validator_in);
00767     if (nonnull(param_new.validator())) {
00768       param_new.validator()->validate(param_new, name_in, this->name());
00769     }
00770     params_.setObj(name_in, param_new);
00771   }
00772   return *this;
00773 }
00774 
00775 
00776 inline
00777 ParameterList& ParameterList::set(
00778   std::string const& name_in, char value[], std::string const& docString
00779   ,RCP<const ParameterEntryValidator> const& validator
00780   ) 
00781 { return set(name_in, std::string(value), docString, validator); }
00782 
00783 
00784 inline
00785 ParameterList& ParameterList::set(
00786   const std::string& name_in, const char value[], const std::string &docString
00787   ,RCP<const ParameterEntryValidator> const& validator
00788   ) 
00789 { return set( name_in, std::string(value), docString, validator ); }
00790 
00791 
00792 inline
00793 ParameterList& ParameterList::set(
00794   std::string const& name_in, ParameterList const& value, std::string const& /*docString*/
00795   )
00796 {
00797   sublist(name_in) = value;
00798   return *this;
00799 }
00800 
00801 
00802 inline
00803 ParameterList& ParameterList::setEntry(std::string const& name_in, ParameterEntry const& entry_in)
00804 {
00805   params_.setObj(name_in, entry_in);
00806   return *this;
00807 }
00808 
00809 
00810 // Get functions
00811 
00812 
00813 template<typename T>
00814 T& ParameterList::get(const std::string& name_in, T def_value)
00815 {
00816   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00817   Ordinal param_idx = params_.getObjOrdinalIndex(name_in); 
00818   if (param_idx == SIOVOCB::getInvalidOrdinal()) {
00819     // Param does not exist
00820     param_idx = params_.setObj(name_in, ParameterEntry(def_value, true));
00821   }
00822   Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
00823   this->template validateEntryType<T>("get", name_in, *param);
00824   return getValue<T>(*param);
00825 }
00826 
00827 
00828 inline
00829 std::string& ParameterList::get(const std::string& name_in, char def_value[])
00830 { return get(name_in, std::string(def_value)); }
00831 
00832 
00833 inline
00834 std::string& ParameterList::get(const std::string& name_in, const char def_value[])
00835 { return get(name_in, std::string(def_value)); }
00836 
00837 
00838 template<typename T>
00839 T& ParameterList::get(const std::string& name_in) 
00840 {
00841   ParameterEntry *foundEntry = this->getEntryPtr(name_in);
00842   validateEntryExists("get",name_in,foundEntry);
00843   this->template validateEntryType<T>("get",name_in,*foundEntry);
00844   return getValue<T>(*foundEntry);
00845 }
00846 
00847   
00848 template<typename T>
00849 const T& ParameterList::get(const std::string& name_in) const
00850 {
00851   const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
00852   validateEntryExists("get",name_in,foundEntry);
00853   this->template validateEntryType<T>("get",name_in,*foundEntry);
00854   return getValue<T>(*foundEntry);
00855 }
00856 
00857 
00858 template<typename T>
00859 inline
00860 T* ParameterList::getPtr(const std::string& name_in) 
00861 {
00862   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00863   const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
00864   if (param_idx != SIOVOCB::getInvalidOrdinal()) {
00865     const Ptr<ParameterEntry> param_ptr = params_.getNonconstObjPtr(param_idx);
00866     if (param_ptr->isType<T>()) {
00867       return &param_ptr->getValue<T>(0);
00868     }
00869     // Note: The above is inefficinet.  You have to do the dynamic_cast twice
00870     // (once to see if it is the type and once to do the cast).  This could be
00871     // made more efficinet by upgrading Teuchos::any to add a any_cast_ptr()
00872     // function but I don't think anyone actually uses this function.
00873     return 0;
00874   }
00875   return 0;
00876 }
00877 
00878   
00879 template<typename T>
00880 inline
00881 const T* ParameterList::getPtr(const std::string& name_in) const
00882 {
00883   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00884   const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
00885   if (param_idx != SIOVOCB::getInvalidOrdinal()) {
00886     const Ptr<const ParameterEntry> param_ptr = params_.getObjPtr(param_idx);
00887     if (param_ptr->isType<T>()) {
00888       return &param_ptr->getValue<T>(0);
00889     }
00890     // Note: The above is inefficinet, see above non-const getPtr() function.
00891     return 0;
00892   }
00893   return 0;
00894 }
00895 
00896 
00897 inline
00898 ParameterEntry& ParameterList::getEntry(const std::string& name_in)
00899 {
00900   ParameterEntry *foundEntry = this->getEntryPtr(name_in);
00901   validateEntryExists("get", name_in, foundEntry);
00902   return *foundEntry;
00903 }
00904 
00905   
00906 inline
00907 const ParameterEntry& ParameterList::getEntry(const std::string& name_in) const
00908 {
00909   const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
00910   validateEntryExists("get", name_in, foundEntry);
00911   return *foundEntry;
00912 }
00913 
00914 
00915 inline
00916 ParameterEntry*
00917 ParameterList::getEntryPtr(const std::string& name_in)
00918 {
00919   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00920   const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
00921   if (param_idx != SIOVOCB::getInvalidOrdinal()) {
00922     return &*params_.getNonconstObjPtr(param_idx);
00923   }
00924   return 0;
00925 }
00926 
00927 
00928 inline
00929 const ParameterEntry*
00930 ParameterList::getEntryPtr(const std::string& name_in) const
00931 {
00932   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00933   const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
00934   if (param_idx != SIOVOCB::getInvalidOrdinal()) {
00935     return &*params_.getObjPtr(param_idx);
00936   }
00937   return 0;
00938 }
00939 
00940 
00941 inline RCP<ParameterEntry>
00942 ParameterList::getEntryRCP(const std::string& name_in)
00943 {
00944   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00945   const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
00946   if (param_idx != SIOVOCB::getInvalidOrdinal()) {
00947     return rcpFromPtr(params_.getNonconstObjPtr(param_idx));
00948   }
00949   return null;
00950 }
00951 
00952 
00953 inline RCP<const ParameterEntry>
00954 ParameterList::getEntryRCP(const std::string& name_in) const
00955 {
00956   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00957   const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
00958   if (param_idx != SIOVOCB::getInvalidOrdinal()) {
00959     return rcpFromPtr(params_.getObjPtr(param_idx));
00960   }
00961   return null;
00962 }
00963 
00964 
00965 // Attribute Functions
00966 
00967 
00968 inline
00969 const std::string& ParameterList::name() const
00970 {
00971   return name_;
00972 }
00973 
00974   
00975 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00976 template<typename T>
00977 bool ParameterList::isType(const std::string& name_in, T* /*ptr*/) const
00978 {
00979   typedef StringIndexedOrderedValueObjectContainerBase SIOVOCB;
00980   const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
00981   if (param_idx != SIOVOCB::getInvalidOrdinal()) {
00982     return params_.getObjPtr(param_idx)->isType<T>();
00983   }
00984   return false;
00985 }
00986 #endif
00987 
00988   
00989 template<typename T>
00990 bool ParameterList::isType(const std::string& name_in) const
00991 {
00992   return this->isType(name_in, static_cast<T*>(0));
00993 }
00994 
00995 
00996 // Read-only access to the iterator
00997 
00998 
00999 inline ParameterList::ConstIterator ParameterList::begin() const
01000 {
01001   return params_.begin();
01002 }
01003 
01004 
01005 inline ParameterList::ConstIterator ParameterList::end() const
01006 {
01007   return params_.end();
01008 }
01009 
01010 
01011 inline const std::string& ParameterList::name(ConstIterator i) const
01012 {
01013   return (i->first);
01014 }
01015 
01016 
01017 inline const ParameterEntry& ParameterList::entry(ConstIterator i) const
01018 {
01019   return (i->second);
01020 }
01021 
01022 
01023 // private
01024 
01025 
01026 inline ParameterList::Iterator ParameterList::nonconstBegin()
01027 {
01028   return params_.nonconstBegin();
01029 }
01030 
01031 
01032 inline ParameterList::Iterator ParameterList::nonconstEnd()
01033 {
01034   return params_.nonconstEnd();
01035 }
01036 
01037 
01038 inline ParameterEntry& ParameterList::nonconstEntry(Iterator i)
01039 {
01040   return (i->second);
01041 }
01042 
01043 
01044 template<typename T>
01045 inline
01046 void ParameterList::validateEntryType(
01047   const std::string &/*funcName*/, const std::string &name_in,
01048   const ParameterEntry &entry_in
01049   ) const
01050 {
01051   TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
01052     entry_in.getAny().type() != typeid(T), Exceptions::InvalidParameterType
01053     ,"Error!  An attempt was made to access parameter \""<<name_in<<"\""
01054     " of type \""<<entry_in.getAny().typeName()<<"\""
01055     "\nin the parameter (sub)list \""<<this->name()<<"\""
01056     "\nusing the incorrect type \""<<TypeNameTraits<T>::name()<<"\"!"
01057     );
01058 }
01059 
01060 
01061 // //////////////////////////////////////
01062 // Helper functions
01063 
01064   
01071 template<typename T>
01072 T& getParameter( ParameterList& l, const std::string& name )
01073 {
01074   return l.template get<T>(name);
01075 }
01076 
01077   
01083 template<typename T>
01084 inline
01085 T& get( ParameterList& l, const std::string& name )
01086 {
01087   return getParameter<T>(l,name);
01088 }
01089 
01090   
01097 template<typename T>
01098 const T& getParameter( const ParameterList& l, const std::string& name )
01099 {
01100   return l.template get<T>(name);
01101 }
01102 
01103   
01111 template<typename T>
01112 inline
01113 T* getParameterPtr( ParameterList& l, const std::string& name )
01114 {
01115   return l.template getPtr<T>(name);
01116 }
01117 
01118   
01126 template<typename T>
01127 inline
01128 const T* getParameterPtr( const ParameterList& l, const std::string& name )
01129 {
01130   return l.template getPtr<T>(name);
01131 }
01132 
01133   
01140 template<typename T>
01141 inline
01142 bool isParameterType( ParameterList& l, const std::string& name )
01143 {
01144   return l.isType( name, (T*)NULL );
01145 }
01146 
01147   
01154 template<typename T>
01155 inline
01156 bool isParameterType( const ParameterList& l, const std::string& name )
01157 {
01158   return l.isType( name, (T*)NULL );
01159 }
01160 
01161   
01173 template<typename T>
01174 void setStringParameterFromArray(
01175   const std::string          &paramName
01176   ,const Array<T>       &array
01177   ,ParameterList        *paramList
01178   )
01179 {
01180   TEUCHOS_TEST_FOR_EXCEPT(!paramList);
01181   paramList->set(paramName,toString(array));
01182 }
01183 
01184   
01249 template<typename T>
01250 Array<T> getArrayFromStringParameter(
01251   const ParameterList   &paramList
01252   ,const std::string         &paramName
01253   ,const int            arrayDim        = -1
01254   ,const bool           mustExist       = true
01255   )
01256 {
01257   std::string arrayStr;
01258   if(mustExist) {
01259     arrayStr = getParameter<std::string>(paramList,paramName);
01260   }
01261   else {
01262     const std::string
01263       *arrayStrPtr = getParameterPtr<std::string>(paramList,paramName);
01264     if(arrayStrPtr) {
01265       arrayStr = *arrayStrPtr;
01266     }
01267     else {
01268       return Array<T>(); // Return an empty array
01269     }
01270   }
01271   Array<T> a;
01272   try {
01273     a = fromStringToArray<T>(arrayStr);
01274   }
01275   catch( const InvalidArrayStringRepresentation&) {
01276     TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
01277       true, Exceptions::InvalidParameterValue
01278       ,"Error!  The parameter \""<<paramName<<"\"\n"
01279       "in the sublist \""<<paramList.name()<<"\"\n"
01280       "exists, but the std::string value:\n"
01281       "----------\n"
01282       <<arrayStr<<
01283       "\n----------\n"
01284       "is not a valid array represntation!"
01285       );
01286   }
01287   TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(
01288     ( ( a.size()>0 && arrayDim>=0 ) && static_cast<int>(a.size())!=arrayDim )
01289     ,Exceptions::InvalidParameterValue
01290     ,"Error!  The parameter \""<<paramName<<"\"\n"
01291     "in the sublist \""<<paramList.name()<<"\"\n"
01292     "exists and is a valid array, but the dimension of\n"
01293     "the read in array a.size() = " << a.size() << "\n"
01294     "was not equal to the expected size arrayDim = " << arrayDim << "!"
01295     );
01296   return a;
01297 }
01298 
01299 
01303 inline
01304 RCP<ParameterList> sublist(
01305   const RCP<ParameterList> &paramList, const std::string& name,
01306   bool mustAlreadyExist = false, const std::string& docString = ""
01307   )
01308 {
01309   return rcpWithEmbeddedObjPostDestroy(
01310     &paramList->sublist(name, mustAlreadyExist, docString), paramList, false );
01311 }
01312 
01313 
01317 inline
01318 RCP<const ParameterList> sublist(
01319   const RCP<const ParameterList> &paramList, const std::string& name
01320   )
01321 {
01322   return rcpWithEmbeddedObjPostDestroy(
01323     &paramList->sublist(name), paramList, false );
01324 }
01325 
01326   
01330 inline std::ostream& operator<<(std::ostream& os, const ParameterList& l)
01331 {
01332   return l.print(os);
01333 }
01334 
01335   
01336 } // end of Teuchos namespace
01337 
01338 
01339 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines