mistream.h

   1 // This file is part of the ustl library, an STL implementation.
   2 //
   3 // Copyright (C) 2005 by Mike Sharov <msharov@users.sourceforge.net>
   4 // This file is free software, distributed under the MIT License.
   5 //
   6 // mistream.h
   7 //
   8 #ifndef MISTREAM_H_103AEF1F266C04AA1A817D38705983DA
   9 #define MISTREAM_H_103AEF1F266C04AA1A817D38705983DA
  10
  11 #include "memlink.h"
  12 #include "uexception.h"
  13 #include "strmsize.h"
  14 #include "utf8.h"
  15 #include "uios.h"
  16 #ifdef WANT_STREAM_BOUNDS_CHECKING
  17     #include <typeinfo>
  18 #endif
  19
  20 namespace ustl {
  21
  22 class ostream;
  23 class memlink;
  24 class string;
  25
  26 /// \class istream mistream.h ustl.h
  27 /// \ingroup BinaryStreams
  28 ///
  29 /// \brief Helper class to read packed binary streams.
  30 ///
  31 /// This class contains a set of functions to read integral types from an
  32 /// unstructured memory block. Unpacking binary file data can be done this
  33 /// way, for instance. aligning the data is your responsibility, and can
  34 /// be accomplished by proper ordering of reads and by calling the align()
  35 /// function. Unaligned access is usually slower by orders of magnitude and,
  36 /// on some architectures, such as PowerPC, can cause your program to crash.
  37 /// Therefore, all read functions have asserts to check alignment.
  38 /// Overreading the end of the stream will also cause a crash (an assert in
  39 /// debug builds). Oh, and don't be intimidated by the size of the inlines
  40 /// here. In the assembly code the compiler will usually chop everything down
  41 /// to five instructions each.
  42 ///
  43 /// Alignment rules for your objects:
  44 ///     - Assume your writes start off 4-byte aligned.
  45 ///     - After completion, \ref istream::align the stream to at least 4.
  46 ///     - If data portability between 32bit and 64bit platforms is important
  47 ///     (it often is not, in config files and the like), ensure you are always
  48 ///     using fixed-size types and are aligning to a fixed grain. Avoid writing
  49 ///     8-byte types, and if you do, manually align before doing so.
  50 ///     - Non-default alignment is allowed if you plan to frequently write this
  51 ///     object in array form and alignment would be costly. For example, an
  52 ///     array of uint16_t-sized objects may leave the stream uint16_t aligned
  53 ///     as long as you know about it and will default-align the stream after
  54 ///     writing the array (note: \ref vector will already do this for you)
  55 ///
  56 /// Example code:
  57 /// \code
  58 ///     memblock b;
  59 ///     b.read_file ("test.file");
  60 ///     ostream is (b);
  61 ///     is >> boolVar >> ios::talign<int>();
  62 ///     is >> intVar >> floatVar;
  63 ///     is.read (binaryData, binaryDataSize);
  64 ///     is.align();
  65 /// \endcode
  66 ///
  67 class istream : public cmemlink, public ios_base {
  68 public:
  69                         istream (void);
  70                         istream (const void* p, size_type n);
  71     explicit            istream (const cmemlink& source);
  72     explicit            istream (const ostream& source);
  73     inline iterator     end (void) const                        { return (cmemlink::end()); }
  74     inline void         link (const void* p, size_type n)       { cmemlink::link (p, n); }
  75     inline void         link (const cmemlink& l)                { cmemlink::link (l.cdata(), l.readable_size()); }
  76     inline void         link (const void* f, const void* l)     { cmemlink::link (f, l); }
  77     inline void         relink (const void* p, size_type n)     { cmemlink::relink (p, n); m_Pos = 0; }
  78     inline void         relink (const cmemlink& l)              { relink (l.cdata(), l.readable_size()); }
  79     virtual void        unlink (void) throw();
  80     inline virtual size_type    underflow (size_type = 1)       { return (remaining()); }
  81     inline uoff_t       pos (void) const        { return (m_Pos); }
  82     inline const_iterator ipos (void) const     { return (begin() + pos()); }
  83     inline size_type    remaining (void) const  { return (size() - pos()); }
  84     inline void         seek (uoff_t newPos);
  85     inline void         iseek (const_iterator newPos);
  86     inline void         skip (size_type nBytes);
  87     inline bool         aligned (size_type grain = c_DefaultAlignment) const;
  88     void                verify_remaining (const char* op, const char* type, size_t n) const;
  89     inline size_type    align_size (size_type grain = c_DefaultAlignment) const;
  90     inline void         align (size_type grain = c_DefaultAlignment);
  91     void                swap (istream& is);
  92     void                read (void* buffer, size_type size);
  93     inline void         read (memlink& buf)     { read (buf.begin(), buf.writable_size()); }
  94     void                read_strz (string& str);
  95     size_type           readsome (void* s, size_type n);
  96     inline void         read (istream&)                 { }
  97     void                write (ostream& os) const;
  98     void                text_write (ostringstream& os) const;
  99     inline size_t       stream_size (void) const        { return (remaining()); }
 100     template <typename T>
 101     inline void         iread (T& v);
 102     inline void         ungetc (void)           { seek (pos() - 1); }
 103     inline off_t        tellg (void) const      { return (pos()); }
 104     inline void         seekg (off_t p, seekdir d = beg);
 105 private:
 106     uoff_t              m_Pos;          ///< The current read position.
 107 };
 108
 109 //----------------------------------------------------------------------
 110
 111 template <typename T, typename Stream>
 112 inline size_t required_stream_size (T, const Stream&) { return (1); }
 113 template <typename T>
 114 inline size_t required_stream_size (T v, const istream&) { return (stream_size_of(v)); }
 115
 116 template <typename Stream>
 117 inline bool stream_at_eof (const Stream& stm)   { return (stm.eof()); }
 118 template <>
 119 inline bool stream_at_eof (const istream&)      { return (false); }
 120
 121 /// \class istream_iterator
 122 /// \ingroup BinaryStreamIterators
 123 ///
 124 /// \brief An iterator over an istream to use with uSTL algorithms.
 125 ///
 126 template <typename T, typename Stream = istream>
 127 class istream_iterator {
 128 public:
 129     typedef T                   value_type;
 130     typedef ptrdiff_t           difference_type;
 131     typedef const value_type*   pointer;
 132     typedef const value_type&   reference;
 133     typedef size_t              size_type;
 134 public:
 135                                 istream_iterator (void)         : m_pis (NULL), m_v() {}
 136     explicit                    istream_iterator (Stream& is)   : m_pis (&is), m_v() { Read(); }
 137                                 istream_iterator (const istream_iterator& i)    : m_pis (i.m_pis), m_v (i.m_v) {}
 138     /// Reads and returns the next value.
 139     inline const T&             operator* (void)        { return (m_v); }
 140     inline istream_iterator&    operator++ (void)       { Read(); return (*this); }
 141     inline istream_iterator&    operator-- (void)       { m_pis->seek (m_pis->pos() - 2 * stream_size_of(m_v)); return (operator++()); }
 142     inline istream_iterator     operator++ (int)        { istream_iterator old (*this); operator++(); return (old); }
 143     inline istream_iterator     operator-- (int)        { istream_iterator old (*this); operator--(); return (old); }
 144     inline istream_iterator&    operator+= (size_type n)        { while (n--) operator++(); return (*this); }
 145     inline istream_iterator&    operator-= (size_type n)        { m_pis->seek (m_pis->pos() - (n + 1) * stream_size_of(m_v)); return (operator++()); }
 146     inline istream_iterator     operator- (size_type n) const                   { istream_iterator result (*this); return (result -= n); }
 147     inline difference_type      operator- (const istream_iterator& i) const     { return (distance (i.m_pis->pos(), m_pis->pos()) / stream_size_of(m_v)); }
 148     inline bool                 operator== (const istream_iterator& i) const    { return ((!m_pis && !i.m_pis) || (m_pis && i.m_pis && m_pis->pos() == i.m_pis->pos())); }
 149     inline bool                 operator< (const istream_iterator& i) const     { return (!i.m_pis || (m_pis && m_pis->pos() < i.m_pis->pos())); }
 150 private:
 151     void Read (void)
 152     {
 153         if (!m_pis)
 154             return;
 155         const size_t rs (required_stream_size (m_v, *m_pis));
 156         if (m_pis->remaining() < rs && m_pis->underflow (rs) < rs) {
 157             m_pis = NULL;
 158             return;
 159         }
 160         *m_pis >> m_v;
 161         if (stream_at_eof (*m_pis))
 162             m_pis = NULL;
 163     }
 164 private:
 165     Stream*     m_pis;          ///< The host stream.
 166     T           m_v;            ///< Last read value; cached to be returnable as a const reference.
 167 };
 168
 169 //----------------------------------------------------------------------
 170
 171 /// Sets the current read position to \p newPos
 172 inline void istream::seek (uoff_t newPos)
 173 {
 174 #ifdef WANT_STREAM_BOUNDS_CHECKING
 175     if (newPos > size())
 176         throw stream_bounds_exception ("seekg", "byte", pos(), newPos - pos(), size());
 177 #else
 178     assert (newPos <= size());
 179 #endif
 180     m_Pos = newPos;
 181 }
 182
 183 /// Sets the current read position to \p newPos
 184 inline void istream::iseek (const_iterator newPos)
 185 {
 186     seek (distance (begin(), newPos));
 187 }
 188
 189 /// Sets the current write position to \p p based on \p d.
 190 inline void istream::seekg (off_t p, seekdir d)
 191 {
 192     switch (d) {
 193         case beg:       seek (p); break;
 194         case cur:       seek (pos() + p); break;
 195         case ios_base::end:     seek (size() - p); break;
 196     }
 197 }
 198
 199 /// Skips \p nBytes without reading them.
 200 inline void istream::skip (size_type nBytes)
 201 {
 202     seek (pos() + nBytes);
 203 }
 204
 205 /// Returns the number of bytes to skip to be aligned on \p grain.
 206 inline istream::size_type istream::align_size (size_type grain) const
 207 {
 208     return (Align (pos(), grain) - pos());
 209 }
 210
 211 /// Returns \c true if the read position is aligned on \p grain
 212 inline bool istream::aligned (size_type grain) const
 213 {
 214     assert (uintptr_t(begin()) % grain == 0 && "Streams should be attached aligned at the maximum element grain to avoid bus errors.");
 215     return (pos() % grain == 0);
 216 }
 217
 218 /// aligns the read position on \p grain
 219 inline void istream::align (size_type grain)
 220 {
 221     seek (Align (pos(), grain));
 222 }
 223
 224 /// Reads type T from the stream via a direct pointer cast.
 225 template <typename T>
 226 inline void istream::iread (T& v)
 227 {
 228     assert (aligned (alignof (v)));
 229 #ifdef WANT_STREAM_BOUNDS_CHECKING
 230     verify_remaining ("read", typeid(v).name(), sizeof(T));
 231 #else
 232     assert (remaining() >= sizeof(T));
 233 #endif
 234     v = *reinterpret_cast<const T*>(ipos());
 235     m_Pos += sizeof(T);
 236 }
 237
 238 //----------------------------------------------------------------------
 239
 240 template <typename T> struct object_reader {
 241     inline void operator()(istream& is, T& v) const { v.read (is); }
 242 };
 243 template <typename T> struct integral_object_reader {
 244     inline void operator()(istream& is, T& v) const { is.iread (v); }
 245 };
 246 template <typename T>
 247 inline istream& operator>> (istream& is, T& v) {
 248     typedef typename tm::Select <numeric_limits<T>::is_integral,
 249         integral_object_reader<T>, object_reader<T> >::Result object_reader_t;
 250     object_reader_t()(is, v);
 251     return (is);
 252 }
 253 template <typename T>
 254 inline istream& operator>> (istream& is, const T& v) { v.read (is); return (is); }
 255
 256 //----------------------------------------------------------------------
 257
 258 typedef istream_iterator<utf8subchar_t> istream_iterator_for_utf8;
 259 typedef utf8in_iterator<istream_iterator_for_utf8> utf8istream_iterator;
 260
 261 /// Returns a UTF-8 adaptor reading from \p is.
 262 inline utf8istream_iterator utf8in (istream& is)
 263 {
 264     istream_iterator_for_utf8 si (is);
 265     return (utf8istream_iterator (si));
 266 }
 267
 268 //----------------------------------------------------------------------
 269
 270 } // namespace ustl
 271
 272 #endif
 273