The MRPT project: CStream.h Source File

00001 /* +---------------------------------------------------------------------------+
00002    |          The Mobile Robot Programming Toolkit (MRPT) C++ library          |
00003    |                                                                           |
00004    |                   http://mrpt.sourceforge.net/                            |
00005    |                                                                           |
00006    |   Copyright (C) 2005-2010  University of Malaga                           |
00007    |                                                                           |
00008    |    This software was written by the Machine Perception and Intelligent    |
00009    |      Robotics Lab, University of Malaga (Spain).                          |
00010    |    Contact: Jose-Luis Blanco  <jlblanco@ctima.uma.es>                     |
00011    |                                                                           |
00012    |  This file is part of the MRPT project.                                   |
00013    |                                                                           |
00014    |     MRPT is free software: you can redistribute it and/or modify          |
00015    |     it under the terms of the GNU General Public License as published by  |
00016    |     the Free Software Foundation, either version 3 of the License, or     |
00017    |     (at your option) any later version.                                   |
00018    |                                                                           |
00019    |   MRPT is distributed in the hope that it will be useful,                 |
00020    |     but WITHOUT ANY WARRANTY; without even the implied warranty of        |
00021    |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         |
00022    |     GNU General Public License for more details.                          |
00023    |                                                                           |
00024    |     You should have received a copy of the GNU General Public License     |
00025    |     along with MRPT.  If not, see <http://www.gnu.org/licenses/>.         |
00026    |                                                                           |
00027    +---------------------------------------------------------------------------+ */
00028 #ifndef  CSTREAM_H
00029 #define  CSTREAM_H
00030 
00031 #include <mrpt/utils/utils_defs.h>
00032 #include <mrpt/utils/CUncopiable.h>
00033 #include <mrpt/utils/CObject.h>
00034 #include <mrpt/utils/exceptions.h>
00035 
00036 namespace mrpt
00037 {
00038         namespace utils
00039         {
00040                 class BASE_IMPEXP CSerializable;
00041                 struct BASE_IMPEXP  CSerializablePtr;
00042                 
00043                 /** This base class is used to provide a unified interface to
00044                  *    files,memory buffers,..Please see the derived classes. This class is
00045                  *    largely inspired by Borland VCL "TStream" class. <br><br>
00046                  *  Apart of the "VCL like" methods, operators ">>" and "<<" have been
00047                  *    defined so that simple types (int,bool,char,float,char *,std::string,...)
00048                  *    can be directly written and read to and from any CStream easily.
00049                  *  Please, it is recomendable to read CSerializable documentation also.
00050                  *
00051                  * \sa CFileStream, CMemoryStream,CSerializable
00052                  */
00053                 class BASE_IMPEXP CStream
00054                 {
00055                 public:
00056                         /** Used in CStream::Seek
00057                           */
00058                         enum TSeekOrigin
00059                         {
00060                                 sFromBeginning = 0,
00061                                 sFromCurrent = 1,
00062                                 sFromEnd = 2
00063                         };
00064 
00065                 protected:
00066                         /** Introduces a pure virtual method responsible for reading from the stream.
00067                          */
00068                         virtual size_t  Read(void *Buffer, size_t Count) = 0;
00069 
00070                         /** Introduces a pure virtual method responsible for writing to the stream.
00071                          *  Write attempts to write up to Count bytes to Buffer, and returns the number of bytes actually written.
00072                          */
00073                         virtual size_t  Write(const void *Buffer, size_t Count) = 0;
00074                 public:
00075                         /* Constructor
00076                          */
00077                         CStream() { }
00078 
00079                         /* Destructor
00080                          */
00081                         virtual ~CStream();
00082 
00083                         /** Reads a block of bytes from the stream into Buffer, and returns the amound of bytes actually read.
00084                          *      \exception std::exception On any error, or if ZERO bytes are read.
00085                          */
00086                         size_t  ReadBuffer(void *Buffer, size_t Count);
00087 
00088                         /** Writes a block of bytes to the stream from Buffer.
00089                          *      \exception std::exception On any error
00090                          */
00091                         void  WriteBuffer (const void *Buffer, size_t Count);
00092 
00093                         /** Copies a specified number of bytes from one stream to another.
00094                          */
00095                         size_t  CopyFrom(CStream* Source, size_t Count);
00096 
00097                         /** Introduces a pure virtual method for moving to a specified position in the streamed resource.
00098                          *   he Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:
00099                          *      - sFromBeginning        (Default) Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.
00100                          *      - sFromCurrent          Offset is from the current position in the resource. Seek moves to Position + Offset.
00101                          *      - sFromEnd                      Offset is from the end of the resource. Offset must be <= 0 to indicate a number of bytes before the end of the file.
00102                          * \return Seek returns the new value of the Position property.
00103                          */
00104                         virtual size_t Seek(long Offset, CStream::TSeekOrigin Origin = sFromBeginning) = 0;
00105 
00106                         /** Returns the total amount of bytes in the stream.
00107                          */
00108                         virtual size_t getTotalBytesCount() = 0;
00109 
00110                         /** Method for getting the current cursor position, where 0 is the first byte and TotalBytesCount-1 the last one.
00111                          */
00112                         virtual size_t getPosition() =0;
00113 
00114                         /** Writes an object to the stream.
00115                          */
00116                         void WriteObject( const CSerializable *o );
00117 
00118                         /** Reads an object from stream, its class determined at runtime, and returns a smart pointer to the object.
00119                          * \exception std::exception On I/O error or undefined class.
00120                          * \exception mrpt::utils::CExceptionEOF On an End-Of-File condition found at a correct place: an EOF that abruptly finishes in the middle of one object raises a plain std::exception instead.
00121                          */
00122                         CSerializablePtr ReadObject();
00123 
00124                         /** Reads an object from stream, where its class must be the same
00125                          *    as the supplied object, where the loaded object will be stored in.
00126                          * \exception std::exception On I/O error or different class found.
00127                          * \exception mrpt::utils::CExceptionEOF On an End-Of-File condition found at a correct place: an EOF that abruptly finishes in the middle of one object raises a plain std::exception instead.
00128                          */
00129                         void ReadObject(CSerializable *existingObj);
00130 
00131                         /** Write an object to a stream in the binary MRPT format. */
00132                         CStream& operator << (const CSerializablePtr & pObj);
00133                         /** Write an object to a stream in the binary MRPT format. */
00134                         CStream& operator << (const CSerializable &obj);
00135 
00136                         CStream& operator >> (CSerializablePtr &pObj);
00137                         CStream& operator >> (CSerializable &obj);
00138 
00139 
00140 
00141                         /** Writes a string to the stream in a textual form.
00142                           * \sa CStdOutStream
00143                           */
00144                         virtual int printf(const char *fmt,...) MRPT_printf_format_check(2,3);  // The first argument (1) is "this" !!!
00145 
00146                         /** Prints a vector in the format [A,B,C,...] using CStream::printf, and the fmt string for <b>each</b> vector element. */
00147                         template <typename T>
00148                         void printf_vector(const char *fmt, const std::vector<T> &V )
00149                         {
00150                                 this->printf("[");
00151                                 size_t N = V.size();
00152                                 for (size_t i=0;i<N;i++)
00153                                 {
00154                                         this->printf(fmt,V[i]);
00155                                         if (i!=(N-1)) this->printf(",");
00156                                 }
00157                                 this->printf("]");
00158                         }
00159 
00160                 }; // End of class def.
00161 
00162 
00163         #define DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( T ) \
00164                 BASE_IMPEXP CStream& operator<<(CStream&out, const T &a); \
00165                 BASE_IMPEXP CStream& operator>>(CStream&in, T &a);
00166 
00167                 // Definitions:
00168                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( bool )
00169                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( uint8_t )
00170                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( int8_t )
00171                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( uint16_t )
00172                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( int16_t )
00173                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( uint32_t )
00174                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( int32_t )
00175                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( uint64_t )
00176                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( int64_t )
00177                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( float )
00178                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( double )
00179 #ifdef HAVE_LONG_DOUBLE
00180                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( long double )
00181 #endif
00182 
00183                 // Why this shouldn't be templatized?: There's a more modern system
00184                 // in MRPT that serializes any kind of vector<T>, deque<T>, etc... but
00185                 // to keep COMPATIBILITY with old serialized objects we must preserve
00186                 // the ones listed here:
00187 
00188                 BASE_IMPEXP CStream& operator << (CStream&, const char *a);
00189                 BASE_IMPEXP CStream& operator << (CStream&, const std::string &str);
00190 
00191                 BASE_IMPEXP CStream& operator << (CStream&, const vector_int &a);
00192                 BASE_IMPEXP CStream& operator << (CStream&, const vector_uint &a);
00193                 BASE_IMPEXP CStream& operator << (CStream&, const vector_word &a);
00194                 BASE_IMPEXP CStream& operator << (CStream&, const vector_signed_word &a);
00195                 BASE_IMPEXP CStream& operator << (CStream&, const vector_long &a);
00196                 BASE_IMPEXP CStream& operator << (CStream&, const vector_float &a);
00197                 BASE_IMPEXP CStream& operator << (CStream&, const vector_double &a);
00198                 BASE_IMPEXP CStream& operator << (CStream&, const vector_byte &a);
00199                 BASE_IMPEXP CStream& operator << (CStream&, const vector_signed_byte &a);
00200                 BASE_IMPEXP CStream& operator << (CStream&, const vector_bool &a);
00201 
00202                 // For backward compatibility, since in MRPT<0.8.1 vector_XXX and std::vector<XXX> were exactly equivalent, now there're not.
00203                 inline CStream& operator << (CStream&s, const std::vector<float>  &a) { return s<<vector_float(a); }
00204                 inline CStream& operator << (CStream&s, const std::vector<double> &a) { return s<<vector_double(a); }
00205                 inline CStream& operator << (CStream&s, const std::vector<int8_t> &a) { return s<<vector_signed_byte(a); }
00206                 inline CStream& operator << (CStream&s, const std::vector<int16_t> &a) { return s<<vector_signed_word(a); }
00207                 inline CStream& operator << (CStream&s, const std::vector<int32_t> &a) { return s<<vector_int(a); }
00208                 inline CStream& operator << (CStream&s, const std::vector<int64_t> &a) { return s<<vector_long(a); }
00209                 inline CStream& operator << (CStream&s, const std::vector<uint8_t> &a) { return s<<vector_byte(a); }
00210                 inline CStream& operator << (CStream&s, const std::vector<uint16_t> &a) { return s<<vector_word(a); }
00211                 inline CStream& operator << (CStream&s, const std::vector<uint32_t> &a) { return s<<vector_uint(a); }
00212 
00213         #if MRPT_WORD_SIZE!=32  // If it's 32 bit, size_t <=> uint32_t
00214                 inline CStream& operator << (CStream&s, const std::vector<size_t> &a) { return s<<vector_size_t(a); }
00215         #endif
00216 
00217                 BASE_IMPEXP CStream& operator>>(CStream&in, char *a);
00218                 BASE_IMPEXP CStream& operator>>(CStream&in, std::string &str);
00219                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_int &a);
00220                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_uint &a);
00221                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_word &a);
00222                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_signed_word &a);
00223                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_long &a);
00224                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_double &a);
00225                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_float &a);
00226                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_byte &a);
00227                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_signed_byte &a);
00228                 BASE_IMPEXP CStream& operator>>(CStream&in, vector_bool &a);
00229                 BASE_IMPEXP CStream &operator<<(CStream &,const std::vector<std::string> &);
00230                 BASE_IMPEXP CStream &operator>>(CStream &,std::vector<std::string> &);
00231 
00232                 // For backward compatibility, since in MRPT<0.8.1 vector_XXX and std::vector<XXX> were exactly equivalent, now there're not.
00233                 inline CStream& operator >> (CStream&s, std::vector<float>  &a) { vector_float d; s>>d; a=d; return s; }
00234                 inline CStream& operator >> (CStream&s, std::vector<double> &a) { vector_double d; s>>d; a=d; return s; }
00235                 inline CStream& operator >> (CStream&s, std::vector<int8_t> &a) { vector_signed_byte d; s>>d; a=d; return s; }
00236                 inline CStream& operator >> (CStream&s, std::vector<int16_t> &a) { vector_signed_word d; s>>d; a=d; return s; }
00237                 inline CStream& operator >> (CStream&s, std::vector<int32_t> &a) { vector_int d; s>>d; a=d; return s; }
00238                 inline CStream& operator >> (CStream&s, std::vector<int64_t> &a) { vector_long d; s>>d; a=d; return s; }
00239                 inline CStream& operator >> (CStream&s, std::vector<uint8_t> &a) { vector_byte d; s>>d; a=d; return s; }
00240                 inline CStream& operator >> (CStream&s, std::vector<uint16_t> &a) { vector_word d; s>>d; a=d; return s; }
00241                 inline CStream& operator >> (CStream&s, std::vector<uint32_t> &a) { vector_uint d; s>>d; a=d; return s; }
00242 
00243         #if MRPT_WORD_SIZE!=32  // If it's 32 bit, size_t <=> uint32_t
00244                 inline CStream& operator >> (CStream&s, std::vector<size_t> &a) { vector_size_t d; s>>d; a=d; return s; }
00245         #endif
00246 
00247 
00248         } // End of namespace
00249 } // End of namespace
00250 
00251 #endif