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), showDefault_(true) {}
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& showDefault(bool _showDefault) { showDefault_ = _showDefault; return *this; }
158  PrintOptions& incrIndent(int indents) { indent_ += indents; return *this; }
159  int indent() const { return indent_; }
160  bool showTypes() const { return showTypes_; }
161  bool showFlags() const { return showFlags_; }
162  bool showDoc() const { return showDoc_; }
163  bool showDefault() const { return showDefault_; }
164  PrintOptions copy() const { return PrintOptions(*this); }
165  private:
166  int indent_;
169  bool showDoc_;
171  };
172 
174 
176 
177 
179  ParameterList() = default;
180 
182  ParameterList(const std::string &name,
183  RCP<const ParameterListModifier> const& modifier = null);
184 
186  ParameterList(const ParameterList& source);
187 
189  virtual ~ParameterList();
190 
192 
194 
196  ParameterList& setName( const std::string &name );
197 
201  ParameterList& operator= (const ParameterList& source);
202 
203  void setModifier(
204  RCP<const ParameterListModifier> const& modifier
205  );
206 
215  ParameterList& setParameters(const ParameterList& source);
216 
226  ParameterList& setParametersNotAlreadySet(const ParameterList& source);
227 
235  ParameterList& disableRecursiveValidation();
236 
245  ParameterList& disableRecursiveModification();
246 
255  ParameterList& disableRecursiveReconciliation();
256 
264  ParameterList& disableRecursiveAll();
265 
284  template<typename T>
285  ParameterList& set (std::string const& name,
286  T const& value,
287  std::string const& docString = "",
288  RCP<const ParameterEntryValidator> const& validator = null);
289 
294  ParameterList& set(
295  std::string const& name, char value[], std::string const& docString = "",
296  RCP<const ParameterEntryValidator> const& validator = null
297  );
298 
303  ParameterList& set(
304  std::string const& name, const char value[], std::string const& docString = "",
305  RCP<const ParameterEntryValidator> const& validator = null
306  );
307 
311  ParameterList& set(
312  std::string const& name, ParameterList const& value, std::string const& docString = ""
313  );
314 
319  ParameterList& setEntry(const std::string& name, const ParameterEntry& entry);
320 
326  template<typename T>
327  void recursivelySetValidator(RCP<const ParameterEntryValidator> const& validator,
328  int const depth = 1000);
329 
331 
333 
350  template<typename T>
351  T& get(const std::string& name, T def_value);
352 
356  std::string& get(const std::string& name, char def_value[]);
357 
361  std::string& get(const std::string& name, const char def_value[]);
362 
393  template<typename T>
394  T& get (const std::string& name);
395 
423  template<typename T>
424  const T& get (const std::string& name) const;
425 
431  template<typename T>
432  inline
433  T* getPtr(const std::string& name);
434 
440  template<typename T>
441  inline
442  const T* getPtr(const std::string& name) const;
443 
444  // ToDo: Add getSafePtr() functions to return Ptr<T> instead of raw T*
445 
451  ParameterEntry& getEntry(const std::string& name);
452 
458  inline
459  const ParameterEntry& getEntry(const std::string& name) const;
460 
463  inline
464  ParameterEntry* getEntryPtr(const std::string& name);
465 
466  // ToDo: Add function called getEntrySafePtr() to return Ptr<> as the main
467  // implementation and deprecate getEntryPtr()
468 
471  inline
472  const ParameterEntry* getEntryPtr(const std::string& name) const;
473 
476  inline RCP<ParameterEntry> getEntryRCP(const std::string& name);
477 
480  inline RCP<const ParameterEntry> getEntryRCP(const std::string& name) const;
481 
483  inline RCP<const ParameterListModifier> getModifier() const;
484 
486 
488 
489 
503  bool remove(
504  std::string const& name, bool throwIfNotExists = true
505  );
506 
508 
510 
511 
517  ParameterList& sublist(
518  const std::string& name, bool mustAlreadyExist = false,
519  const std::string& docString = ""
520  );
521 
526  ParameterList& sublist(
527  const std::string& name, RCP<const ParameterListModifier> const& modifier,
528  const std::string& docString = ""
529  );
530 
535  const ParameterList& sublist(const std::string& name) const;
536 
538 
540 
541 
543  const std::string& name() const;
544 
549  bool isParameter (const std::string& name) const;
550 
555  bool isSublist (const std::string& name) const;
556 
562  template<typename T>
563  bool isType (const std::string& name) const;
564 
565 #ifndef DOXYGEN_SHOULD_SKIP_THIS
566 
576  template<typename T>
577  bool isType(const std::string& name, T* ptr) const;
578 #endif
579 
581  Ordinal numParams () const;
582 
584 
586 
587 
593  void print() const;
594 
597  std::ostream& print(std::ostream& os, const PrintOptions &printOptions) const;
598 
601  std::ostream& print(std::ostream& os, int indent = 0, bool showTypes = false, bool showFlags = true, bool showDefault = true ) const;
602 
604  void unused(std::ostream& os) const;
605 
607  std::string currentParametersString() const;
608 
610 
612 
613 
615  inline ConstIterator begin() const;
616 
618  inline ConstIterator end() const;
619 
621  inline const std::string& name(ConstIterator i) const;
622 
624  inline const ParameterEntry& entry(ConstIterator i) const;
625 
627 
629 
630 
675  void validateParameters(
676  ParameterList const& validParamList,
677  int const depth = 1000,
678  EValidateUsed const validateUsed = VALIDATE_USED_ENABLED,
679  EValidateDefaults const validateDefaults = VALIDATE_DEFAULTS_ENABLED
680  ) const;
681 
719  void validateParametersAndSetDefaults(
720  ParameterList const& validParamList,
721  int const depth = 1000
722  );
723 
738  void modifyParameterList(ParameterList &validParamList, int const depth = 1000);
739 
750  void reconcileParameterList(ParameterList &validParamList,
751  const bool left_to_right = true);
752 
754 
755 private: // Functions
756 
758  inline Iterator nonconstBegin();
760  inline Iterator nonconstEnd();
762  inline ParameterEntry& nonconstEntry(Iterator i);
764  void validateEntryExists(const std::string &funcName, const std::string &name,
765  const ParameterEntry *entry) const;
766  // ToDo: Change above function to take Ptr<> instead of raw pointer.
768  template<typename T>
769  void validateEntryType(const std::string &funcName, const std::string &name,
770  const ParameterEntry &entry ) const;
772  void validateEntryIsList(const std::string &name, const ParameterEntry &entry) const;
774  void validateMissingSublistMustExist(const std::string &baselist_name,
775  const std::string &sublist_name, const bool mustAlreadyExist) const;
777  void updateSubListNames(int depth = 0);
778 
779 private: // Data members
780 
782  std::string name_ = "ANONYMOUS";
783 
785 //use pragmas to disable some false-positive warnings for windows sharedlibs export
786 //#ifdef _MSC_VER
787 //#pragma warning(push)
788 //#pragma warning(disable:4251)
789 //#endif
791 //#ifdef _MSC_VER
792 //#pragma warning(pop)
793 //#endif
794 
796  bool disableRecursiveValidation_ = false;
797 
799  bool disableRecursiveModification_ = false;
800 
802  bool disableRecursiveReconciliation_ = false;
803 
805 };
806 
807 
812 inline
814 {
815  return rcp(new ParameterList);
816 }
817 
818 
823 inline
824 RCP<ParameterList> parameterList(const std::string &name)
825 {
826  return rcp(new ParameterList(name));
827 }
828 
829 
834 inline
836 {
837  return rcp(new ParameterList(source));
838 }
839 
840 
845 inline
847 {
848  return rcp(new ParameterList);
849 }
850 
851 
856 inline
857 RCP<ParameterList> createParameterList(const std::string &name)
858 {
859  return rcp(new ParameterList(name));
860 }
861 
862 
867 template<>
869 public:
870  static std::string name() { return "ParameterList"; }
871  static std::string concreteName( const ParameterList& /*t2*/ )
872  { return name(); }
873 };
874 
875 
880 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool operator==( const ParameterList& list1, const ParameterList& list2 );
881 
882 
887 inline
888 bool operator!=( const ParameterList& list1, const ParameterList& list2 )
889 {
890  return !( list1 == list2 );
891 }
892 
893 
901 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameModifiers (const ParameterList& list1,
904  const ParameterList& list2);
905 
906 
918 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValues( const ParameterList& list1, const ParameterList& list2,
919  bool verbose = false);
920 
921 
933 TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT bool haveSameValuesSorted( const ParameterList& list1,
934  const ParameterList& list2, bool verbose = false);
935 
936 
937 // /////////////////////////////////////////////////////
938 // Inline and Template Function Definitions
939 
940 
941 inline
942 ParameterList& ParameterList::setName( const std::string &name_in )
943 {
944  name_ = name_in;
945  return *this;
946 }
947 
948 
949 // Set functions
950 
951 
952 template<typename T>
953 inline
955  std::string const& name_in, T const& value_in, std::string const& docString_in,
956  RCP<const ParameterEntryValidator> const& validator_in
957  )
958 {
960  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
961  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
962  Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
963  const std::string docString =
964  (docString_in.length() ? docString_in : param->docString());
965  const RCP<const ParameterEntryValidator> validator =
966  (nonnull(validator_in) ? validator_in : param->validator());
967  // Create temp param to validate before setting
968  ParameterEntry param_new(value_in, false, false, docString, validator );
969  if (nonnull(validator)) {
970  validator->validate(param_new, name_in, this->name());
971  }
972  // Strong guarantee: (if exception is thrown, the value is not changed)
973  *param = param_new;
974  }
975  else {
976  ParameterEntry param_new(value_in, false, false, docString_in, validator_in);
977  if (nonnull(param_new.validator())) {
978  param_new.validator()->validate(param_new, name_in, this->name());
979  }
980  params_.setObj(name_in, param_new);
981  }
982  return *this;
983 }
984 
985 
986 inline
988  std::string const& name_in, char value[], std::string const& docString
989  ,RCP<const ParameterEntryValidator> const& validator
990  )
991 { return set(name_in, std::string(value), docString, validator); }
992 
993 
994 inline
996  const std::string& name_in, const char value[], const std::string &docString
997  ,RCP<const ParameterEntryValidator> const& validator
998  )
999 { return set( name_in, std::string(value), docString, validator ); }
1000 
1001 
1002 inline
1004  std::string const& name_in, ParameterList const& value, std::string const& /*docString*/
1005  )
1006 {
1007  sublist(name_in) = value;
1008  return *this;
1009 }
1010 
1011 
1012 inline
1013 ParameterList& ParameterList::setEntry(std::string const& name_in, ParameterEntry const& entry_in)
1014 {
1015  params_.setObj(name_in, entry_in);
1016  return *this;
1017 }
1018 
1019 
1020 template<typename T>
1022  RCP<const ParameterEntryValidator> const& validator, int const depth)
1023 {
1024  ConstIterator itr;
1025  for (itr = this->begin(); itr != this->end(); ++itr){
1026  const std::string &entry_name = itr->first;
1027  if (this->isSublist(entry_name) && depth > 0){
1028  this->sublist(entry_name).recursivelySetValidator<T>(validator, depth - 1);
1029  } else{
1030  ParameterEntry *theEntry = this->getEntryPtr(entry_name);
1031  if (theEntry->isType<T>()){
1032  theEntry->setValidator(validator);
1033  }
1034  }
1035  }
1036 }
1037 
1038 
1039 // Get functions
1040 
1041 
1042 template<typename T>
1043 T& ParameterList::get(const std::string& name_in, T def_value)
1044 {
1046  Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1047  if (param_idx == SIOVOCB::getInvalidOrdinal()) {
1048  // Param does not exist
1049  param_idx = params_.setObj(name_in, ParameterEntry(def_value, true));
1050  }
1051  Ptr<ParameterEntry> param = params_.getNonconstObjPtr(param_idx);
1052  this->template validateEntryType<T>("get", name_in, *param);
1053  return getValue<T>(*param);
1054 }
1055 
1056 
1057 inline
1058 std::string& ParameterList::get(const std::string& name_in, char def_value[])
1059 { return get(name_in, std::string(def_value)); }
1060 
1061 
1062 inline
1063 std::string& ParameterList::get(const std::string& name_in, const char def_value[])
1064 { return get(name_in, std::string(def_value)); }
1065 
1066 
1067 template<typename T>
1068 T& ParameterList::get(const std::string& name_in)
1069 {
1070  ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1071  validateEntryExists("get",name_in,foundEntry);
1072  this->template validateEntryType<T>("get",name_in,*foundEntry);
1073  return getValue<T>(*foundEntry);
1074 }
1075 
1076 
1077 template<typename T>
1078 const T& ParameterList::get(const std::string& name_in) const
1079 {
1080  const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1081  validateEntryExists("get",name_in,foundEntry);
1082  this->template validateEntryType<T>("get",name_in,*foundEntry);
1083  return getValue<T>(*foundEntry);
1084 }
1085 
1086 
1087 template<typename T>
1088 inline
1089 T* ParameterList::getPtr(const std::string& name_in)
1090 {
1092  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1093  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1094  const Ptr<ParameterEntry> param_ptr = params_.getNonconstObjPtr(param_idx);
1095  if (param_ptr->isType<T>()) {
1096  return &param_ptr->getValue<T>(0);
1097  }
1098  // Note: The above is inefficinet. You have to do the dynamic_cast twice
1099  // (once to see if it is the type and once to do the cast). This could be
1100  // made more efficinet by upgrading Teuchos::any to add a any_cast_ptr()
1101  // function but I don't think anyone actually uses this function.
1102  return 0;
1103  }
1104  return 0;
1105 }
1106 
1107 
1108 template<typename T>
1109 inline
1110 const T* ParameterList::getPtr(const std::string& name_in) const
1111 {
1113  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1114  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1115  const Ptr<const ParameterEntry> param_ptr = params_.getObjPtr(param_idx);
1116  if (param_ptr->isType<T>()) {
1117  return &param_ptr->getValue<T>(0);
1118  }
1119  // Note: The above is inefficinet, see above non-const getPtr() function.
1120  return 0;
1121  }
1122  return 0;
1123 }
1124 
1125 
1126 inline
1127 ParameterEntry& ParameterList::getEntry(const std::string& name_in)
1128 {
1129  ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1130  validateEntryExists("get", name_in, foundEntry);
1131  return *foundEntry;
1132 }
1133 
1134 
1135 inline
1136 const ParameterEntry& ParameterList::getEntry(const std::string& name_in) const
1137 {
1138  const ParameterEntry *foundEntry = this->getEntryPtr(name_in);
1139  validateEntryExists("get", name_in, foundEntry);
1140  return *foundEntry;
1141 }
1142 
1143 
1144 inline
1146 ParameterList::getEntryPtr(const std::string& name_in)
1147 {
1149  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1150  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1151  return &*params_.getNonconstObjPtr(param_idx);
1152  }
1153  return 0;
1154 }
1155 
1156 
1157 inline
1158 const ParameterEntry*
1159 ParameterList::getEntryPtr(const std::string& name_in) const
1160 {
1162  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1163  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1164  return &*params_.getObjPtr(param_idx);
1165  }
1166  return 0;
1167 }
1168 
1169 
1170 inline RCP<ParameterEntry>
1171 ParameterList::getEntryRCP(const std::string& name_in)
1172 {
1174  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1175  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1176  return rcpFromPtr(params_.getNonconstObjPtr(param_idx));
1177  }
1178  return null;
1179 }
1180 
1181 
1183 ParameterList::getEntryRCP(const std::string& name_in) const
1184 {
1186  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1187  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1188  return rcpFromPtr(params_.getObjPtr(param_idx));
1189  }
1190  return null;
1191 }
1192 
1193 
1196 { return modifier_; }
1197 
1198 
1199 // Attribute Functions
1200 
1201 
1202 inline
1203 const std::string& ParameterList::name() const
1204 {
1205  return name_;
1206 }
1207 
1208 
1209 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1210 template<typename T>
1211 bool ParameterList::isType(const std::string& name_in, T* /*ptr*/) const
1212 {
1214  const Ordinal param_idx = params_.getObjOrdinalIndex(name_in);
1215  if (param_idx != SIOVOCB::getInvalidOrdinal()) {
1216  return params_.getObjPtr(param_idx)->isType<T>();
1217  }
1218  return false;
1219 }
1220 #endif
1221 
1222 
1223 template<typename T>
1224 bool ParameterList::isType(const std::string& name_in) const
1225 {
1226  return this->isType(name_in, static_cast<T*>(0));
1227 }
1228 
1229 
1230 // Read-only access to the iterator
1231 
1232 
1234 {
1235  return params_.begin();
1236 }
1237 
1238 
1240 {
1241  return params_.end();
1242 }
1243 
1244 
1245 inline const std::string& ParameterList::name(ConstIterator i) const
1246 {
1247  return (i->first);
1248 }
1249 
1250 
1252 {
1253  return (i->second);
1254 }
1255 
1256 
1257 // private
1258 
1259 
1261 {
1262  return params_.nonconstBegin();
1263 }
1264 
1265 
1267 {
1268  return params_.nonconstEnd();
1269 }
1270 
1271 
1273 {
1274  return (i->second);
1275 }
1276 
1277 
1278 template<typename T>
1279 inline
1281  const std::string &/*funcName*/, const std::string &name_in,
1282  const ParameterEntry &entry_in
1283  ) const
1284 {
1286  entry_in.getAny().type() != typeid(T), Exceptions::InvalidParameterType
1287  ,"Error! An attempt was made to access parameter \""<<name_in<<"\""
1288  " of type \""<<entry_in.getAny().typeName()<<"\""
1289  "\nin the parameter (sub)list \""<<this->name()<<"\""
1290  "\nusing the incorrect type \""<<TypeNameTraits<T>::name()<<"\"!"
1291  );
1292 }
1293 
1294 
1295 // //////////////////////////////////////
1296 // Helper functions
1297 
1298 
1305 template<typename T>
1306 T& getParameter( ParameterList& l, const std::string& name )
1307 {
1308  return l.template get<T>(name);
1309 }
1310 
1311 
1317 template<typename T>
1318 inline
1319 T& get( ParameterList& l, const std::string& name )
1320 {
1321  return getParameter<T>(l,name);
1322 }
1323 
1324 
1331 template<typename T>
1332 const T& getParameter( const ParameterList& l, const std::string& name )
1333 {
1334  return l.template get<T>(name);
1335 }
1336 
1337 
1345 template<typename T>
1346 inline
1347 T* getParameterPtr( ParameterList& l, const std::string& name )
1348 {
1349  return l.template getPtr<T>(name);
1350 }
1351 
1352 
1360 template<typename T>
1361 inline
1362 const T* getParameterPtr( const ParameterList& l, const std::string& name )
1363 {
1364  return l.template getPtr<T>(name);
1365 }
1366 
1367 
1374 template<typename T>
1375 inline
1376 bool isParameterType( ParameterList& l, const std::string& name )
1377 {
1378  return l.isType( name, (T*)NULL );
1379 }
1380 
1381 
1388 template<typename T>
1389 inline
1390 bool isParameterType( const ParameterList& l, const std::string& name )
1391 {
1392  return l.isType( name, (T*)NULL );
1393 }
1394 
1395 
1407 template<typename T>
1409  const std::string &paramName
1410  ,const Array<T> &array
1411  ,ParameterList *paramList
1412  )
1413 {
1414  TEUCHOS_TEST_FOR_EXCEPT(!paramList);
1415  paramList->set(paramName,toString(array));
1416 }
1417 
1418 
1483 template<typename T>
1485  const ParameterList &paramList
1486  ,const std::string &paramName
1487  ,const int arrayDim = -1
1488  ,const bool mustExist = true
1489  )
1490 {
1491  std::string arrayStr;
1492  if(mustExist) {
1493  arrayStr = getParameter<std::string>(paramList,paramName);
1494  }
1495  else {
1496  const std::string
1497  *arrayStrPtr = getParameterPtr<std::string>(paramList,paramName);
1498  if(arrayStrPtr) {
1499  arrayStr = *arrayStrPtr;
1500  }
1501  else {
1502  return Array<T>(); // Return an empty array
1503  }
1504  }
1505  Array<T> a;
1506  try {
1507  a = fromStringToArray<T>(arrayStr);
1508  }
1509  catch( const InvalidArrayStringRepresentation&) {
1512  ,"Error! The parameter \""<<paramName<<"\"\n"
1513  "in the sublist \""<<paramList.name()<<"\"\n"
1514  "exists, but the std::string value:\n"
1515  "----------\n"
1516  <<arrayStr<<
1517  "\n----------\n"
1518  "is not a valid array represntation!"
1519  );
1520  }
1522  ( ( a.size()>0 && arrayDim>=0 ) && static_cast<int>(a.size())!=arrayDim )
1524  ,"Error! The parameter \""<<paramName<<"\"\n"
1525  "in the sublist \""<<paramList.name()<<"\"\n"
1526  "exists and is a valid array, but the dimension of\n"
1527  "the read in array a.size() = " << a.size() << "\n"
1528  "was not equal to the expected size arrayDim = " << arrayDim << "!"
1529  );
1530  return a;
1531 }
1532 
1533 
1546 template<typename T>
1547 bool replaceParameterWithArray(const std::string &paramName, const std::string &newName,
1548  ParameterList &pl)
1549 {
1550  bool param_exists = false;
1551  bool overwrite = false;
1552  if (paramName == newName){
1553  overwrite = true;
1554  }
1555  if (pl.isParameter(paramName)){
1556  param_exists = true;
1557  TEUCHOS_TEST_FOR_EXCEPTION(!pl.isType<T>(paramName), std::logic_error,
1558  "The parameter " << paramName << " is not of type " << typeid(T).name());
1559  TEUCHOS_TEST_FOR_EXCEPTION(pl.isParameter(newName) && !overwrite,
1560  std::logic_error, "The parameter " << newName << " already exists in this "
1561  "parameter list.");
1562  Array<T> params = tuple<T>(pl.get<T>(paramName));
1563  pl.remove(paramName);
1564  pl.set(newName, params);
1565  }
1566  return param_exists;
1567 }
1568 
1569 
1573 inline
1575  const RCP<ParameterList> &paramList, const std::string& name,
1576  bool mustAlreadyExist = false, const std::string& docString = ""
1577  )
1578 {
1579  return rcpWithEmbeddedObjPostDestroy(
1580  &paramList->sublist(name, mustAlreadyExist, docString), paramList, false );
1581 }
1582 
1583 
1587 inline
1589  const RCP<const ParameterList> &paramList, const std::string& name
1590  )
1591 {
1592  return rcpWithEmbeddedObjPostDestroy(
1593  &paramList->sublist(name), paramList, false );
1594 }
1595 
1596 
1600 inline std::ostream& operator<<(std::ostream& os, const ParameterList& l)
1601 {
1602  return l.print(os);
1603 }
1604 
1605 
1606 } // end of Teuchos namespace
1607 
1608 
1609 #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.
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.
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...