Main MRPT website > C++ reference
MRPT logo
CSerializable.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | The Mobile Robot Programming Toolkit (MRPT) C++ library |
3  | |
4  | http://www.mrpt.org/ |
5  | |
6  | Copyright (C) 2005-2012 University of Malaga |
7  | |
8  | This software was written by the Machine Perception and Intelligent |
9  | Robotics Lab, University of Malaga (Spain). |
10  | Contact: Jose-Luis Blanco <jlblanco@ctima.uma.es> |
11  | |
12  | This file is part of the MRPT project. |
13  | |
14  | MRPT is free software: you can redistribute it and/or modify |
15  | it under the terms of the GNU General Public License as published by |
16  | the Free Software Foundation, either version 3 of the License, or |
17  | (at your option) any later version. |
18  | |
19  | MRPT is distributed in the hope that it will be useful, |
20  | but WITHOUT ANY WARRANTY; without even the implied warranty of |
21  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22  | GNU General Public License for more details. |
23  | |
24  | You should have received a copy of the GNU General Public License |
25  | along with MRPT. If not, see <http://www.gnu.org/licenses/>. |
26  | |
27  +---------------------------------------------------------------------------+ */
28 #ifndef CSERIALIZABLE_H
29 #define CSERIALIZABLE_H
30 
31 #include <mrpt/utils/CObject.h>
32 #include <mrpt/utils/CStream.h>
33 #include <mrpt/utils/safe_pointers.h>
34 
35 #include <set>
36 #include <list>
37 
38 namespace mrpt
39 {
40  /** Classes for serialization, sockets, ini-file manipulation, streams, list of properties-values, timewatch, extensions to STL.
41  * \ingroup mrpt_base_grp
42  */
43  namespace utils
44  {
45  DEFINE_MRPT_OBJECT_PRE( CSerializable )
46 
47  /** The virtual base class which provides a unified interface for all persistent objects in MRPT.
48  * Many important properties of this class are inherited from mrpt::utils::CObject. See that class for more details.
49  * Refer to the tutorial about <a href="http://www.mrpt.org/Serialization" >serialization</a> in the wiki.
50  * \sa CStream
51  * \ingroup mrpt_base_grp
52  */
53  class BASE_IMPEXP CSerializable : public mrpt::utils::CObject
54  {
55  // This must be added to any CObject derived class:
56  DEFINE_VIRTUAL_MRPT_OBJECT( CSerializable )
57 
58  virtual ~CSerializable() { }
59 
60  protected:
61  /** Introduces a pure virtual method responsible for writing to a CStream.
62  * This can not be used directly be users, instead use "stream << object;"
63  * for writing it to a stream.
64  * \param out The output binary stream where object must be dumped.
65  * \param getVersion If NULL, the object must be dumped. If not, only the
66  * version of the object dump must be returned in this pointer. This enables
67  * the versioning of objects dumping and backward compatibility with previously
68  * stored data.
69  * \exception std::exception On any error, see CStream::WriteBuffer
70  * \sa CStream
71  */
72  virtual void writeToStream(mrpt::utils::CStream &out, int *getVersion) const = 0;
73 
74  /** Introduces a pure virtual method responsible for loading from a CStream
75  * This can not be used directly be users, instead use "stream >> object;"
76  * for reading it from a stream or "stream >> object_ptr;" if the class is
77  * unknown apriori.
78  * \param in The input binary stream where the object data must read from.
79  * \param version The version of the object stored in the stream: use this version
80  * number in your code to know how to read the incoming data.
81  * \exception std::exception On any error, see CStream::ReadBuffer
82  * \sa CStream
83  */
84  virtual void readFromStream(mrpt::utils::CStream &in, int version) = 0;
85  }; // End of class def.
86 
87 
88  /** @name Non-streaming serialization functions
89  @{ */
90 
91  /** Used to pass MRPT objects into a CORBA-like object (strings). See doc about "Integration with BABEL".
92  * \param o The object to be serialized.
93  * \return The string containing the binay version of object.
94  * \sa StringToObject, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a>
95  */
96  std::string BASE_IMPEXP ObjectToString(const CSerializable *o);
97 
98  /** Used to pass CORBA-like objects (strings) into a MRPT object.
99  * \param str An string generated with ObjectToString
100  * \param obj A currently empty pointer, where a pointer to the newly created object will be stored.
101  * \exception None On any internal exception, this function returns NULL.
102  * \sa ObjectToString, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a>
103  */
104  void BASE_IMPEXP StringToObject(const std::string &str, CSerializablePtr &obj);
105 
106  /** Converts (serializes) an MRPT object into an array of bytes.
107  * \param o The object to be serialized.
108  * \param out_vector The vector which at return will contain the data. Size will be set automatically.
109  * \sa OctetVectorToObject, ObjectToString
110  */
111  void BASE_IMPEXP ObjectToOctetVector(const CSerializable *o, vector_byte & out_vector);
112 
113  /** Converts back (de-serializes) a sequence of binary data into a MRPT object, without prior information about the object's class.
114  * \param in_data The serialized input data representing the object.
115  * \param obj The newly created object will be stored in this smart pointer.
116  * \exception None On any internal exception, this function returns a NULL pointer.
117  * \sa ObjectToOctetVector, StringToObject
118  */
119  void BASE_IMPEXP OctetVectorToObject(const vector_byte & in_data, CSerializablePtr &obj);
120 
121  /** Converts (serializes) an MRPT object into an array of bytes within a std::string, without codifying to avoid NULL characters.
122  * This is therefore more efficient than ObjectToString
123  * \param o The object to be serialized.
124  * \param out_vector The string which at return will contain the data. Size will be set automatically.
125  * \sa RawStringToObject, ObjectToOctetVector
126  */
127  void BASE_IMPEXP ObjectToRawString(const CSerializable *o, std::string & out_str);
128 
129  /** Converts back (de-serializes) a sequence of binary data within a std::string into a MRPT object, without prior information about the object's class.
130  * \param in_data The serialized input data representing the object.
131  * \param obj The newly created object will be stored in this smart pointer.
132  * \exception None On any internal exception, this function returns a NULL pointer.
133  * \sa ObjectToRawString
134  */
135  void BASE_IMPEXP RawStringToObject(const std::string & in_str, CSerializablePtr &obj);
136 
137  /** @} */
138 
139 
140 
141  /** @name Conversion of type to string at compile time
142  * IMPORTANT: See also the implementation of Serialization for STL containers in mrpt/utils/stl_extensions.h
143  @{ */
144 
145  /** A template to obtain the type of its argument as a string at compile time.
146  * It works with all classes derived from CSerializable, plus many specializations for the plain data types (bool, double, uint8_t, etc...)
147  * For example:
148  * \code
149  * cout << TTypeName<double>::get() << endl; // "double"
150  * cout << TTypeName<CPose2D>::get() << endl; // "CPose2D"
151  * cout << TTypeName<mrpt::slam::COccupancyGridMap2D>::get() << endl; // "COccupancyGridMap2D"
152  * \endcode
153  *
154  * Users can extend this for custom structs/classes with the macro DECLARE_CUSTOM_TTYPENAME:
155  * \code
156  * class MyClass { ... };
157  * DECLARE_CUSTOM_TTYPENAME(MyClass)
158  * cout << TTypeName<MyClass>::get() << endl; // "MyClass"
159  * \endcode
160  *
161  * The following types are NOT ALLOWED since they have platform-dependant sizes:
162  * - int, unsigned int
163  * - long, unsigned long
164  * - short, unsigned short
165  * - size_t
166  *
167  */
168  template<typename T>
169  struct TTypeName
170  {
171  static std::string get() {
172  return std::string( T::classinfo->className );
173  }
174  };
175 
176  /** Identical to MRPT_DECLARE_TTYPENAME but intended for user code.
177  * MUST be placed at the GLOBAL namespace.
178  */
179  #define DECLARE_CUSTOM_TTYPENAME(_TYPE) \
180  namespace mrpt { namespace utils { MRPT_DECLARE_TTYPENAME(_TYPE) } }
181 
182  #define MRPT_DECLARE_TTYPENAME(_TYPE) \
183  template<> struct TTypeName <_TYPE > { \
184  static std::string get() { return std::string(#_TYPE); } };
185 
186  #define MRPT_DECLARE_TTYPENAME_PTR(_TYPE) \
187  template<> struct TTypeName <_TYPE##Ptr> { \
188  static std::string get() { return TTypeName<_TYPE>::get(); } };
189 
190  MRPT_DECLARE_TTYPENAME(bool)
191  MRPT_DECLARE_TTYPENAME(double)
192  MRPT_DECLARE_TTYPENAME(float)
193  MRPT_DECLARE_TTYPENAME(uint64_t)
194  MRPT_DECLARE_TTYPENAME(int64_t)
195  MRPT_DECLARE_TTYPENAME(uint32_t)
196  MRPT_DECLARE_TTYPENAME(int32_t)
197  MRPT_DECLARE_TTYPENAME(uint16_t)
198  MRPT_DECLARE_TTYPENAME(int16_t)
199  MRPT_DECLARE_TTYPENAME(uint8_t)
200  MRPT_DECLARE_TTYPENAME(int8_t)
201 
202  MRPT_DECLARE_TTYPENAME(std::string)
203 
204 
205  #define MRPT_DECLARE_TTYPENAME_CONTAINER(_CONTAINER) \
206  template< typename V > \
207  struct TTypeName <_CONTAINER<V> > { \
208  static std::string get() { \
209  return std::string( #_CONTAINER )+std::string("<")+std::string( TTypeName<V>::get() ) + std::string(">"); \
210  } \
211  };
212 
213  MRPT_DECLARE_TTYPENAME_CONTAINER( std::vector )
214  MRPT_DECLARE_TTYPENAME_CONTAINER( std::deque )
215  MRPT_DECLARE_TTYPENAME_CONTAINER( std::list )
216  MRPT_DECLARE_TTYPENAME_CONTAINER( std::set )
217 
218  // These ones act as a "translation" between vector_XXX types and their base classes:
219  #define MRPT_DECLARE_TTYPENAME_MAP_FOR_VECTOR(_CONT) \
220  template<> struct TTypeName <_CONT> : TTypeName<std::vector<_CONT::Scalar> > { };
221 
222  MRPT_DECLARE_TTYPENAME_MAP_FOR_VECTOR(vector_float)
223  MRPT_DECLARE_TTYPENAME_MAP_FOR_VECTOR(vector_double)
224 
225  // These ones are not needed since typedef's of "std::vector<>" are automatically supported
226  //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_signed_byte )
227  //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_signed_word)
228  //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_int)
229  //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_long)
230  //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_byte)
231  //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_word)
232  //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_uint)
233  //#if MRPT_WORD_SIZE!=32 // If it's 32 bit, size_t <=> uint32_t
234  //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_size_t)
235  //#endif
236 
237 
238  #define MRPT_DECLARE_TTYPENAME_CONTAINER_ASSOC(_CONTAINER) \
239  template< typename K, typename V > \
240  struct TTypeName <_CONTAINER<K,V> > { \
241  static std::string get() { \
242  return std::string( #_CONTAINER )+std::string("<")+std::string( TTypeName<K>::get() )+ std::string(",")+std::string( TTypeName<V>::get() )+std::string(">"); \
243  } \
244  };
245 
246  MRPT_DECLARE_TTYPENAME_CONTAINER_ASSOC( std::map )
247  MRPT_DECLARE_TTYPENAME_CONTAINER_ASSOC( std::multimap )
248 
249 
250  template< typename T1, typename T2 >
251  struct TTypeName <std::pair<T1,T2> > {
252  static std::string get() {
253  return std::string("std::pair<")+std::string( TTypeName<T1>::get() )+ std::string(",")+std::string( TTypeName<T2>::get() )+std::string(">");
254  }
255  };
256 
257  /** @} */
258 
259 
260  /** This declaration must be inserted in all CSerializable classes definition, within the class declaration.
261  */
262  #define DEFINE_SERIALIZABLE(class_name) \
263  DEFINE_MRPT_OBJECT(class_name) \
264  protected: \
265  /*! @name CSerializable virtual methods */ \
266  /*! @{ */ \
267  void writeToStream(mrpt::utils::CStream &out, int *getVersion) const;\
268  void readFromStream(mrpt::utils::CStream &in, int version); \
269  /*! @} */
270 
271  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
272  */
273  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_LINKAGE(class_name,_LINKAGE_) \
274  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, CSerializable, _LINKAGE_ class_name) \
275  _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
276 
277 
278  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
279  */
280  #define DEFINE_SERIALIZABLE_PRE(class_name) \
281  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, CSerializable, BASE_IMPEXP class_name) \
282  BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
283 
284  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
285  */
286  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_ ) \
287  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, base_name, _LINKAGE_ class_name) \
288  _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
289 
290 
291  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
292  */
293  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE(class_name, base_name) \
294  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, BASE_IMPEXP ) \
295  BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
296 
297  /** This must be inserted in all CSerializable classes implementation files:
298  */
299  #define IMPLEMENTS_SERIALIZABLE(class_name, base,NameSpace) \
300  IMPLEMENTS_MRPT_OBJECT(class_name, base,NameSpace) \
301  mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, NameSpace::class_name##Ptr &pObj) \
302  { pObj = NameSpace::class_name##Ptr( in.ReadObject() ); return in; }
303 
304  /** This declaration must be inserted in virtual CSerializable classes definition:
305  */
306  #define DEFINE_VIRTUAL_SERIALIZABLE(class_name) \
307  DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
308 
309  /** This must be inserted as implementation of some required members for
310  * virtual CSerializable classes:
311  */
312  #define IMPLEMENTS_VIRTUAL_SERIALIZABLE(class_name, base_class_name,NameSpace) \
313  IMPLEMENTS_VIRTUAL_MRPT_OBJECT(class_name, base_class_name,NameSpace) \
314  mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj) \
315  { pObj = class_name##Ptr( in.ReadObject() ); return in; }
316 
317 
318  } // End of namespace
319 } // End of namespace
320 
321 #endif


Page generated by Doxygen 1.8.3 for MRPT 0.9.6 SVN: at Fri Feb 15 22:05:02 EST 2013