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 
50 #include "TeuchosParameterList_config.h"
55 #include "Teuchos_Assert.hpp"
56 #include "Teuchos_RCP.hpp"
57 #include "Teuchos_Array.hpp"
58 #include "Teuchos_map.hpp"
59 
60 
65 namespace Teuchos {
66 
77 };
78 
89 };
90 
135 
138 
141 
142 public:
143 
145 
146 
149 
151  class PrintOptions {
152  public:
153  PrintOptions() : indent_(0), showTypes_(false), showFlags_(false), showDoc_(false), showDefault_(true) {}
154  PrintOptions& indent(int _indent) { indent_ = _indent; return *this; }
155  PrintOptions& showTypes(bool _showTypes) { showTypes_ = _showTypes; return *this; }
156  PrintOptions& showFlags(bool _showFlags) { showFlags_ = _showFlags; return *this; }
157  PrintOptions& showDoc(bool _showDoc) { showDoc_ = _showDoc; return *this; }
158  PrintOptions& showDefault(bool _showDefault) { showDefault_ = _showDefault; return *this; }
159  PrintOptions& incrIndent(int indents) { indent_ += indents; return *this; }
160  int indent() const { return indent_; }
161  bool showTypes() const { return showTypes_; }
162  bool showFlags() const { return showFlags_; }
163  bool showDoc() const { return showDoc_; }
164  bool showDefault() const { return showDefault_; }
165  PrintOptions copy() const { return PrintOptions(*this); }
166  private:
167  int indent_;
170  bool showDoc_;
172  };
173 
175 
177 
178 
180  ParameterList() = default;
181 
183  ParameterList(const std::string &name,
184  RCP<const ParameterListModifier> const& modifier = null);
185 
187  ParameterList(const ParameterList& source);
188 
190  virtual ~ParameterList();
191 
193 
195 
197  ParameterList& setName( const std::string &name );
198 
202  ParameterList& operator= (const ParameterList& source);
203 
204  void setModifier(
205  RCP<const ParameterListModifier> const& modifier
206  );
207 
216  ParameterList& setParameters(const ParameterList& source);
217 
227  ParameterList& setParametersNotAlreadySet(const ParameterList& source);
228 
236  ParameterList& disableRecursiveValidation();
237 
246  ParameterList& disableRecursiveModification();
247 
256  ParameterList& disableRecursiveReconciliation();
257 
265  ParameterList& disableRecursiveAll();
266 
285  template<typename T>
286  ParameterList& set (std::string const& name,
287  T const& value,
288  std::string const& docString = "",
289  RCP<const ParameterEntryValidator> const& validator = null);
290 
295  ParameterList& set(
296  std::string const& name, char value[], std::string const& docString = "",
297  RCP<const ParameterEntryValidator> const& validator = null
298  );
299 
304  ParameterList& set(
305  std::string const& name, const char value[], std::string const& docString = "",
306  RCP<const ParameterEntryValidator> const& validator = null
307  );
308 
312  ParameterList& set(
313  std::string const& name, ParameterList const& value, std::string const& docString = ""
314  );
315 
320  template <typename U, typename = std::enable_if_t<std::is_same_v<std::decay_t<U>, ParameterEntry>>>
321  ParameterList& setEntry(const std::string& name, U&& entry);
322 
328  template<typename T>
329  void recursivelySetValidator(RCP<const ParameterEntryValidator> const& validator,
330  int const depth = 1000);
331 
333 
335 
352  template<typename T>
353  T& get(const std::string& name, T def_value);
354 
358  std::string& get(const std::string& name, char def_value[]);
359 
363  std::string& get(const std::string& name, const char def_value[]);
364 
395  template<typename T>
396  T& get (const std::string& name);
397 
425  template<typename T>
426  const T& get (const std::string& name) const;
427 
433  template<typename T>
434  inline
435  T* getPtr(const std::string& name);
436 
442  template<typename T>
443  inline
444  const T* getPtr(const std::string& name) const;
445 
446  // ToDo: Add getSafePtr() functions to return Ptr<T> instead of raw T*
447 
453  ParameterEntry& getEntry(const std::string& name);
454 
460  inline
461  const ParameterEntry& getEntry(const std::string& name) const;
462 
465  inline
466  ParameterEntry* getEntryPtr(const std::string& name);
467 
468  // ToDo: Add function called getEntrySafePtr() to return Ptr<> as the main
469  // implementation and deprecate getEntryPtr()
470 
473  inline
474  const ParameterEntry* getEntryPtr(const std::string& name) const;
475 
478  inline RCP<ParameterEntry> getEntryRCP(const std::string& name);
479 
482  inline RCP<const ParameterEntry> getEntryRCP(const std::string& name) const;
483 
485  inline RCP<const ParameterListModifier> getModifier() const;
486 
488 
490 
491 
505  bool remove(
506  std::string const& name, bool throwIfNotExists = true
507  );
508 
510 
512 
513 
519  ParameterList& sublist(
520  const std::string& name, bool mustAlreadyExist = false,
521  const std::string& docString = ""
522  );
523 
528  ParameterList& sublist(
529  const std::string& name, RCP<const ParameterListModifier> const& modifier,
530  const std::string& docString = ""
531  );
532 
537  const ParameterList& sublist(const std::string& name) const;
538 
540 
542 
543 
545  const std::string& name() const;
546 
551  bool isParameter (const std::string& name) const;
552 
557  bool isSublist (const std::string& name) const;
558 
564  template<typename T>
565  bool isType (const std::string& name) const;
566 
567 #ifndef DOXYGEN_SHOULD_SKIP_THIS
568 
578  template<typename T>
579  bool isType(const std::string& name, T* ptr) const;
580 #endif
581 
583  Ordinal numParams () const;
584 
586 
588 
589 
595  void print() const;
596 
599  std::ostream& print(std::ostream& os, const PrintOptions &printOptions) const;
600 
603  std::ostream& print(std::ostream& os, int indent = 0, bool showTypes = false, bool showFlags = true, bool showDefault = true ) const;
604 
606  void unused(std::ostream& os) const;
607 
609  std::string currentParametersString() const;
610 
612 
614 
615 
617  inline ConstIterator begin() const;
618 
620  inline ConstIterator end() const;
621 
623  inline const std::string& name(ConstIterator i) const;
624 
626  inline const ParameterEntry& entry(ConstIterator i) const;
627 
629 
631 
632 
677  void validateParameters(
678  ParameterList const& validParamList,
679  int const depth = 1000,
680  EValidateUsed const validateUsed = VALIDATE_USED_ENABLED,
681  EValidateDefaults const validateDefaults = VALIDATE_DEFAULTS_ENABLED
682  ) const;
683 
721  void validateParametersAndSetDefaults(
722  ParameterList const& validParamList,
723  int const depth = 1000
724  );
725 
740  void modifyParameterList(ParameterList &validParamList, int const depth = 1000);
741 
752  void reconcileParameterList(ParameterList &validParamList,
753  const bool left_to_right = true);
754 
756 
757 private: // Functions
758 
760  inline Iterator nonconstBegin();
762  inline Iterator nonconstEnd();
764  inline ParameterEntry& nonconstEntry(Iterator i);
766  void validateEntryExists(const std::string &funcName, const std::string &name,
767  const ParameterEntry *entry) const;
768  // ToDo: Change above function to take Ptr<> instead of raw pointer.
770  template<typename T>
771  void validateEntryType(const std::string &funcName, const std::string &name,
772  const ParameterEntry &entry ) const;
774  void validateEntryIsList(const std::string &name, const ParameterEntry &entry) const;
776  void validateMissingSublistMustExist(const std::string &baselist_name,
777  const std::string &sublist_name, const bool mustAlreadyExist) const;
779  void updateSubListNames(int depth = 0);
780 
781 private: // Data members
782 
784  std::string name_ = "ANONYMOUS";
785 
787 //use pragmas to disable some false-positive warnings for windows sharedlibs export
788 //#ifdef _MSC_VER
789 //#pragma warning(push)
790 //#pragma warning(disable:4251)
791 //#endif
793 //#ifdef _MSC_VER
794 //#pragma warning(pop)
795 //#endif
796 
798  bool disableRecursiveValidation_ = false;
799 
801  bool disableRecursiveModification_ = false;
802 
804  bool disableRecursiveReconciliation_ = false;
805 
807 };
808 
809 
814 inline
816 {
817  return rcp(new ParameterList);
818 }
819 
820 
825 inline
826 RCP<ParameterList> parameterList(const std::string &name)
827 {
828  return rcp(new ParameterList(name));
829 }
830 
831 
836 inline
838 {
839  return rcp(new ParameterList(source));
840 }
841 
842 
847 inline
849 {
850  return rcp(new ParameterList);
851 }
852 
853 
858 inline
859 RCP<ParameterList> createParameterList(const std::string &name)
860 {
861  return rcp(new ParameterList(name));
862 }
863 
864 
869 template<>
871 public:
872  static std::string name() { return "ParameterList"; }
873  static std::string concreteName( const ParameterList& /*t2*/ )
874  { return name(); }
875 };
876 
877 
882 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool operator==( const ParameterList& list1, const ParameterList& list2 );
883 
884 
889 inline
890 bool operator!=( const ParameterList& list1, const ParameterList& list2 )
891 {
892  return !( list1 == list2 );
893 }
894 
895 
903 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameModifiers (const ParameterList& list1,
906  const ParameterList& list2);
907 
908 
920 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValues( const ParameterList& list1, const ParameterList& list2,
921  bool verbose = false);
922 
923 
935 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValuesSorted( const ParameterList& list1,
936  const ParameterList& list2, bool verbose = false);
937 
938 
939 // /////////////////////////////////////////////////////
940 // Inline and Template Function Definitions
941 
942 
943 inline
944 ParameterList& ParameterList::setName( const std::string &name_in )
945 {
946  name_ = name_in;
947  return *this;
948 }
949 
950 
951 // Set functions
952 
953 
954 template<typename T>
955 inline
957  std::string const& name_in, T const& value_in, std::string const& docString_in,
958  RCP<const ParameterEntryValidator> const& validator_in
959  )
960 {
962  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
963  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
964  Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
965  const std::string docString =
966  (docString_in.length() ? docString_in : param->docString());
967  const RCP<const ParameterEntryValidator> validator =
968  (nonnull(validator_in) ? validator_in : param->validator());
969  // Create temp param to validate before setting
970  ParameterEntry param_new(value_in, false, false, docString, validator );
971  if (nonnull(validator)) {
972  validator->validate(param_new, name_in, this->name());
973  }
974  // Strong guarantee: (if exception is thrown, the value is not changed)
975  *param = param_new;
976  }
977  else {
978  ParameterEntry param_new(value_in, false, false, docString_in, validator_in);
979  if (nonnull(param_new.validator())) {
980  param_new.validator()->validate(param_new, name_in, this->name());
981  }
982  params_.setObj(name_in, param_new);
983  }
984  return *this;
985 }
986 
987 
988 inline
990  std::string const& name_in, char value[], std::string const& docString
991  ,RCP<const ParameterEntryValidator> const& validator
992  )
993 { return set(name_in, std::string(value), docString, validator); }
994 
995 
996 inline
998  const std::string& name_in, const char value[], const std::string &docString
999  ,RCP<const ParameterEntryValidator> const& validator
1000  )
1001 { return set( name_in, std::string(value), docString, validator ); }
1002 
1003 
1004 inline
1006  std::string const& name_in, ParameterList const& value, std::string const& /*docString*/
1007  )
1008 {
1009  sublist(name_in) = value;
1010  return *this;
1011 }
1012 
1013 
1014 template <typename U, typename>
1015 inline
1016 ParameterList& ParameterList::setEntry(std::string const& name_in, U&& entry_in)
1017 {
1018  params_.setObj(name_in, std::forward<U>(entry_in));
1019  return *this;
1020 }
1021 
1022 template<typename T>
1024  RCP<const ParameterEntryValidator> const& validator, int const depth)
1025 {
1026  ConstIterator itr;
1027  for (itr = this->begin(); itr != this->end(); ++itr){
1028  const std::string &entry_name = itr->first;
1029  if (this->isSublist(entry_name) && depth > 0){
1030  this->sublist(entry_name).recursivelySetValidator<T>(validator, depth - 1);
1031  } else{
1032  ParameterEntry *theEntry = this->getEntryPtr(entry_name);
1033  if (theEntry->isType<T>()){
1034  theEntry->setValidator(validator);
1035  }
1036  }
1037  }
1038 }
1039 
1040 
1041 // Get functions
1042 
1043 
1044 template<typename T>
1045 T& ParameterList::get(const std::string& name_in, T def_value)
1046 {
1048  Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1049  if (param_idx == SIOVOCB::getInvalidOrdinal()) {
1050  // Param does not exist
1051  param_idx = params_.setObj(name_in, ParameterEntry(def_value, true));
1052  }
1053  Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
1054  this->template validateEntryType<T>("get", name_in, *param);
1055  return getValue<T>(*param);
1056 }
1057 
1058 
1059 inline
1060 std::string& ParameterList::get(const std::string& name_in, char def_value[])
1061 { return get(name_in, std::string(def_value)); }
1062 
1063 
1064 inline
1065 std::string& ParameterList::get(const std::string& name_in, const char def_value[])
1066 { return get(name_in, std::string(def_value)); }
1067 
1068 
1069 template<typename T>
1070 T& ParameterList::get(const std::string& name_in)
1071 {
1072  ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1073  validateEntryExists("get",name_in,foundEntry);
1074  this->template validateEntryType<T>("get",name_in,*foundEntry);
1075  return getValue<T>(*foundEntry);
1076 }
1077 
1078 
1079 template<typename T>
1080 const T& ParameterList::get(const std::string& name_in) const
1081 {
1082  const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1083  validateEntryExists("get",name_in,foundEntry);
1084  this->template validateEntryType<T>("get",name_in,*foundEntry);
1085  return getValue<T>(*foundEntry);
1086 }
1087 
1088 
1089 template<typename T>
1090 inline
1091 T* ParameterList::getPtr(const std::string& name_in)
1092 {
1094  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1095  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1096  const Ptr<ParameterEntry> param_ptr = params_.getNonconstObjPtr(param_idx);
1097  if (param_ptr->isType<T>()) {
1098  return &param_ptr->getValue<T>(0);
1099  }
1100  // Note: The above is inefficinet. You have to do the dynamic_cast twice
1101  // (once to see if it is the type and once to do the cast). This could be
1102  // made more efficinet by upgrading Teuchos::any to add a any_cast_ptr()
1103  // function but I don't think anyone actually uses this function.
1104  return 0;
1105  }
1106  return 0;
1107 }
1108 
1109 
1110 template<typename T>
1111 inline
1112 const T* ParameterList::getPtr(const std::string& name_in) const
1113 {
1115  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1116  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1117  const Ptr<const ParameterEntry> param_ptr = params_.getObjPtr(param_idx);
1118  if (param_ptr->isType<T>()) {
1119  return &param_ptr->getValue<T>(0);
1120  }
1121  // Note: The above is inefficinet, see above non-const getPtr() function.
1122  return 0;
1123  }
1124  return 0;
1125 }
1126 
1127 
1128 inline
1129 ParameterEntry& ParameterList::getEntry(const std::string& name_in)
1130 {
1131  ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1132  validateEntryExists("get", name_in, foundEntry);
1133  return *foundEntry;
1134 }
1135 
1136 
1137 inline
1138 const ParameterEntry& ParameterList::getEntry(const std::string& name_in) const
1139 {
1140  const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1141  validateEntryExists("get", name_in, foundEntry);
1142  return *foundEntry;
1143 }
1144 
1145 
1146 inline
1148 ParameterList::getEntryPtr(const std::string& name_in)
1149 {
1151  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1152  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1153  return &*params_.getNonconstObjPtr(param_idx);
1154  }
1155  return 0;
1156 }
1157 
1158 
1159 inline
1160 const ParameterEntry*
1161 ParameterList::getEntryPtr(const std::string& name_in) const
1162 {
1164  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1165  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1166  return &*params_.getObjPtr(param_idx);
1167  }
1168  return 0;
1169 }
1170 
1171 
1172 inline RCP<ParameterEntry>
1173 ParameterList::getEntryRCP(const std::string& name_in)
1174 {
1176  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1177  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1178  return rcpFromPtr(params_.getNonconstObjPtr(param_idx));
1179  }
1180  return null;
1181 }
1182 
1183 
1185 ParameterList::getEntryRCP(const std::string& name_in) const
1186 {
1188  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1189  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1190  return rcpFromPtr(params_.getObjPtr(param_idx));
1191  }
1192  return null;
1193 }
1194 
1195 
1198 { return modifier_; }
1199 
1200 
1201 // Attribute Functions
1202 
1203 
1204 inline
1205 const std::string& ParameterList::name() const
1206 {
1207  return name_;
1208 }
1209 
1210 
1211 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1212 template<typename T>
1213 bool ParameterList::isType(const std::string& name_in, T* /*ptr*/) const
1214 {
1216  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1217  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1218  return params_.getObjPtr(param_idx)->isType<T>();
1219  }
1220  return false;
1221 }
1222 #endif
1223 
1224 
1225 template<typename T>
1226 bool ParameterList::isType(const std::string& name_in) const
1227 {
1228  return this->isType(name_in, static_cast<T*>(0));
1229 }
1230 
1231 
1232 // Read-only access to the iterator
1233 
1234 
1236 {
1237  return params_.begin();
1238 }
1239 
1240 
1242 {
1243  return params_.end();
1244 }
1245 
1246 
1247 inline const std::string& ParameterList::name(ConstIterator i) const
1248 {
1249  return (i->first);
1250 }
1251 
1252 
1254 {
1255  return (i->second);
1256 }
1257 
1258 
1259 // private
1260 
1261 
1263 {
1264  return params_.nonconstBegin();
1265 }
1266 
1267 
1269 {
1270  return params_.nonconstEnd();
1271 }
1272 
1273 
1275 {
1276  return (i->second);
1277 }
1278 
1279 
1280 template<typename T>
1281 inline
1283  const std::string &/*funcName*/, const std::string &name_in,
1284  const ParameterEntry &entry_in
1285  ) const
1286 {
1288  entry_in.getAny().type() != typeid(T), Exceptions::InvalidParameterType
1289  ,"Error! An attempt was made to access parameter \""<<name_in<<"\""
1290  " of type \""<<entry_in.getAny().typeName()<<"\""
1291  "\nin the parameter (sub)list \""<<this->name()<<"\""
1292  "\nusing the incorrect type \""<<TypeNameTraits<T>::name()<<"\"!"
1293  );
1294 }
1295 
1296 
1297 // //////////////////////////////////////
1298 // Helper functions
1299 
1300 
1307 template<typename T>
1308 T& getParameter( ParameterList& l, const std::string& name )
1309 {
1310  return l.template get<T>(name);
1311 }
1312 
1313 
1319 template<typename T>
1320 inline
1321 T& get( ParameterList& l, const std::string& name )
1322 {
1323  return getParameter<T>(l,name);
1324 }
1325 
1326 
1333 template<typename T>
1334 const T& getParameter( const ParameterList& l, const std::string& name )
1335 {
1336  return l.template get<T>(name);
1337 }
1338 
1339 
1347 template<typename T>
1348 inline
1349 T* getParameterPtr( ParameterList& l, const std::string& name )
1350 {
1351  return l.template getPtr<T>(name);
1352 }
1353 
1354 
1362 template<typename T>
1363 inline
1364 const T* getParameterPtr( const ParameterList& l, const std::string& name )
1365 {
1366  return l.template getPtr<T>(name);
1367 }
1368 
1369 
1376 template<typename T>
1377 inline
1378 bool isParameterType( ParameterList& l, const std::string& name )
1379 {
1380  return l.isType( name, (T*)NULL );
1381 }
1382 
1383 
1390 template<typename T>
1391 inline
1392 bool isParameterType( const ParameterList& l, const std::string& name )
1393 {
1394  return l.isType( name, (T*)NULL );
1395 }
1396 
1397 
1409 template<typename T>
1411  const std::string &paramName
1412  ,const Array<T> &array
1413  ,ParameterList *paramList
1414  )
1415 {
1416  TEUCHOS_TEST_FOR_EXCEPT(!paramList);
1417  paramList->set(paramName,toString(array));
1418 }
1419 
1420 
1485 template<typename T>
1487  const ParameterList &paramList
1488  ,const std::string &paramName
1489  ,const int arrayDim = -1
1490  ,const bool mustExist = true
1491  )
1492 {
1493  std::string arrayStr;
1494  if(mustExist) {
1495  arrayStr = getParameter<std::string>(paramList,paramName);
1496  }
1497  else {
1498  const std::string
1499  *arrayStrPtr = getParameterPtr<std::string>(paramList,paramName);
1500  if(arrayStrPtr) {
1501  arrayStr = *arrayStrPtr;
1502  }
1503  else {
1504  return Array<T>(); // Return an empty array
1505  }
1506  }
1507  Array<T> a;
1508  try {
1509  a = fromStringToArray<T>(arrayStr);
1510  }
1511  catch( const InvalidArrayStringRepresentation&) {
1514  ,"Error! The parameter \""<<paramName<<"\"\n"
1515  "in the sublist \""<<paramList.name()<<"\"\n"
1516  "exists, but the std::string value:\n"
1517  "----------\n"
1518  <<arrayStr<<
1519  "\n----------\n"
1520  "is not a valid array represntation!"
1521  );
1522  }
1524  ( ( a.size()>0 && arrayDim>=0 ) && static_cast<int>(a.size())!=arrayDim )
1526  ,"Error! The parameter \""<<paramName<<"\"\n"
1527  "in the sublist \""<<paramList.name()<<"\"\n"
1528  "exists and is a valid array, but the dimension of\n"
1529  "the read in array a.size() = " << a.size() << "\n"
1530  "was not equal to the expected size arrayDim = " << arrayDim << "!"
1531  );
1532  return a;
1533 }
1534 
1535 
1548 template<typename T>
1549 bool replaceParameterWithArray(const std::string &paramName, const std::string &newName,
1550  ParameterList &pl)
1551 {
1552  bool param_exists = false;
1553  bool overwrite = false;
1554  if (paramName == newName){
1555  overwrite = true;
1556  }
1557  if (pl.isParameter(paramName)){
1558  param_exists = true;
1559  TEUCHOS_TEST_FOR_EXCEPTION(!pl.isType<T>(paramName), std::logic_error,
1560  "The parameter " << paramName << " is not of type " << typeid(T).name());
1561  TEUCHOS_TEST_FOR_EXCEPTION(pl.isParameter(newName) && !overwrite,
1562  std::logic_error, "The parameter " << newName << " already exists in this "
1563  "parameter list.");
1564  Array<T> params = tuple<T>(pl.get<T>(paramName));
1565  pl.remove(paramName);
1566  pl.set(newName, params);
1567  }
1568  return param_exists;
1569 }
1570 
1571 
1575 inline
1577  const RCP<ParameterList> &paramList, const std::string& name,
1578  bool mustAlreadyExist = false, const std::string& docString = ""
1579  )
1580 {
1581  return rcpWithEmbeddedObjPostDestroy(
1582  &paramList->sublist(name, mustAlreadyExist, docString), paramList, false );
1583 }
1584 
1585 
1589 inline
1591  const RCP<const ParameterList> &paramList, const std::string& name
1592  )
1593 {
1594  return rcpWithEmbeddedObjPostDestroy(
1595  &paramList->sublist(name), paramList, false );
1596 }
1597 
1598 
1602 inline std::ostream& operator<<(std::ostream& os, const ParameterList& l)
1603 {
1604  return l.print(os);
1605 }
1606 
1607 
1608 } // end of Teuchos namespace
1609 
1610 
1611 #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.
ParameterList & setEntry(const std::string &name, U &&entry)
Set a parameter directly as a ParameterEntry.
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.
Ordinal setObj(const std::string &key, U &&obj)
Set (or reset) object by value and return its ordinal index.
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.
PrintOptions & showDefault(bool _showDefault)
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.
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...