iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ParameterStringConversion.H
Go to the documentation of this file.
1 /*! @file
2  @author Laurent Itti
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_CORE_MODEL_PARAMETERSTRINGCONVERSION_H
37 #define INCLUDE_NRT_CORE_MODEL_PARAMETERSTRINGCONVERSION_H
38 
39 #include <nrt/Core/Util/VectorUtils.H>
40 #include <string>
41 #include <iostream>
42 #include <sstream>
43 #include <vector>
44 
45 #include <nrt/config.h>
46 
47 #ifdef NRT_HAVE_EIGEN3
48 #include <nrt/Eigen/Eigen.H>
49 #endif // NRT_HAVE_EIGEN3
50 
51 namespace nrt
52 {
53 
54  /*! \defgroup parameterstrconv String conversions for Parameter
55  \ingroup parameter */
56 
57  /*! @{ */ // **********************************************************************
58 
59  //! Machine-readable conversion of T to a string, for use in nrt::Parameter
60  /*! A default implementation is provided which internally just uses boost::lexical_cast. When implementing new types
61  that can be used as parameters, users should supply the appropriate template specialization for this
62  function. This function is used internally by Parameter to get a Parameter value as string. */
63  template <class T>
64  void paramValToString(T const & val, std::string & result);
65 
66  //! Machine-readable conversion from string to T, for use in nrt::Parameter
67  /*! @throws Implementation-dependent exception encountered during conversion, if any, e.g., nrt::exception::Exception
68  or, for the default implementation, boost::bad_lexical_cast.
69 
70  A default implementation is provided which internally just uses boost::lexical_cast. When implementing new types
71  that can be used as parameters, users should supply the appropriate template specialization for this
72  function. This function is used internally by Parameter to set a Parameter value from string. */
73  template <class T>
74  void paramStringToVal(std::string const & valstring, T & result);
75 
76  //! Machine-readable output to a string, for use in nrt::Parameter: outputs [\c Element1, \c Element2, ...]
77  /*! Specialization for std::vector<T> which supports nesting of other vectors and vectors of other types
78  such as Dims and Points */
79  template <class Q>
80  void paramValToString(std::vector<Q> const & val, std::string & result);
81 
82  //! Machine-readable input from a string, for use in nrt::Parameter: reads [\c Element1, \c Element2, ...]
83  /*! @throws nrt::exception::Exception if input string is malformed.
84  Specialization for std::vector<T> which supports nesting of other vectors and vectors of other types
85  such as Dims and Points */
86  template <class Q>
87  void paramStringToVal(std::string const & valstring, std::vector<Q> & result);
88 
89  //! Machine-readable output to a string, for use in nrt::Parameter: outputs [\c Key1:Value1, \c Key2:Value2, ...]
90  /*! Specialization for std::map which supports nesting of other maps/vectors */
91  template <class K, class V>
92  void paramValToString(std::map<K,V> const & val, std::string & result);
93 
94  //! Machine-readable input from a string, for use in nrt::Parameter: reads [\c Key1:Value1, \c Key2:Value2, ...]
95  /*! @throws nrt::exception::Exception if input string is malformed.
96  Specialization for std::map which supports nesting of other maps/vectors */
97  template <class K, class V>
98  void paramStringToVal(std::string const & valstring, std::map<K,V> & result);
99 
100  //! Machine-readable conversion of bool to a string, for use in nrt::Parameter
101  /*! @returns "true" or "false". */
102  template <>
103  void paramValToString<bool>(bool const & val, std::string & result);
104 
105  //! Machine-readable conversion from string to bool, for use in nrt::Parameter
106  /*! @throws nrt::exception::Exception if input string is malformed.
107 
108  Specialization for bool so that we can accept nice verbose terms rather than just 0 and 1. Acceptable ways to set
109  a bool Parameter are:
110 
111  - "true" or "false"
112  - "t" or "f"
113  - "yes" or "no"
114  - "y" or "n"
115  - 1 or 0
116  - An empty string will set the Parameter to true, so you may use boolean parameters as switches, e.g.,
117  <code>"--myFlag"</code> is equivalent to <code>"--myFlag=true"</code> */
118  template <>
119  void paramStringToVal<bool>(std::string const & valstring, bool & result);
120 
121  //! Machine-readable conversion of string to a string, for use in nrt::Parameter
122  /*! This implementation just returns the original string. */
123  template <>
124  void paramValToString<std::string>(std::string const & val, std::string & result);
125 
126  //! Machine-readable conversion from string to string, for use in nrt::Parameter
127  /*! This implementation just returns the original string. */
128  template <>
129  void paramStringToVal<std::string>(std::string const & valstring, std::string & result);
130 
131 #ifdef NRT_HAVE_EIGEN3
132 
133  //! Convert from Eigen::Matrix to string for parameters, just wrap around Eigen's operator<<, replacing \n by ,
134  template <typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols>
135  void paramValToString(Eigen::Matrix<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> const & val,
136  std::string & result);
137 
138  //! Convert from string to Eigen::Matrix for parameters, matrix must already have correct size
139  template <typename _Scalar, int _Rows, int _Cols, int _Options, int _MaxRows, int _MaxCols>
140  void paramStringToVal(std::string const & valstring,
141  Eigen::Matrix<_Scalar, _Rows, _Cols, _Options, _MaxRows, _MaxCols> & result);
142 
143 #endif // NRT_HAVE_EIGEN3
144 
145 
146  /*! @} */ // **********************************************************************
147 
148 } // namespace nrt
149 
150 //! Include implementation details of no interest to the user
151 #include <nrt/Core/Model/details/ParameterStringConversionImpl.H>
152 
153 #endif // INCLUDE_NRT_CORE_MODEL_PARAMETERSTRINGCONVERSION_H
154