libstdc++-v3/include/std/std_sstream.h

   1 // String based streams -*- C++ -*-
   2
   3 // Copyright (C) 1997, 1998, 1999, 2002, 2003 Free Software Foundation, Inc.
   4 //
   5 // This file is part of the GNU ISO C++ Library.  This library is free
   6 // software; you can redistribute it and/or modify it under the
   7 // terms of the GNU General Public License as published by the
   8 // Free Software Foundation; either version 2, or (at your option)
   9 // any later version.
  10
  11 // This library is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15
  16 // You should have received a copy of the GNU General Public License along
  17 // with this library; see the file COPYING.  If not, write to the Free
  18 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  19 // USA.
  20
  21 // As a special exception, you may use this file as part of a free software
  22 // library without restriction.  Specifically, if other files instantiate
  23 // templates or use macros or inline functions from this file, or you compile
  24 // this file and link it with other files to produce an executable, this
  25 // file does not by itself cause the resulting executable to be covered by
  26 // the GNU General Public License.  This exception does not however
  27 // invalidate any other reasons why the executable file might be covered by
  28 // the GNU General Public License.
  29
  30 //
  31 // ISO C++ 14882: 27.7  String-based streams
  32 //
  33
  34 /** @file sstream
  35  *  This is a Standard C++ Library header.  You should @c #include this header
  36  *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
  37  */
  38
  39 #ifndef _GLIBCXX_SSTREAM
  40 #define _GLIBCXX_SSTREAM 1
  41
  42 #pragma GCC system_header
  43
  44 #include <istream>
  45 #include <ostream>
  46
  47 namespace std
  48 {
  49   // [27.7.1] template class basic_stringbuf
  50   /**
  51    *  @brief  The actual work of input and output (for std::string).
  52    *
  53    *  This class associates either or both of its input and output sequences
  54    *  with a sequence of characters, which can be initialized from, or made
  55    *  available as, a @c std::basic_string.  (Paraphrased from [27.7.1]/1.)
  56    *
  57    *  For this class, open modes (of type @c ios_base::openmode) have
  58    *  @c in set if the input sequence can be read, and @c out set if the
  59    *  output sequence can be written.
  60   */
  61   template<typename _CharT, typename _Traits, typename _Alloc>
  62     class basic_stringbuf : public basic_streambuf<_CharT, _Traits>
  63     {
  64     public:
  65       // Types:
  66       typedef _CharT                                    char_type;
  67       typedef _Traits                                   traits_type;
  68 #ifdef _GLIBCXX_RESOLVE_LIB_DEFECTS
  69 // 251. basic_stringbuf missing allocator_type
  70       typedef _Alloc                                    allocator_type;
  71 #endif
  72       typedef typename traits_type::int_type            int_type;
  73       typedef typename traits_type::pos_type            pos_type;
  74       typedef typename traits_type::off_type            off_type;
  75
  76       //@{
  77       /**
  78        *  @if maint
  79        *  @doctodo
  80        *  @endif
  81       */
  82       typedef basic_streambuf<char_type, traits_type>   __streambuf_type;
  83       typedef basic_string<char_type, _Traits, _Alloc>  __string_type;
  84       typedef typename __string_type::size_type         __size_type;
  85       //@}
  86
  87     protected:
  88       /**
  89        *  @if maint
  90        *  Place to stash in || out || in | out settings for current stringbuf.
  91        *  @endif
  92       */
  93       ios_base::openmode        _M_mode;
  94
  95       // Data Members:
  96       /**
  97        *  @if maint
  98        *  @doctodo
  99        *  @endif
 100       */
 101       __string_type             _M_string;
 102
 103     public:
 104       // Constructors:
 105       /**
 106        *  @brief  Starts with an empty string buffer.
 107        *  @param  mode  Whether the buffer can read, or write, or both.
 108        *
 109        *  The default constructor initializes the parent class using its
 110        *  own default ctor.
 111       */
 112       explicit
 113       basic_stringbuf(ios_base::openmode __mode = ios_base::in | ios_base::out)
 114       : __streambuf_type(), _M_string()
 115       { _M_stringbuf_init(__mode); }
 116
 117       /**
 118        *  @brief  Starts with an existing string buffer.
 119        *  @param  str  A string to copy as a starting buffer.
 120        *  @param  mode  Whether the buffer can read, or write, or both.
 121        *
 122        *  This constructor initializes the parent class using its
 123        *  own default ctor.
 124       */
 125       explicit
 126       basic_stringbuf(const __string_type& __str,
 127                       ios_base::openmode __mode = ios_base::in | ios_base::out)
 128       : __streambuf_type(), _M_string(__str.data(), __str.size())
 129       { _M_stringbuf_init(__mode); }
 130
 131       // Get and set:
 132       /**
 133        *  @brief  Copying out the string buffer.
 134        *  @return  A copy of one of the underlying sequences.
 135        *
 136        *  "If the buffer is only created in input mode, the underlying
 137        *  character sequence is equal to the input sequence; otherwise, it
 138        *  is equal to the output sequence." [27.7.1.2]/1
 139       */
 140       __string_type
 141       str() const
 142       {
 143         const bool __testout = this->_M_mode & ios_base::out;
 144         if (__testout)
 145           {
 146             // The current egptr() may not be the actual string end.
 147             if (this->pptr() > this->egptr())
 148               return __string_type(this->pbase(), this->pptr());
 149             else
 150               return __string_type(this->pbase(), this->egptr());
 151           }
 152         else
 153           return _M_string;
 154       }
 155
 156       /**
 157        *  @brief  Setting a new buffer.
 158        *  @param  s  The string to use as a new sequence.
 159        *
 160        *  Deallocates any previous stored sequence, then copies @a s to
 161        *  use as a new one.
 162       */
 163       void
 164       str(const __string_type& __s)
 165       {
 166         // Cannot use _M_string = __s, since v3 strings are COW.
 167         _M_string.assign(__s.data(), __s.size());
 168         _M_stringbuf_init(this->_M_mode);
 169       }
 170
 171     protected:
 172       // Common initialization code for both ctors goes here.
 173       /**
 174        *  @if maint
 175        *  @doctodo
 176        *  @endif
 177       */
 178       void
 179       _M_stringbuf_init(ios_base::openmode __mode)
 180       {
 181         this->_M_mode = __mode;
 182
 183         __size_type __len = 0;
 184         if (this->_M_mode & (ios_base::ate | ios_base::app))
 185           __len = _M_string.size();
 186         _M_sync(const_cast<char_type*>(_M_string.data()), 0, __len);
 187       }
 188
 189       // [documentation is inherited]
 190       virtual int_type
 191       underflow();
 192
 193       // [documentation is inherited]
 194       virtual int_type
 195       pbackfail(int_type __c = traits_type::eof());
 196
 197       // [documentation is inherited]
 198       virtual int_type
 199       overflow(int_type __c = traits_type::eof());
 200
 201       /**
 202        *  @brief  Manipulates the buffer.
 203        *  @param  s  Pointer to a buffer area.
 204        *  @param  n  Size of @a s.
 205        *  @return  @c this
 206        *
 207        *  If no buffer has already been created, and both @a s and @a n are
 208        *  non-zero, then @c s is used as a buffer; see
 209        *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2
 210        *  for more.
 211       */
 212       virtual __streambuf_type*
 213       setbuf(char_type* __s, streamsize __n)
 214       {
 215         if (__s && __n >= 0)
 216           {
 217             // This is implementation-defined behavior, and assumes
 218             // that an external char_type array of length __n exists
 219             // and has been pre-allocated. If this is not the case,
 220             // things will quickly blow up.
 221
 222             // Step 1: Destroy the current internal array.
 223             _M_string = __string_type(__s, __n);
 224
 225             // Step 2: Use the external array.
 226             _M_sync(__s, 0, 0);
 227           }
 228         return this;
 229       }
 230
 231       // [documentation is inherited]
 232       virtual pos_type
 233       seekoff(off_type __off, ios_base::seekdir __way,
 234               ios_base::openmode __mode = ios_base::in | ios_base::out);
 235
 236       // [documentation is inherited]
 237       virtual pos_type
 238       seekpos(pos_type __sp,
 239               ios_base::openmode __mode = ios_base::in | ios_base::out);
 240
 241       // Internal function for correctly updating the internal buffer
 242       // for a particular _M_string, due to initialization or
 243       // re-sizing of an existing _M_string.
 244       // Assumes: contents of _M_string and internal buffer match exactly.
 245       // __i == _M_in_cur - _M_in_beg
 246       // __o == _M_out_cur - _M_out_beg
 247       /**
 248        *  @if maint
 249        *  @doctodo
 250        *  @endif
 251       */
 252       void
 253       _M_sync(char_type* __base, __size_type __i, __size_type __o)
 254       {
 255         const bool __testin = this->_M_mode & ios_base::in;
 256         const bool __testout = this->_M_mode & ios_base::out;
 257         const __size_type __len = _M_string.size();
 258
 259         if (__testin)
 260           this->setg(__base, __base + __i, __base + __len);
 261         if (__testout)
 262           {
 263             this->setp(__base, __base + _M_string.capacity());
 264             this->pbump(__o);
 265             // We need a pointer to the string end anyway, even when
 266             // !__testin: in that case, however, for the correct
 267             // functioning of the streambuf inlines all the get area
 268             // pointers must be identical.
 269             if (!__testin)
 270               this->setg(__base + __len, __base + __len, __base + __len);
 271           }
 272       }
 273
 274       // Internal function for correctly updating egptr() to the actual
 275       // string end.
 276       void
 277       _M_update_egptr()
 278       {
 279         const bool __testin = this->_M_mode & ios_base::in;
 280         const bool __testout = this->_M_mode & ios_base::out;
 281
 282         if (__testout && this->pptr() > this->egptr())
 283           if (__testin)
 284             this->setg(this->eback(), this->gptr(), this->pptr());
 285           else
 286             this->setg(this->pptr(), this->pptr(), this->pptr());
 287       }
 288     };
 289
 290
 291   // [27.7.2] Template class basic_istringstream
 292   /**
 293    *  @brief  Controlling input for std::string.
 294    *
 295    *  This class supports reading from objects of type std::basic_string,
 296    *  using the inherited functions from std::basic_istream.  To control
 297    *  the associated sequence, an instance of std::basic_stringbuf is used,
 298    *  which this page refers to as @c sb.
 299   */
 300   template<typename _CharT, typename _Traits, typename _Alloc>
 301     class basic_istringstream : public basic_istream<_CharT, _Traits>
 302     {
 303     public:
 304       // Types:
 305       typedef _CharT                                    char_type;
 306       typedef _Traits                                   traits_type;
 307 #ifdef _GLIBCXX_RESOLVE_LIB_DEFECTS
 308 // 251. basic_stringbuf missing allocator_type
 309       typedef _Alloc                                    allocator_type;
 310 #endif
 311       typedef typename traits_type::int_type            int_type;
 312       typedef typename traits_type::pos_type            pos_type;
 313       typedef typename traits_type::off_type            off_type;
 314
 315       // Non-standard types:
 316       typedef basic_string<_CharT, _Traits, _Alloc>     __string_type;
 317       typedef basic_stringbuf<_CharT, _Traits, _Alloc>  __stringbuf_type;
 318       typedef basic_istream<char_type, traits_type>     __istream_type;
 319
 320     private:
 321       /**
 322        *  @if maint
 323        *  @doctodo
 324        *  @endif
 325       */
 326       __stringbuf_type  _M_stringbuf;
 327
 328     public:
 329       // Constructors:
 330       /**
 331        *  @brief  Default constructor starts with an empty string buffer.
 332        *  @param  mode  Whether the buffer can read, or write, or both.
 333        *
 334        *  @c ios_base::in is automatically included in @a mode.
 335        *
 336        *  Initializes @c sb using @c mode|in, and passes @c &sb to the base
 337        *  class initializer.  Does not allocate any buffer.
 338        *
 339        *  @if maint
 340        *  That's a lie.  We initialize the base class with NULL, because the
 341        *  string class does its own memory management.
 342        *  @endif
 343       */
 344       explicit
 345       basic_istringstream(ios_base::openmode __mode = ios_base::in)
 346       : __istream_type(), _M_stringbuf(__mode | ios_base::in)
 347       { this->init(&_M_stringbuf); }
 348
 349       /**
 350        *  @brief  Starts with an existing string buffer.
 351        *  @param  str  A string to copy as a starting buffer.
 352        *  @param  mode  Whether the buffer can read, or write, or both.
 353        *
 354        *  @c ios_base::in is automatically included in @a mode.
 355        *
 356        *  Initializes @c sb using @a str and @c mode|in, and passes @c &sb
 357        *  to the base class initializer.
 358        *
 359        *  @if maint
 360        *  That's a lie.  We initialize the base class with NULL, because the
 361        *  string class does its own memory management.
 362        *  @endif
 363       */
 364       explicit
 365       basic_istringstream(const __string_type& __str,
 366                           ios_base::openmode __mode = ios_base::in)
 367       : __istream_type(), _M_stringbuf(__str, __mode | ios_base::in)
 368       { this->init(&_M_stringbuf); }
 369
 370       /**
 371        *  @brief  The destructor does nothing.
 372        *
 373        *  The buffer is deallocated by the stringbuf object, not the
 374        *  formatting stream.
 375       */
 376       ~basic_istringstream()
 377       { }
 378
 379       // Members:
 380       /**
 381        *  @brief  Accessing the underlying buffer.
 382        *  @return  The current basic_stringbuf buffer.
 383        *
 384        *  This hides both signatures of std::basic_ios::rdbuf().
 385       */
 386       __stringbuf_type*
 387       rdbuf() const
 388       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 389
 390       /**
 391        *  @brief  Copying out the string buffer.
 392        *  @return  @c rdbuf()->str()
 393       */
 394       __string_type
 395       str() const
 396       { return _M_stringbuf.str(); }
 397
 398       /**
 399        *  @brief  Setting a new buffer.
 400        *  @param  s  The string to use as a new sequence.
 401        *
 402        *  Calls @c rdbuf()->str(s).
 403       */
 404       void
 405       str(const __string_type& __s)
 406       { _M_stringbuf.str(__s); }
 407     };
 408
 409
 410   // [27.7.3] Template class basic_ostringstream
 411   /**
 412    *  @brief  Controlling output for std::string.
 413    *
 414    *  This class supports writing to objects of type std::basic_string,
 415    *  using the inherited functions from std::basic_ostream.  To control
 416    *  the associated sequence, an instance of std::basic_stringbuf is used,
 417    *  which this page refers to as @c sb.
 418   */
 419   template <typename _CharT, typename _Traits, typename _Alloc>
 420     class basic_ostringstream : public basic_ostream<_CharT, _Traits>
 421     {
 422     public:
 423       // Types:
 424       typedef _CharT                                    char_type;
 425       typedef _Traits                                   traits_type;
 426 #ifdef _GLIBCXX_RESOLVE_LIB_DEFECTS
 427 // 251. basic_stringbuf missing allocator_type
 428       typedef _Alloc                                    allocator_type;
 429 #endif
 430       typedef typename traits_type::int_type            int_type;
 431       typedef typename traits_type::pos_type            pos_type;
 432       typedef typename traits_type::off_type            off_type;
 433
 434       // Non-standard types:
 435       typedef basic_string<_CharT, _Traits, _Alloc>     __string_type;
 436       typedef basic_stringbuf<_CharT, _Traits, _Alloc>  __stringbuf_type;
 437       typedef basic_ostream<char_type, traits_type>     __ostream_type;
 438
 439     private:
 440       /**
 441        *  @if maint
 442        *  @doctodo
 443        *  @endif
 444       */
 445       __stringbuf_type  _M_stringbuf;
 446
 447     public:
 448       // Constructors/destructor:
 449       /**
 450        *  @brief  Default constructor starts with an empty string buffer.
 451        *  @param  mode  Whether the buffer can read, or write, or both.
 452        *
 453        *  @c ios_base::out is automatically included in @a mode.
 454        *
 455        *  Initializes @c sb using @c mode|out, and passes @c &sb to the base
 456        *  class initializer.  Does not allocate any buffer.
 457        *
 458        *  @if maint
 459        *  That's a lie.  We initialize the base class with NULL, because the
 460        *  string class does its own memory management.
 461        *  @endif
 462       */
 463       explicit
 464       basic_ostringstream(ios_base::openmode __mode = ios_base::out)
 465       : __ostream_type(), _M_stringbuf(__mode | ios_base::out)
 466       { this->init(&_M_stringbuf); }
 467
 468       /**
 469        *  @brief  Starts with an existing string buffer.
 470        *  @param  str  A string to copy as a starting buffer.
 471        *  @param  mode  Whether the buffer can read, or write, or both.
 472        *
 473        *  @c ios_base::out is automatically included in @a mode.
 474        *
 475        *  Initializes @c sb using @a str and @c mode|out, and passes @c &sb
 476        *  to the base class initializer.
 477        *
 478        *  @if maint
 479        *  That's a lie.  We initialize the base class with NULL, because the
 480        *  string class does its own memory management.
 481        *  @endif
 482       */
 483       explicit
 484       basic_ostringstream(const __string_type& __str,
 485                           ios_base::openmode __mode = ios_base::out)
 486       : __ostream_type(), _M_stringbuf(__str, __mode | ios_base::out)
 487       { this->init(&_M_stringbuf); }
 488
 489       /**
 490        *  @brief  The destructor does nothing.
 491        *
 492        *  The buffer is deallocated by the stringbuf object, not the
 493        *  formatting stream.
 494       */
 495       ~basic_ostringstream()
 496       { }
 497
 498       // Members:
 499       /**
 500        *  @brief  Accessing the underlying buffer.
 501        *  @return  The current basic_stringbuf buffer.
 502        *
 503        *  This hides both signatures of std::basic_ios::rdbuf().
 504       */
 505       __stringbuf_type*
 506       rdbuf() const
 507       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 508
 509       /**
 510        *  @brief  Copying out the string buffer.
 511        *  @return  @c rdbuf()->str()
 512       */
 513       __string_type
 514       str() const
 515       { return _M_stringbuf.str(); }
 516
 517       /**
 518        *  @brief  Setting a new buffer.
 519        *  @param  s  The string to use as a new sequence.
 520        *
 521        *  Calls @c rdbuf()->str(s).
 522       */
 523       void
 524       str(const __string_type& __s)
 525       { _M_stringbuf.str(__s); }
 526     };
 527
 528
 529   // [27.7.4] Template class basic_stringstream
 530   /**
 531    *  @brief  Controlling input and output for std::string.
 532    *
 533    *  This class supports reading from and writing to objects of type
 534    *  std::basic_string, using the inherited functions from
 535    *  std::basic_iostream.  To control the associated sequence, an instance
 536    *  of std::basic_stringbuf is used, which this page refers to as @c sb.
 537   */
 538   template <typename _CharT, typename _Traits, typename _Alloc>
 539     class basic_stringstream : public basic_iostream<_CharT, _Traits>
 540     {
 541     public:
 542       // Types:
 543       typedef _CharT                                    char_type;
 544       typedef _Traits                                   traits_type;
 545 #ifdef _GLIBCXX_RESOLVE_LIB_DEFECTS
 546 // 251. basic_stringbuf missing allocator_type
 547       typedef _Alloc                                    allocator_type;
 548 #endif
 549       typedef typename traits_type::int_type            int_type;
 550       typedef typename traits_type::pos_type            pos_type;
 551       typedef typename traits_type::off_type            off_type;
 552
 553       // Non-standard Types:
 554       typedef basic_string<_CharT, _Traits, _Alloc>     __string_type;
 555       typedef basic_stringbuf<_CharT, _Traits, _Alloc>  __stringbuf_type;
 556       typedef basic_iostream<char_type, traits_type>    __iostream_type;
 557
 558     private:
 559       /**
 560        *  @if maint
 561        *  @doctodo
 562        *  @endif
 563       */
 564       __stringbuf_type  _M_stringbuf;
 565
 566     public:
 567       // Constructors/destructors
 568       /**
 569        *  @brief  Default constructor starts with an empty string buffer.
 570        *  @param  mode  Whether the buffer can read, or write, or both.
 571        *
 572        *  Initializes @c sb using @c mode, and passes @c &sb to the base
 573        *  class initializer.  Does not allocate any buffer.
 574        *
 575        *  @if maint
 576        *  That's a lie.  We initialize the base class with NULL, because the
 577        *  string class does its own memory management.
 578        *  @endif
 579       */
 580       explicit
 581       basic_stringstream(ios_base::openmode __m = ios_base::out | ios_base::in)
 582       : __iostream_type(), _M_stringbuf(__m)
 583       { this->init(&_M_stringbuf); }
 584
 585       /**
 586        *  @brief  Starts with an existing string buffer.
 587        *  @param  str  A string to copy as a starting buffer.
 588        *  @param  mode  Whether the buffer can read, or write, or both.
 589        *
 590        *  Initializes @c sb using @a str and @c mode, and passes @c &sb
 591        *  to the base class initializer.
 592        *
 593        *  @if maint
 594        *  That's a lie.  We initialize the base class with NULL, because the
 595        *  string class does its own memory management.
 596        *  @endif
 597       */
 598       explicit
 599       basic_stringstream(const __string_type& __str,
 600                          ios_base::openmode __m = ios_base::out | ios_base::in)
 601       : __iostream_type(), _M_stringbuf(__str, __m)
 602       { this->init(&_M_stringbuf); }
 603
 604       /**
 605        *  @brief  The destructor does nothing.
 606        *
 607        *  The buffer is deallocated by the stringbuf object, not the
 608        *  formatting stream.
 609       */
 610       ~basic_stringstream()
 611       { }
 612
 613       // Members:
 614       /**
 615        *  @brief  Accessing the underlying buffer.
 616        *  @return  The current basic_stringbuf buffer.
 617        *
 618        *  This hides both signatures of std::basic_ios::rdbuf().
 619       */
 620       __stringbuf_type*
 621       rdbuf() const
 622       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 623
 624       /**
 625        *  @brief  Copying out the string buffer.
 626        *  @return  @c rdbuf()->str()
 627       */
 628       __string_type
 629       str() const
 630       { return _M_stringbuf.str(); }
 631
 632       /**
 633        *  @brief  Setting a new buffer.
 634        *  @param  s  The string to use as a new sequence.
 635        *
 636        *  Calls @c rdbuf()->str(s).
 637       */
 638       void
 639       str(const __string_type& __s)
 640       { _M_stringbuf.str(__s); }
 641     };
 642 } // namespace std
 643
 644 #ifndef _GLIBCXX_EXPORT_TEMPLATE
 645 # include <bits/sstream.tcc>
 646 #endif
 647
 648 #endif /* _GLIBCXX_SSTREAM */