Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Teuchos_ParameterList.hpp
Go to the documentation of this file.
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Teuchos: Common Tools Package
5 // Copyright (2004) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
38 //
39 // ***********************************************************************
40 // @HEADER
41 
42 
43 #ifndef TEUCHOS_PARAMETER_LIST_H
44 #define TEUCHOS_PARAMETER_LIST_H
45 
54 #include "Teuchos_Assert.hpp"
55 #include "Teuchos_RCP.hpp"
56 #include "Teuchos_Array.hpp"
57 #include "Teuchos_map.hpp"
58 
59 
64 namespace Teuchos {
65 
76 };
77 
88 };
89 
134 
137 
140 
141 public:
142 
144 
145 
148 
150  class PrintOptions {
151  public:
152  PrintOptions() : indent_(0), showTypes_(false), showFlags_(false), showDoc_(false) {}
153  PrintOptions& indent(int _indent) { indent_ = _indent; return *this; }
154  PrintOptions& showTypes(bool _showTypes) { showTypes_ = _showTypes; return *this; }
155  PrintOptions& showFlags(bool _showFlags) { showFlags_ = _showFlags; return *this; }
156  PrintOptions& showDoc(bool _showDoc) { showDoc_ = _showDoc; return *this; }
157  PrintOptions& incrIndent(int indents) { indent_ += indents; return *this; }
158  int indent() const { return indent_; }
159  bool showTypes() const { return showTypes_; }
160  bool showFlags() const { return showFlags_; }
161  bool showDoc() const { return showDoc_; }
162  PrintOptions copy() const { return PrintOptions(*this); }
163  private:
164  int indent_;
167  bool showDoc_;
168  };
169 
171 
173 
174 
176  ParameterList() = default;
177 
179  ParameterList(const std::string &name,
180  RCP<const ParameterListModifier> const& modifier = null);
181 
183  ParameterList(const ParameterList& source);
184 
186  virtual ~ParameterList();
187 
189 
191 
193  ParameterList& setName( const std::string &name );
194 
198  ParameterList& operator= (const ParameterList& source);
199 
200  void setModifier(
201  RCP<const ParameterListModifier> const& modifier
202  );
203 
212  ParameterList& setParameters(const ParameterList& source);
213 
223  ParameterList& setParametersNotAlreadySet(const ParameterList& source);
224 
232  ParameterList& disableRecursiveValidation();
233 
242  ParameterList& disableRecursiveModification();
243 
252  ParameterList& disableRecursiveReconciliation();
253 
261  ParameterList& disableRecursiveAll();
262 
281  template<typename T>
282  ParameterList& set (std::string const& name,
283  T const& value,
284  std::string const& docString = "",
285  RCP<const ParameterEntryValidator> const& validator = null);
286 
291  ParameterList& set(
292  std::string const& name, char value[], std::string const& docString = "",
293  RCP<const ParameterEntryValidator> const& validator = null
294  );
295 
300  ParameterList& set(
301  std::string const& name, const char value[], std::string const& docString = "",
302  RCP<const ParameterEntryValidator> const& validator = null
303  );
304 
308  ParameterList& set(
309  std::string const& name, ParameterList const& value, std::string const& docString = ""
310  );
311 
316  ParameterList& setEntry(const std::string& name, const ParameterEntry& entry);
317 
323  template<typename T>
324  void recursivelySetValidator(RCP<const ParameterEntryValidator> const& validator,
325  int const depth = 1000);
326 
328 
330 
347  template<typename T>
348  T& get(const std::string& name, T def_value);
349 
353  std::string& get(const std::string& name, char def_value[]);
354 
358  std::string& get(const std::string& name, const char def_value[]);
359 
390  template<typename T>
391  T& get (const std::string& name);
392 
420  template<typename T>
421  const T& get (const std::string& name) const;
422 
428  template<typename T>
429  inline
430  T* getPtr(const std::string& name);
431 
437  template<typename T>
438  inline
439  const T* getPtr(const std::string& name) const;
440 
441  // ToDo: Add getSafePtr() functions to return Ptr<T> instead of raw T*
442 
448  ParameterEntry& getEntry(const std::string& name);
449 
455  inline
456  const ParameterEntry& getEntry(const std::string& name) const;
457 
460  inline
461  ParameterEntry* getEntryPtr(const std::string& name);
462 
463  // ToDo: Add function called getEntrySafePtr() to return Ptr<> as the main
464  // implementation and deprecate getEntryPtr()
465 
468  inline
469  const ParameterEntry* getEntryPtr(const std::string& name) const;
470 
473  inline RCP<ParameterEntry> getEntryRCP(const std::string& name);
474 
477  inline RCP<const ParameterEntry> getEntryRCP(const std::string& name) const;
478 
480  inline RCP<const ParameterListModifier> getModifier() const;
481 
483 
485 
486 
500  bool remove(
501  std::string const& name, bool throwIfNotExists = true
502  );
503 
505 
507 
508 
514  ParameterList& sublist(
515  const std::string& name, bool mustAlreadyExist = false,
516  const std::string& docString = ""
517  );
518 
523  ParameterList& sublist(
524  const std::string& name, RCP<const ParameterListModifier> const& modifier,
525  const std::string& docString = ""
526  );
527 
532  const ParameterList& sublist(const std::string& name) const;
533 
535 
537 
538 
540  const std::string& name() const;
541 
546  bool isParameter (const std::string& name) const;
547 
552  bool isSublist (const std::string& name) const;
553 
559  template<typename T>
560  bool isType (const std::string& name) const;
561 
562 #ifndef DOXYGEN_SHOULD_SKIP_THIS
563 
573  template<typename T>
574  bool isType(const std::string& name, T* ptr) const;
575 #endif
576 
578  Ordinal numParams () const;
579 
581 
583 
584 
590  void print() const;
591 
594  std::ostream& print(std::ostream& os, const PrintOptions &printOptions) const;
595 
598  std::ostream& print(std::ostream& os, int indent = 0, bool showTypes = false, bool showFlags = true ) const;
599 
601  void unused(std::ostream& os) const;
602 
604  std::string currentParametersString() const;
605 
607 
609 
610 
612  inline ConstIterator begin() const;
613 
615  inline ConstIterator end() const;
616 
618  inline const std::string& name(ConstIterator i) const;
619 
621  inline const ParameterEntry& entry(ConstIterator i) const;
622 
624 
626 
627 
672  void validateParameters(
673  ParameterList const& validParamList,
674  int const depth = 1000,
675  EValidateUsed const validateUsed = VALIDATE_USED_ENABLED,
676  EValidateDefaults const validateDefaults = VALIDATE_DEFAULTS_ENABLED
677  ) const;
678 
716  void validateParametersAndSetDefaults(
717  ParameterList const& validParamList,
718  int const depth = 1000
719  );
720 
735  void modifyParameterList(ParameterList &validParamList, int const depth = 1000);
736 
747  void reconcileParameterList(ParameterList &validParamList,
748  const bool left_to_right = true);
749 
751 
752 private: // Functions
753 
755  inline Iterator nonconstBegin();
757  inline Iterator nonconstEnd();
759  inline ParameterEntry& nonconstEntry(Iterator i);
761  void validateEntryExists(const std::string &funcName, const std::string &name,
762  const ParameterEntry *entry) const;
763  // ToDo: Change above function to take Ptr<> instead of raw pointer.
765  template<typename T>
766  void validateEntryType(const std::string &funcName, const std::string &name,
767  const ParameterEntry &entry ) const;
769  void validateEntryIsList(const std::string &name, const ParameterEntry &entry) const;
771  void validateMissingSublistMustExist(const std::string &baselist_name,
772  const std::string &sublist_name, const bool mustAlreadyExist) const;
774  void updateSubListNames(int depth = 0);
775 
776 private: // Data members
777 
779  std::string name_ = "ANONYMOUS";
780 
782 //use pragmas to disable some false-positive warnings for windows sharedlibs export
783 //#ifdef _MSC_VER
784 //#pragma warning(push)
785 //#pragma warning(disable:4251)
786 //#endif
788 //#ifdef _MSC_VER
789 //#pragma warning(pop)
790 //#endif
791 
793  bool disableRecursiveValidation_ = false;
794 
796  bool disableRecursiveModification_ = false;
797 
799  bool disableRecursiveReconciliation_ = false;
800 
802 };
803 
804 
809 inline
811 {
812  return rcp(new ParameterList);
813 }
814 
815 
820 inline
821 RCP<ParameterList> parameterList(const std::string &name)
822 {
823  return rcp(new ParameterList(name));
824 }
825 
826 
831 inline
833 {
834  return rcp(new ParameterList(source));
835 }
836 
837 
842 inline
844 {
845  return rcp(new ParameterList);
846 }
847 
848 
853 inline
854 RCP<ParameterList> createParameterList(const std::string &name)
855 {
856  return rcp(new ParameterList(name));
857 }
858 
859 
864 template<>
866 public:
867  static std::string name() { return "ParameterList"; }
868  static std::string concreteName( const ParameterList& /*t2*/ )
869  { return name(); }
870 };
871 
872 
877 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool operator==( const ParameterList& list1, const ParameterList& list2 );
878 
879 
884 inline
885 bool operator!=( const ParameterList& list1, const ParameterList& list2 )
886 {
887  return !( list1 == list2 );
888 }
889 
890 
898 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameModifiers (const ParameterList& list1,
901  const ParameterList& list2);
902 
903 
915 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValues( const ParameterList& list1, const ParameterList& list2,
916  bool verbose = false);
917 
918 
930 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValuesSorted( const ParameterList& list1,
931  const ParameterList& list2, bool verbose = false);
932 
933 
934 // /////////////////////////////////////////////////////
935 // Inline and Template Function Definitions
936 
937 
938 inline
939 ParameterList& ParameterList::setName( const std::string &name_in )
940 {
941  name_ = name_in;
942  return *this;
943 }
944 
945 
946 // Set functions
947 
948 
949 template<typename T>
950 inline
952  std::string const& name_in, T const& value_in, std::string const& docString_in,
953  RCP<const ParameterEntryValidator> const& validator_in
954  )
955 {
957  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
958  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
959  Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
960  const std::string docString =
961  (docString_in.length() ? docString_in : param->docString());
962  const RCP<const ParameterEntryValidator> validator =
963  (nonnull(validator_in) ? validator_in : param->validator());
964  // Create temp param to validate before setting
965  ParameterEntry param_new(value_in, false, false, docString, validator );
966  if (nonnull(validator)) {
967  validator->validate(param_new, name_in, this->name());
968  }
969  // Strong guarantee: (if exception is thrown, the value is not changed)
970  *param = param_new;
971  }
972  else {
973  ParameterEntry param_new(value_in, false, false, docString_in, validator_in);
974  if (nonnull(param_new.validator())) {
975  param_new.validator()->validate(param_new, name_in, this->name());
976  }
977  params_.setObj(name_in, param_new);
978  }
979  return *this;
980 }
981 
982 
983 inline
985  std::string const& name_in, char value[], std::string const& docString
986  ,RCP<const ParameterEntryValidator> const& validator
987  )
988 { return set(name_in, std::string(value), docString, validator); }
989 
990 
991 inline
993  const std::string& name_in, const char value[], const std::string &docString
994  ,RCP<const ParameterEntryValidator> const& validator
995  )
996 { return set( name_in, std::string(value), docString, validator ); }
997 
998 
999 inline
1001  std::string const& name_in, ParameterList const& value, std::string const& /*docString*/
1002  )
1003 {
1004  sublist(name_in) = value;
1005  return *this;
1006 }
1007 
1008 
1009 inline
1010 ParameterList& ParameterList::setEntry(std::string const& name_in, ParameterEntry const& entry_in)
1011 {
1012  params_.setObj(name_in, entry_in);
1013  return *this;
1014 }
1015 
1016 
1017 template<typename T>
1019  RCP<const ParameterEntryValidator> const& validator, int const depth)
1020 {
1021  ConstIterator itr;
1022  for (itr = this->begin(); itr != this->end(); ++itr){
1023  const std::string &entry_name = itr->first;
1024  if (this->isSublist(entry_name) && depth > 0){
1025  this->sublist(entry_name).recursivelySetValidator<T>(validator, depth - 1);
1026  } else{
1027  ParameterEntry *theEntry = this->getEntryPtr(entry_name);
1028  if (theEntry->isType<T>()){
1029  theEntry->setValidator(validator);
1030  }
1031  }
1032  }
1033 }
1034 
1035 
1036 // Get functions
1037 
1038 
1039 template<typename T>
1040 T& ParameterList::get(const std::string& name_in, T def_value)
1041 {
1043  Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1044  if (param_idx == SIOVOCB::getInvalidOrdinal()) {
1045  // Param does not exist
1046  param_idx = params_.setObj(name_in, ParameterEntry(def_value, true));
1047  }
1048  Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
1049  this->template validateEntryType<T>("get", name_in, *param);
1050  return getValue<T>(*param);
1051 }
1052 
1053 
1054 inline
1055 std::string& ParameterList::get(const std::string& name_in, char def_value[])
1056 { return get(name_in, std::string(def_value)); }
1057 
1058 
1059 inline
1060 std::string& ParameterList::get(const std::string& name_in, const char def_value[])
1061 { return get(name_in, std::string(def_value)); }
1062 
1063 
1064 template<typename T>
1065 T& ParameterList::get(const std::string& name_in)
1066 {
1067  ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1068  validateEntryExists("get",name_in,foundEntry);
1069  this->template validateEntryType<T>("get",name_in,*foundEntry);
1070  return getValue<T>(*foundEntry);
1071 }
1072 
1073 
1074 template<typename T>
1075 const T& ParameterList::get(const std::string& name_in) const
1076 {
1077  const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1078  validateEntryExists("get",name_in,foundEntry);
1079  this->template validateEntryType<T>("get",name_in,*foundEntry);
1080  return getValue<T>(*foundEntry);
1081 }
1082 
1083 
1084 template<typename T>
1085 inline
1086 T* ParameterList::getPtr(const std::string& name_in)
1087 {
1089  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1090  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1091  const Ptr<ParameterEntry> param_ptr = params_.getNonconstObjPtr(param_idx);
1092  if (param_ptr->isType<T>()) {
1093  return &param_ptr->getValue<T>(0);
1094  }
1095  // Note: The above is inefficinet. You have to do the dynamic_cast twice
1096  // (once to see if it is the type and once to do the cast). This could be
1097  // made more efficinet by upgrading Teuchos::any to add a any_cast_ptr()
1098  // function but I don't think anyone actually uses this function.
1099  return 0;
1100  }
1101  return 0;
1102 }
1103 
1104 
1105 template<typename T>
1106 inline
1107 const T* ParameterList::getPtr(const std::string& name_in) const
1108 {
1110  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1111  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1112  const Ptr<const ParameterEntry> param_ptr = params_.getObjPtr(param_idx);
1113  if (param_ptr->isType<T>()) {
1114  return &param_ptr->getValue<T>(0);
1115  }
1116  // Note: The above is inefficinet, see above non-const getPtr() function.
1117  return 0;
1118  }
1119  return 0;
1120 }
1121 
1122 
1123 inline
1124 ParameterEntry& ParameterList::getEntry(const std::string& name_in)
1125 {
1126  ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1127  validateEntryExists("get", name_in, foundEntry);
1128  return *foundEntry;
1129 }
1130 
1131 
1132 inline
1133 const ParameterEntry& ParameterList::getEntry(const std::string& name_in) const
1134 {
1135  const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1136  validateEntryExists("get", name_in, foundEntry);
1137  return *foundEntry;
1138 }
1139 
1140 
1141 inline
1143 ParameterList::getEntryPtr(const std::string& name_in)
1144 {
1146  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1147  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1148  return &*params_.getNonconstObjPtr(param_idx);
1149  }
1150  return 0;
1151 }
1152 
1153 
1154 inline
1155 const ParameterEntry*
1156 ParameterList::getEntryPtr(const std::string& name_in) const
1157 {
1159  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1160  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1161  return &*params_.getObjPtr(param_idx);
1162  }
1163  return 0;
1164 }
1165 
1166 
1167 inline RCP<ParameterEntry>
1168 ParameterList::getEntryRCP(const std::string& name_in)
1169 {
1171  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1172  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1173  return rcpFromPtr(params_.getNonconstObjPtr(param_idx));
1174  }
1175  return null;
1176 }
1177 
1178 
1180 ParameterList::getEntryRCP(const std::string& name_in) const
1181 {
1183  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1184  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1185  return rcpFromPtr(params_.getObjPtr(param_idx));
1186  }
1187  return null;
1188 }
1189 
1190 
1193 { return modifier_; }
1194 
1195 
1196 // Attribute Functions
1197 
1198 
1199 inline
1200 const std::string& ParameterList::name() const
1201 {
1202  return name_;
1203 }
1204 
1205 
1206 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1207 template<typename T>
1208 bool ParameterList::isType(const std::string& name_in, T* /*ptr*/) const
1209 {
1211  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1212  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1213  return params_.getObjPtr(param_idx)->isType<T>();
1214  }
1215  return false;
1216 }
1217 #endif
1218 
1219 
1220 template<typename T>
1221 bool ParameterList::isType(const std::string& name_in) const
1222 {
1223  return this->isType(name_in, static_cast<T*>(0));
1224 }
1225 
1226 
1227 // Read-only access to the iterator
1228 
1229 
1231 {
1232  return params_.begin();
1233 }
1234 
1235 
1237 {
1238  return params_.end();
1239 }
1240 
1241 
1242 inline const std::string& ParameterList::name(ConstIterator i) const
1243 {
1244  return (i->first);
1245 }
1246 
1247 
1249 {
1250  return (i->second);
1251 }
1252 
1253 
1254 // private
1255 
1256 
1258 {
1259  return params_.nonconstBegin();
1260 }
1261 
1262 
1264 {
1265  return params_.nonconstEnd();
1266 }
1267 
1268 
1270 {
1271  return (i->second);
1272 }
1273 
1274 
1275 template<typename T>
1276 inline
1278  const std::string &/*funcName*/, const std::string &name_in,
1279  const ParameterEntry &entry_in
1280  ) const
1281 {
1283  entry_in.getAny().type() != typeid(T), Exceptions::InvalidParameterType
1284  ,"Error! An attempt was made to access parameter \""<<name_in<<"\""
1285  " of type \""<<entry_in.getAny().typeName()<<"\""
1286  "\nin the parameter (sub)list \""<<this->name()<<"\""
1287  "\nusing the incorrect type \""<<TypeNameTraits<T>::name()<<"\"!"
1288  );
1289 }
1290 
1291 
1292 // //////////////////////////////////////
1293 // Helper functions
1294 
1295 
1302 template<typename T>
1303 T& getParameter( ParameterList& l, const std::string& name )
1304 {
1305  return l.template get<T>(name);
1306 }
1307 
1308 
1314 template<typename T>
1315 inline
1316 T& get( ParameterList& l, const std::string& name )
1317 {
1318  return getParameter<T>(l,name);
1319 }
1320 
1321 
1328 template<typename T>
1329 const T& getParameter( const ParameterList& l, const std::string& name )
1330 {
1331  return l.template get<T>(name);
1332 }
1333 
1334 
1342 template<typename T>
1343 inline
1344 T* getParameterPtr( ParameterList& l, const std::string& name )
1345 {
1346  return l.template getPtr<T>(name);
1347 }
1348 
1349 
1357 template<typename T>
1358 inline
1359 const T* getParameterPtr( const ParameterList& l, const std::string& name )
1360 {
1361  return l.template getPtr<T>(name);
1362 }
1363 
1364 
1371 template<typename T>
1372 inline
1373 bool isParameterType( ParameterList& l, const std::string& name )
1374 {
1375  return l.isType( name, (T*)NULL );
1376 }
1377 
1378 
1385 template<typename T>
1386 inline
1387 bool isParameterType( const ParameterList& l, const std::string& name )
1388 {
1389  return l.isType( name, (T*)NULL );
1390 }
1391 
1392 
1404 template<typename T>
1406  const std::string &paramName
1407  ,const Array<T> &array
1408  ,ParameterList *paramList
1409  )
1410 {
1411  TEUCHOS_TEST_FOR_EXCEPT(!paramList);
1412  paramList->set(paramName,toString(array));
1413 }
1414 
1415 
1480 template<typename T>
1482  const ParameterList &paramList
1483  ,const std::string &paramName
1484  ,const int arrayDim = -1
1485  ,const bool mustExist = true
1486  )
1487 {
1488  std::string arrayStr;
1489  if(mustExist) {
1490  arrayStr = getParameter<std::string>(paramList,paramName);
1491  }
1492  else {
1493  const std::string
1494  *arrayStrPtr = getParameterPtr<std::string>(paramList,paramName);
1495  if(arrayStrPtr) {
1496  arrayStr = *arrayStrPtr;
1497  }
1498  else {
1499  return Array<T>(); // Return an empty array
1500  }
1501  }
1502  Array<T> a;
1503  try {
1504  a = fromStringToArray<T>(arrayStr);
1505  }
1506  catch( const InvalidArrayStringRepresentation&) {
1509  ,"Error! The parameter \""<<paramName<<"\"\n"
1510  "in the sublist \""<<paramList.name()<<"\"\n"
1511  "exists, but the std::string value:\n"
1512  "----------\n"
1513  <<arrayStr<<
1514  "\n----------\n"
1515  "is not a valid array represntation!"
1516  );
1517  }
1519  ( ( a.size()>0 && arrayDim>=0 ) && static_cast<int>(a.size())!=arrayDim )
1521  ,"Error! The parameter \""<<paramName<<"\"\n"
1522  "in the sublist \""<<paramList.name()<<"\"\n"
1523  "exists and is a valid array, but the dimension of\n"
1524  "the read in array a.size() = " << a.size() << "\n"
1525  "was not equal to the expected size arrayDim = " << arrayDim << "!"
1526  );
1527  return a;
1528 }
1529 
1530 
1543 template<typename T>
1544 bool replaceParameterWithArray(const std::string &paramName, const std::string &newName,
1545  ParameterList &pl)
1546 {
1547  bool param_exists = false;
1548  bool overwrite = false;
1549  if (paramName == newName){
1550  overwrite = true;
1551  }
1552  if (pl.isParameter(paramName)){
1553  param_exists = true;
1554  TEUCHOS_TEST_FOR_EXCEPTION(!pl.isType<T>(paramName), std::logic_error,
1555  "The parameter " << paramName << " is not of type " << typeid(T).name());
1556  TEUCHOS_TEST_FOR_EXCEPTION(pl.isParameter(newName) && !overwrite,
1557  std::logic_error, "The parameter " << newName << " already exists in this "
1558  "parameter list.");
1559  Array<T> params = tuple<T>(pl.get<T>(paramName));
1560  pl.remove(paramName);
1561  pl.set(newName, params);
1562  }
1563  return param_exists;
1564 }
1565 
1566 
1570 inline
1572  const RCP<ParameterList> &paramList, const std::string& name,
1573  bool mustAlreadyExist = false, const std::string& docString = ""
1574  )
1575 {
1576  return rcpWithEmbeddedObjPostDestroy(
1577  &paramList->sublist(name, mustAlreadyExist, docString), paramList, false );
1578 }
1579 
1580 
1584 inline
1586  const RCP<const ParameterList> &paramList, const std::string& name
1587  )
1588 {
1589  return rcpWithEmbeddedObjPostDestroy(
1590  &paramList->sublist(name), paramList, false );
1591 }
1592 
1593 
1597 inline std::ostream& operator<<(std::ostream& os, const ParameterList& l)
1598 {
1599  return l.print(os);
1600 }
1601 
1602 
1603 } // end of Teuchos namespace
1604 
1605 
1606 #endif
void print() const
Print function to use in debugging in a debugger.
bool replaceParameterWithArray(const std::string &paramName, const std::string &newName, ParameterList &pl)
Replace a parameter with an array containing the parameter.
Object held as the &quot;value&quot; in the Teuchos::ParameterList std::map.
const std::string & name() const
The name of this ParameterList.
C++ Standard Library compatable filtered iterator.
Ordinal getObjOrdinalIndex(const std::string &key) const
Get the ordinal index given the string key.
ConstIterator end() const
An iterator pointing beyond the last entry.
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...
PrintOptions & showTypes(bool _showTypes)
RCP< ParameterEntry > getEntryRCP(const std::string &name)
Retrieves the RCP for an entry with the name name if it exists.
void setValidator(RCP< const ParameterEntryValidator > const &validator)
Set the validator.
RCP< const ParameterEntryValidator > validator() const
Return the (optional) validator object.
RCP< ParameterList > createParameterList()
Nonmember constructor.
RCP< ParameterList > createParameterList(const std::string &name)
Nonmember constructor.
T & get(const std::string &name, T def_value)
Return the parameter&#39;s value, or the default value if it is not there.
ParameterList & set(std::string const &name, T const &value, std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
Set a parameter whose value has type T.
bool nonnull(const std::shared_ptr< T > &p)
Returns true if p.get()!=NULL.
This object is held as the &quot;value&quot; in the Teuchos::ParameterList std::map.
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.
Iterator nonconstBegin()
An iterator pointing to the first entry.
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...
void validateEntryExists(const std::string &funcName, const std::string &name, const ParameterEntry *entry) const
Validate that a parameter exists.
bool isType() const
Test the type of the data being contained.
RCP< ParameterList > sublist(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.
void recursivelySetValidator(RCP< const ParameterEntryValidator > const &validator, int const depth=1000)
Recursively attach a validator to parameters of type 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...
void validateEntryType(const std::string &funcName, const std::string &name, const ParameterEntry &entry) const
Validate that a type is the same.
ParameterEntry * getEntryPtr(const std::string &name)
Retrieves the pointer for an entry with the name name if it exists.
RCP< ParameterList > parameterList()
Nonmember constructor.
ParameterList & setEntry(const std::string &name, const ParameterEntry &entry)
Set a parameter directly as a ParameterEntry.
bool isParameter(const std::string &name) const
Whether the given parameter exists in this list.
bool remove(std::string const &name, bool throwIfNotExists=true)
Remove a parameter (does not depend on the type of the parameter).
Iterator nonconstEnd()
An iterator pointing beyond the last entry.
std::ostream & operator<<(std::ostream &os, const ParameterList &l)
Output stream operator for handling the printing of the parameter list.
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
Deprecated.
bool isSublist(const std::string &name) const
Whether the given sublist exists in this list.
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...
bool operator!=(const ParameterList &list1, const ParameterList &list2)
Returns true if two parameter lists are not the same.
std::string toString(const HashSet< Key > &h)
RCP< ParameterList > parameterList(const ParameterList &source)
Nonmember constructor.
params_t::ConstIterator ConstIterator
Parameter container const iterator typedef.
std::string name_
Name of the (sub)list.
ParameterEntry & nonconstEntry(Iterator i)
Access to ParameterEntry (i.e., returns i-&gt;second)
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 ...
Utility class for setting and passing in print options.
T & getParameter(ParameterList &l, const std::string &name)
A templated helper function for getting a parameter from a non-const list. This helper function preve...
ConstIterator begin() const
An iterator pointing to the first entry.
RCP< const ParameterList > sublist(const RCP< const ParameterList > &paramList, const std::string &name)
Return a RCP to a sublist in another RCP-ed parameter list.
T * getParameterPtr(ParameterList &l, const std::string &name)
A templated helper function for getting a pointer to a parameter from a non-const list...
Ptr< const ObjType > getObjPtr(const Ordinal &idx) const
Get a const semi-persisting association with the stored object indexed by ordinal.
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 pa...
A list of parameters of arbitrary type.
RCP< const ParameterListModifier > modifier_
#define TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT
params_t params_
Parameter list.
Provides std::map class for deficient platforms.
Parameter List Modifier class.
const ParameterEntry & entry(ConstIterator i) const
Access to ParameterEntry (i.e., returns i-&gt;second)
any & getAny(bool activeQry=true)
Direct access to the Teuchos::any data value underlying this object. The bool argument activeQry (def...
Templated array class derived from the STL std::vector.
RCP< const ParameterListModifier > getModifier() const
Return the optional modifier object.
Ordinal setObj(const std::string &key, const ObjType &obj)
Set (or reset) object by value and return its ordinal index.
Default traits class that just returns typeid(T).name().
void setStringParameterFromArray(const std::string &paramName, const Array< T > &array, ParameterList *paramList)
Set a std::string parameter representation of an array.
size_type size() const
bool isType(const std::string &name) const
Whether the given parameter exists in this list and has type T.
EValidateDefaults
Validation defaults enum.
std::string typeName() const
Return the name of the type.
params_t::Iterator Iterator
Parameter container iterator typedef.
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...
ParameterList & setName(const std::string &name)
Set the name of *this list.
Smart reference counting pointer class for automatic garbage collection.
const std::type_info & type() const
Return the type of value being stored.
bool operator==(BigUInt< n > const &a, BigUInt< n > const &b)
ParameterEntry & getEntry(const std::string &name)
Retrieves an entry with the name name.
StringIndexedOrderedValueObjectContainer< ParameterEntry > params_t
Internal data-structure.
Ptr< ObjType > getNonconstObjPtr(const Ordinal &idx)
Get a nonconst semi-persisting association with the stored object indexed by ordinal.
EValidateUsed
Validation used enum.
RCP< ParameterList > parameterList(const std::string &name)
Nonmember constructor.
Reference-counted pointer class and non-member templated function implementations.
static std::string concreteName(const ParameterList &)
#define TEUCHOS_TEST_FOR_EXCEPT(throw_exception_test)
This macro is designed to be a short version of TEUCHOS_TEST_FOR_EXCEPTION() that is easier to call...
Simple wrapper class for raw pointers to single objects where no persisting relationship exists...
PrintOptions & showFlags(bool _showFlags)
#define TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.
Replacement for std::vector that is compatible with the Teuchos Memory Management classes...