The MRPT project: CStream.h Source File

Go to the documentation of this 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/exceptions.h>
00034 
00035 namespace mrpt
00036 {
00037         namespace utils
00038         {
00039                 class   MRPTDLLIMPEXP CSerializable;
00040                 struct  MRPTDLLIMPEXP TRuntimeClassId;
00041 
00042                 /** A smart pointer to a CRenderizable object */
00043                 typedef stlplus::smart_ptr_clone<CSerializable> CSerializablePtr;
00044 
00045 
00046                 /** This base class is used to provide a unified interface to
00047                  *    files,memory buffers,..Please see the derived classes. This class is
00048                  *    largely inspired by Borland VCL "TStream" class. <br><br>
00049                  *  Apart of the "VCL like" methods, operators ">>" and "<<" have been
00050                  *    defined so that simple types (int,bool,char,float,char *,std::string,...)
00051                  *    can be directly written and read to and from any CStream easily.
00052                  *  Please, it is recomendable to read CSerializable documentation also.
00053                  *
00054                  * \sa CFileStream, CMemoryStream,CSerializable
00055                  */
00056                 class MRPTDLLIMPEXP CStream
00057                 {
00058                 public:
00059                         /** Used in CStream::Seek
00060                           */
00061                         enum TSeekOrigin
00062                         {
00063                                 sFromBeginning = 0,
00064                                 sFromCurrent = 1,
00065                                 sFromEnd = 2
00066                         };
00067 
00068                 protected:
00069                         /** Introduces a pure virtual method responsible for reading from the stream.
00070                          */
00071                         virtual size_t  Read(void *Buffer, size_t Count) = 0;
00072 
00073                         /** Introduces a pure virtual method responsible for writing to the stream.
00074                          *  Write attempts to write up to Count bytes to Buffer, and returns the number of bytes actually written.
00075                          */
00076                         virtual size_t  Write(const void *Buffer, size_t Count) = 0;
00077                 public:
00078                         /* Constructor
00079                          */
00080                         CStream() { }
00081 
00082                         /* Destructor
00083                          */
00084                         virtual ~CStream();
00085 
00086                         /** Reads a block of bytes from the stream into Buffer, and returns the amound of bytes actually read.
00087                          *      \exception std::exception On any error, or if ZERO bytes are read.
00088                          */
00089                         size_t  ReadBuffer(void *Buffer, size_t Count);
00090 
00091                         /** Writes a block of bytes to the stream from Buffer.
00092                          *      \exception std::exception On any error
00093                          */
00094                         void  WriteBuffer (const void *Buffer, size_t Count);
00095 
00096                         /** Copies a specified number of bytes from one stream to another.
00097                          */
00098                         size_t  CopyFrom(CStream* Source, size_t Count);
00099 
00100                         /** Introduces a pure virtual method for moving to a specified position in the streamed resource.
00101                          *   he Origin parameter indicates how to interpret the Offset parameter. Origin should be one of the following values:
00102                          *      - sFromBeginning        (Default) Offset is from the beginning of the resource. Seek moves to the position Offset. Offset must be >= 0.
00103                          *      - sFromCurrent          Offset is from the current position in the resource. Seek moves to Position + Offset.
00104                          *      - 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.
00105                          * \return Seek returns the new value of the Position property.
00106                          */
00107                         virtual size_t Seek(long Offset, CStream::TSeekOrigin Origin = sFromBeginning) = 0;
00108 
00109                         /** Returns the total amount of bytes in the stream.
00110                          */
00111                         virtual size_t getTotalBytesCount() = 0;
00112 
00113                         /** Method for getting the current cursor position, where 0 is the first byte and TotalBytesCount-1 the last one.
00114                          */
00115                         virtual size_t getPosition() =0;
00116 
00117 
00118                         /** Write operator for objects
00119                           */
00120                         CStream& operator << (const CSerializablePtr& pObj);
00121                         /** Write operator for objects
00122                           */
00123                         CStream& operator << (const CSerializable &obj);
00124 
00125                         /** Read operator for objects
00126                           */
00127                         CStream& operator >> (CSerializablePtr &pObj);
00128 
00129                         /** Read operator for objects
00130                           */
00131                         CStream& operator >> (CSerializable &obj);
00132 
00133 
00134                         /** Writes an object to the stream.
00135                          */
00136                         void WriteObject( const CSerializable *o );
00137 
00138                         /** Reads an object from stream, its class determined at runtime, and returns a smart pointer to the object.
00139                          * \exception std::exception On I/O error or undefined class.
00140                          * \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.
00141                          */
00142                         CSerializablePtr ReadObject();
00143 
00144                         /** Reads an object from stream, where its class must be the same
00145                          *    as the supplied object, where the loaded object will be stored in.
00146                          * \exception std::exception On I/O error or different class found.
00147                          * \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.
00148                          */
00149                         void ReadObject(CSerializable *existingObj);
00150 
00151                         /** Writes a string to the stream in a textual form.
00152                           * \sa CStdOutStream
00153                           */
00154                         virtual int printf(const char *fmt,...) MRPT_printf_format_check(2,3);  // The first argument (1) is "this" !!!
00155 
00156                         /** Prints a vector in the format [A,B,C,...] using CStream::printf, and the fmt string for <b>each</b> vector element. */
00157                         template <typename T>
00158                         void printf_vector(const char *fmt, const std::vector<T> &V )
00159                         {
00160                                 this->printf("[");
00161                                 size_t N = V.size();
00162                                 for (size_t i=0;i<N;i++)
00163                                 {
00164                                         this->printf(fmt,V[i]);
00165                                         if (i!=(N-1)) this->printf(",");
00166                                 }
00167                                 this->printf("]");
00168                         }
00169 
00170                 }; // End of class def.
00171 
00172 
00173 
00174         #define DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( T ) \
00175                 MRPTDLLIMPEXP CStream& operator<<(CStream&out, const T &a); \
00176                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, T &a);
00177 
00178                 // Definitions:
00179                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( bool )
00180                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( uint8_t )
00181                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( int8_t )
00182                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( uint16_t )
00183                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( int16_t )
00184                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( uint32_t )
00185                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( int32_t )
00186                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( uint64_t )
00187                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( int64_t )
00188                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( float )
00189                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( double )
00190                 DECLARE_CSTREAM_READ_WRITE_SIMPLE_TYPE( long double )
00191 
00192                 // Why this shouldn't be templatized?: There's a more modern system
00193                 // in MRPT that serializes any kind of vector<T>, deque<T>, etc... but
00194                 // to keep COMPATIBILITY with old serialized objects we must preserve
00195                 // the ones listed here:
00196 
00197                 MRPTDLLIMPEXP CStream& operator << (CStream&, const char *a);
00198                 MRPTDLLIMPEXP CStream& operator << (CStream&, const std::string &str);
00199 
00200                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_int &a);
00201                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_uint &a);
00202                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_word &a);
00203                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_signed_word &a);
00204                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_long &a);
00205                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_float &a);
00206                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_double &a);
00207                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_byte &a);
00208                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_signed_byte &a);
00209                 MRPTDLLIMPEXP CStream& operator << (CStream&, const vector_bool &a);
00210 
00211                 // For backward compatibility, since in MRPT<0.8.1 vector_XXX and std::vector<XXX> were exactly equivalent, now there're not.
00212                 inline CStream& operator << (CStream&s, const std::vector<float>  &a) { return s<<vector_float(a); }
00213                 inline CStream& operator << (CStream&s, const std::vector<double> &a) { return s<<vector_double(a); }
00214                 inline CStream& operator << (CStream&s, const std::vector<int8_t> &a) { return s<<vector_signed_byte(a); }
00215                 inline CStream& operator << (CStream&s, const std::vector<int16_t> &a) { return s<<vector_signed_word(a); }
00216                 inline CStream& operator << (CStream&s, const std::vector<int32_t> &a) { return s<<vector_int(a); }
00217                 inline CStream& operator << (CStream&s, const std::vector<int64_t> &a) { return s<<vector_long(a); }
00218                 inline CStream& operator << (CStream&s, const std::vector<uint8_t> &a) { return s<<vector_byte(a); }
00219                 inline CStream& operator << (CStream&s, const std::vector<uint16_t> &a) { return s<<vector_word(a); }
00220                 inline CStream& operator << (CStream&s, const std::vector<uint32_t> &a) { return s<<vector_uint(a); }
00221 
00222         #if MRPT_WORD_SIZE!=32  // If it's 32 bit, size_t <=> uint32_t
00223                 inline CStream& operator << (CStream&s, const std::vector<size_t> &a) { return s<<vector_size_t(a); }
00224         #endif
00225 
00226                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, char *a);
00227                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, std::string &str);
00228                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_int &a);
00229                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_uint &a);
00230                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_word &a);
00231                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_signed_word &a);
00232                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_long &a);
00233                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_double &a);
00234                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_float &a);
00235                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_byte &a);
00236                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_signed_byte &a);
00237                 MRPTDLLIMPEXP CStream& operator>>(CStream&in, vector_bool &a);
00238                 MRPTDLLIMPEXP CStream &operator<<(CStream &,const std::vector<std::string> &);
00239                 MRPTDLLIMPEXP CStream &operator>>(CStream &,std::vector<std::string> &);
00240 
00241                 // For backward compatibility, since in MRPT<0.8.1 vector_XXX and std::vector<XXX> were exactly equivalent, now there're not.
00242                 inline CStream& operator >> (CStream&s, std::vector<float>  &a) { vector_float d; s>>d; a=d; return s; }
00243                 inline CStream& operator >> (CStream&s, std::vector<double> &a) { vector_double d; s>>d; a=d; return s; }
00244                 inline CStream& operator >> (CStream&s, std::vector<int8_t> &a) { vector_signed_byte d; s>>d; a=d; return s; }
00245                 inline CStream& operator >> (CStream&s, std::vector<int16_t> &a) { vector_signed_word d; s>>d; a=d; return s; }
00246                 inline CStream& operator >> (CStream&s, std::vector<int32_t> &a) { vector_int d; s>>d; a=d; return s; }
00247                 inline CStream& operator >> (CStream&s, std::vector<int64_t> &a) { vector_long d; s>>d; a=d; return s; }
00248                 inline CStream& operator >> (CStream&s, std::vector<uint8_t> &a) { vector_byte d; s>>d; a=d; return s; }
00249                 inline CStream& operator >> (CStream&s, std::vector<uint16_t> &a) { vector_word d; s>>d; a=d; return s; }
00250                 inline CStream& operator >> (CStream&s, std::vector<uint32_t> &a) { vector_uint d; s>>d; a=d; return s; }
00251 
00252         #if MRPT_WORD_SIZE!=32  // If it's 32 bit, size_t <=> uint32_t
00253                 inline CStream& operator >> (CStream&s, std::vector<size_t> &a) { vector_size_t d; s>>d; a=d; return s; }
00254         #endif
00255 
00256 
00257         } // End of namespace
00258 } // End of namespace
00259 
00260 #endif