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 _CPP_SSTREAM
  40 #define _CPP_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 _GLIBCPP_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       // Data Members:
  89       /**
  90        *  @if maint
  91        *  @doctodo
  92        *  @endif
  93       */
  94       __string_type             _M_string;
  95
  96     public:
  97       // Constructors:
  98       /**
  99        *  @brief  Starts with an empty string buffer.
 100        *  @param  mode  Whether the buffer can read, or write, or both.
 101        *
 102        *  The default constructor initializes the parent class using its
 103        *  own default ctor.
 104       */
 105       explicit
 106       basic_stringbuf(ios_base::openmode __mode = ios_base::in | ios_base::out)
 107       : __streambuf_type(), _M_string()
 108       { _M_stringbuf_init(__mode); }
 109
 110       /**
 111        *  @brief  Starts with an existing string buffer.
 112        *  @param  str  A string to copy as a starting buffer.
 113        *  @param  mode  Whether the buffer can read, or write, or both.
 114        *
 115        *  This constructor initializes the parent class using its
 116        *  own default ctor.
 117       */
 118       explicit
 119       basic_stringbuf(const __string_type& __str,
 120                       ios_base::openmode __mode = ios_base::in | ios_base::out)
 121       : __streambuf_type(), _M_string(__str.data(), __str.size())
 122       { _M_stringbuf_init(__mode); }
 123
 124       // Get and set:
 125       /**
 126        *  @brief  Copying out the string buffer.
 127        *  @return  A copy of one of the underlying sequences.
 128        *
 129        *  "If the buffer is only created in input mode, the underlying
 130        *  character sequence is equal to the input sequence; otherwise, it
 131        *  is equal to the output sequence." [27.7.1.2]/1
 132       */
 133       __string_type
 134       str() const
 135       {
 136         if (this->_M_mode & ios_base::out)
 137           {
 138             // This is the deal: _M_string.size() is a value that
 139             // represents the size of the initial string that makes
 140             // _M_string, and may not be the correct size of the
 141             // current stringbuf internal buffer.
 142             __size_type __len = _M_string.size();
 143             if (this->_M_out_cur > this->_M_out_beg)
 144               __len = std::max(__size_type(this->_M_out_end
 145                                            - this->_M_out_beg), __len);
 146             return __string_type(this->_M_out_beg, this->_M_out_beg + __len);
 147           }
 148         else
 149           return _M_string;
 150       }
 151
 152       /**
 153        *  @brief  Setting a new buffer.
 154        *  @param  s  The string to use as a new sequence.
 155        *
 156        *  Deallocates any previous stored sequence, then copies @a s to
 157        *  use as a new one.
 158       */
 159       void
 160       str(const __string_type& __s)
 161       {
 162         // Cannot use _M_string = __s, since v3 strings are COW.
 163         _M_string.assign(__s.data(), __s.size());
 164         _M_stringbuf_init(this->_M_mode);
 165       }
 166
 167     protected:
 168       // Common initialization code for both ctors goes here.
 169       /**
 170        *  @if maint
 171        *  @doctodo
 172        *  @endif
 173       */
 174       void
 175       _M_stringbuf_init(ios_base::openmode __mode)
 176       {
 177         // _M_buf_size is a convenient alias for "what the streambuf
 178         // thinks the allocated size of the string really is." This is
 179         // necessary as ostringstreams are implemented with the
 180         // streambufs having control of the allocation and
 181         // re-allocation of the internal string object, _M_string.
 182         this->_M_buf_size = _M_string.size();
 183
 184         // NB: Start ostringstream buffers at 512 bytes. This is an
 185         // experimental value (pronounced "arbitrary" in some of the
 186         // hipper english-speaking countries), and can be changed to
 187         // suit particular needs.
 188         this->_M_buf_size_opt = 512;
 189         this->_M_mode = __mode;
 190         if (this->_M_mode & (ios_base::ate | ios_base::app))
 191           _M_really_sync(0, this->_M_buf_size);
 192         else
 193           _M_really_sync(0, 0);
 194       }
 195
 196       // Overridden virtual functions:
 197       // [documentation is inherited]
 198       virtual int_type
 199       underflow()
 200       {
 201         if (this->_M_in_cur && this->_M_in_cur < this->_M_in_end)
 202           return traits_type::to_int_type(*gptr());
 203         else
 204           return traits_type::eof();
 205       }
 206
 207       // [documentation is inherited]
 208       virtual int_type
 209       pbackfail(int_type __c = traits_type::eof());
 210
 211       // [documentation is inherited]
 212       virtual int_type
 213       overflow(int_type __c = traits_type::eof());
 214
 215       /**
 216        *  @brief  Manipulates the buffer.
 217        *  @param  s  Pointer to a buffer area.
 218        *  @param  n  Size of @a s.
 219        *  @return  @c this
 220        *
 221        *  If no buffer has already been created, and both @a s and @a n are
 222        *  non-zero, then @c s is used as a buffer; see
 223        *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2
 224        *  for more.
 225       */
 226       virtual __streambuf_type*
 227       setbuf(char_type* __s, streamsize __n)
 228       {
 229         if (__s && __n)
 230           {
 231             _M_string = __string_type(__s, __n);
 232             _M_really_sync(0, 0);
 233           }
 234         return this;
 235       }
 236
 237       // [documentation is inherited]
 238       virtual pos_type
 239       seekoff(off_type __off, ios_base::seekdir __way,
 240               ios_base::openmode __mode = ios_base::in | ios_base::out);
 241
 242       // [documentation is inherited]
 243       virtual pos_type
 244       seekpos(pos_type __sp,
 245               ios_base::openmode __mode = ios_base::in | ios_base::out);
 246
 247       // Internal function for correctly updating the internal buffer
 248       // for a particular _M_string, due to initialization or
 249       // re-sizing of an existing _M_string.
 250       // Assumes: contents of _M_string and internal buffer match exactly.
 251       // __i == _M_in_cur - _M_in_beg
 252       // __o == _M_out_cur - _M_out_beg
 253       /**
 254        *  @if maint
 255        *  @doctodo
 256        *  @endif
 257       */
 258       virtual int
 259       _M_really_sync(__size_type __i, __size_type __o)
 260       {
 261         char_type* __base = const_cast<char_type*>(_M_string.data());
 262         bool __testin = this->_M_mode & ios_base::in;
 263         bool __testout = this->_M_mode & ios_base::out;
 264         __size_type __len = _M_string.size();
 265
 266         this->_M_buf = __base;
 267         if (__testin)
 268             this->setg(__base, __base + __i, __base + __len);
 269         if (__testout)
 270           {
 271             this->setp(__base, __base + __len);
 272             this->_M_out_cur += __o;
 273           }
 274         return 0;
 275       }
 276     };
 277
 278
 279   // [27.7.2] Template class basic_istringstream
 280   /**
 281    *  @brief  Controlling input for std::string.
 282    *
 283    *  This class supports reading from objects of type std::basic_string,
 284    *  using the inherited functions from std::basic_istream.  To control
 285    *  the associated sequence, an instance of std::basic_stringbuf is used,
 286    *  which this page refers to as @c sb.
 287   */
 288   template<typename _CharT, typename _Traits, typename _Alloc>
 289     class basic_istringstream : public basic_istream<_CharT, _Traits>
 290     {
 291     public:
 292       // Types:
 293       typedef _CharT                                    char_type;
 294       typedef _Traits                                   traits_type;
 295 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
 296 // 251. basic_stringbuf missing allocator_type
 297       typedef _Alloc                                    allocator_type;
 298 #endif
 299       typedef typename traits_type::int_type            int_type;
 300       typedef typename traits_type::pos_type            pos_type;
 301       typedef typename traits_type::off_type            off_type;
 302
 303       // Non-standard types:
 304       typedef basic_string<_CharT, _Traits, _Alloc>     __string_type;
 305       typedef basic_stringbuf<_CharT, _Traits, _Alloc>  __stringbuf_type;
 306       typedef basic_istream<char_type, traits_type>     __istream_type;
 307
 308     private:
 309       /**
 310        *  @if maint
 311        *  @doctodo
 312        *  @endif
 313       */
 314       __stringbuf_type  _M_stringbuf;
 315
 316     public:
 317       // Constructors:
 318       /**
 319        *  @brief  Default constructor starts with an empty string buffer.
 320        *  @param  mode  Whether the buffer can read, or write, or both.
 321        *
 322        *  @c ios_base::in is automatically included in @a mode.
 323        *
 324        *  Initializes @c sb using @c mode|in, and passes @c &sb to the base
 325        *  class initializer.  Does not allocate any buffer.
 326        *
 327        *  @if maint
 328        *  That's a lie.  We initialize the base class with NULL, because the
 329        *  string class does its own memory management.
 330        *  @endif
 331       */
 332       explicit
 333       basic_istringstream(ios_base::openmode __mode = ios_base::in)
 334       : __istream_type(NULL), _M_stringbuf(__mode | ios_base::in)
 335       { this->init(&_M_stringbuf); }
 336
 337       /**
 338        *  @brief  Starts with an existing string buffer.
 339        *  @param  str  A string to copy as a starting buffer.
 340        *  @param  mode  Whether the buffer can read, or write, or both.
 341        *
 342        *  @c ios_base::in is automatically included in @a mode.
 343        *
 344        *  Initializes @c sb using @a str and @c mode|in, and passes @c &sb
 345        *  to the base class initializer.
 346        *
 347        *  @if maint
 348        *  That's a lie.  We initialize the base class with NULL, because the
 349        *  string class does its own memory management.
 350        *  @endif
 351       */
 352       explicit
 353       basic_istringstream(const __string_type& __str,
 354                           ios_base::openmode __mode = ios_base::in)
 355       : __istream_type(NULL), _M_stringbuf(__str, __mode | ios_base::in)
 356       { this->init(&_M_stringbuf); }
 357
 358       /**
 359        *  @brief  The destructor does nothing.
 360        *
 361        *  The buffer is deallocated by the stringbuf object, not the
 362        *  formatting stream.
 363       */
 364       ~basic_istringstream()
 365       { }
 366
 367       // Members:
 368       /**
 369        *  @brief  Accessing the underlying buffer.
 370        *  @return  The current basic_stringbuf buffer.
 371        *
 372        *  This hides both signatures of std::basic_ios::rdbuf().
 373       */
 374       __stringbuf_type*
 375       rdbuf() const
 376       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 377
 378       /**
 379        *  @brief  Copying out the string buffer.
 380        *  @return  @c rdbuf()->str()
 381       */
 382       __string_type
 383       str() const
 384       { return _M_stringbuf.str(); }
 385
 386       /**
 387        *  @brief  Setting a new buffer.
 388        *  @param  s  The string to use as a new sequence.
 389        *
 390        *  Calls @c rdbuf()->str(s).
 391       */
 392       void
 393       str(const __string_type& __s)
 394       { _M_stringbuf.str(__s); }
 395     };
 396
 397
 398   // [27.7.3] Template class basic_ostringstream
 399   /**
 400    *  @brief  Controlling output for std::string.
 401    *
 402    *  This class supports writing to objects of type std::basic_string,
 403    *  using the inherited functions from std::basic_ostream.  To control
 404    *  the associated sequence, an instance of std::basic_stringbuf is used,
 405    *  which this page refers to as @c sb.
 406   */
 407   template <typename _CharT, typename _Traits, typename _Alloc>
 408     class basic_ostringstream : public basic_ostream<_CharT, _Traits>
 409     {
 410     public:
 411       // Types:
 412       typedef _CharT                                    char_type;
 413       typedef _Traits                                   traits_type;
 414 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
 415 // 251. basic_stringbuf missing allocator_type
 416       typedef _Alloc                                    allocator_type;
 417 #endif
 418       typedef typename traits_type::int_type            int_type;
 419       typedef typename traits_type::pos_type            pos_type;
 420       typedef typename traits_type::off_type            off_type;
 421
 422       // Non-standard types:
 423       typedef basic_string<_CharT, _Traits, _Alloc>     __string_type;
 424       typedef basic_stringbuf<_CharT, _Traits, _Alloc>  __stringbuf_type;
 425       typedef basic_ostream<char_type, traits_type>     __ostream_type;
 426
 427     private:
 428       /**
 429        *  @if maint
 430        *  @doctodo
 431        *  @endif
 432       */
 433       __stringbuf_type  _M_stringbuf;
 434
 435     public:
 436       // Constructors/destructor:
 437       /**
 438        *  @brief  Default constructor starts with an empty string buffer.
 439        *  @param  mode  Whether the buffer can read, or write, or both.
 440        *
 441        *  @c ios_base::out is automatically included in @a mode.
 442        *
 443        *  Initializes @c sb using @c mode|out, and passes @c &sb to the base
 444        *  class initializer.  Does not allocate any buffer.
 445        *
 446        *  @if maint
 447        *  That's a lie.  We initialize the base class with NULL, because the
 448        *  string class does its own memory management.
 449        *  @endif
 450       */
 451       explicit
 452       basic_ostringstream(ios_base::openmode __mode = ios_base::out)
 453       : __ostream_type(NULL), _M_stringbuf(__mode | ios_base::out)
 454       { this->init(&_M_stringbuf); }
 455
 456       /**
 457        *  @brief  Starts with an existing string buffer.
 458        *  @param  str  A string to copy as a starting buffer.
 459        *  @param  mode  Whether the buffer can read, or write, or both.
 460        *
 461        *  @c ios_base::out is automatically included in @a mode.
 462        *
 463        *  Initializes @c sb using @a str and @c mode|out, and passes @c &sb
 464        *  to the base class initializer.
 465        *
 466        *  @if maint
 467        *  That's a lie.  We initialize the base class with NULL, because the
 468        *  string class does its own memory management.
 469        *  @endif
 470       */
 471       explicit
 472       basic_ostringstream(const __string_type& __str,
 473                           ios_base::openmode __mode = ios_base::out)
 474       : __ostream_type(NULL), _M_stringbuf(__str, __mode | ios_base::out)
 475       { this->init(&_M_stringbuf); }
 476
 477       /**
 478        *  @brief  The destructor does nothing.
 479        *
 480        *  The buffer is deallocated by the stringbuf object, not the
 481        *  formatting stream.
 482       */
 483       ~basic_ostringstream()
 484       { }
 485
 486       // Members:
 487       /**
 488        *  @brief  Accessing the underlying buffer.
 489        *  @return  The current basic_stringbuf buffer.
 490        *
 491        *  This hides both signatures of std::basic_ios::rdbuf().
 492       */
 493       __stringbuf_type*
 494       rdbuf() const
 495       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 496
 497       /**
 498        *  @brief  Copying out the string buffer.
 499        *  @return  @c rdbuf()->str()
 500       */
 501       __string_type
 502       str() const
 503       { return _M_stringbuf.str(); }
 504
 505       /**
 506        *  @brief  Setting a new buffer.
 507        *  @param  s  The string to use as a new sequence.
 508        *
 509        *  Calls @c rdbuf()->str(s).
 510       */
 511       void
 512       str(const __string_type& __s)
 513       { _M_stringbuf.str(__s); }
 514     };
 515
 516
 517   // [27.7.4] Template class basic_stringstream
 518   /**
 519    *  @brief  Controlling input and output for std::string.
 520    *
 521    *  This class supports reading from and writing to objects of type
 522    *  std::basic_string, using the inherited functions from
 523    *  std::basic_iostream.  To control the associated sequence, an instance
 524    *  of std::basic_stringbuf is used, which this page refers to as @c sb.
 525   */
 526   template <typename _CharT, typename _Traits, typename _Alloc>
 527     class basic_stringstream : public basic_iostream<_CharT, _Traits>
 528     {
 529     public:
 530       // Types:
 531       typedef _CharT                                    char_type;
 532       typedef _Traits                                   traits_type;
 533 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
 534 // 251. basic_stringbuf missing allocator_type
 535       typedef _Alloc                                    allocator_type;
 536 #endif
 537       typedef typename traits_type::int_type            int_type;
 538       typedef typename traits_type::pos_type            pos_type;
 539       typedef typename traits_type::off_type            off_type;
 540
 541       // Non-standard Types:
 542       typedef basic_string<_CharT, _Traits, _Alloc>     __string_type;
 543       typedef basic_stringbuf<_CharT, _Traits, _Alloc>  __stringbuf_type;
 544       typedef basic_iostream<char_type, traits_type>    __iostream_type;
 545
 546     private:
 547       /**
 548        *  @if maint
 549        *  @doctodo
 550        *  @endif
 551       */
 552       __stringbuf_type  _M_stringbuf;
 553
 554     public:
 555       // Constructors/destructors
 556       /**
 557        *  @brief  Default constructor starts with an empty string buffer.
 558        *  @param  mode  Whether the buffer can read, or write, or both.
 559        *
 560        *  Initializes @c sb using @c mode, and passes @c &sb to the base
 561        *  class initializer.  Does not allocate any buffer.
 562        *
 563        *  @if maint
 564        *  That's a lie.  We initialize the base class with NULL, because the
 565        *  string class does its own memory management.
 566        *  @endif
 567       */
 568       explicit
 569       basic_stringstream(ios_base::openmode __m = ios_base::out | ios_base::in)
 570       : __iostream_type(NULL), _M_stringbuf(__m)
 571       { this->init(&_M_stringbuf); }
 572
 573       /**
 574        *  @brief  Starts with an existing string buffer.
 575        *  @param  str  A string to copy as a starting buffer.
 576        *  @param  mode  Whether the buffer can read, or write, or both.
 577        *
 578        *  Initializes @c sb using @a str and @c mode, and passes @c &sb
 579        *  to the base class initializer.
 580        *
 581        *  @if maint
 582        *  That's a lie.  We initialize the base class with NULL, because the
 583        *  string class does its own memory management.
 584        *  @endif
 585       */
 586       explicit
 587       basic_stringstream(const __string_type& __str,
 588                          ios_base::openmode __m = ios_base::out | ios_base::in)
 589       : __iostream_type(NULL), _M_stringbuf(__str, __m)
 590       { this->init(&_M_stringbuf); }
 591
 592       /**
 593        *  @brief  The destructor does nothing.
 594        *
 595        *  The buffer is deallocated by the stringbuf object, not the
 596        *  formatting stream.
 597       */
 598       ~basic_stringstream()
 599       { }
 600
 601       // Members:
 602       /**
 603        *  @brief  Accessing the underlying buffer.
 604        *  @return  The current basic_stringbuf buffer.
 605        *
 606        *  This hides both signatures of std::basic_ios::rdbuf().
 607       */
 608       __stringbuf_type*
 609       rdbuf() const
 610       { return const_cast<__stringbuf_type*>(&_M_stringbuf); }
 611
 612       /**
 613        *  @brief  Copying out the string buffer.
 614        *  @return  @c rdbuf()->str()
 615       */
 616       __string_type
 617       str() const
 618       { return _M_stringbuf.str(); }
 619
 620       /**
 621        *  @brief  Setting a new buffer.
 622        *  @param  s  The string to use as a new sequence.
 623        *
 624        *  Calls @c rdbuf()->str(s).
 625       */
 626       void
 627       str(const __string_type& __s)
 628       { _M_stringbuf.str(__s); }
 629     };
 630 } // namespace std
 631
 632 #ifdef _GLIBCPP_NO_TEMPLATE_EXPORT
 633 # define export
 634 #endif
 635 #ifdef  _GLIBCPP_FULLY_COMPLIANT_HEADERS
 636 # include <bits/sstream.tcc>
 637 #endif
 638
 639 #endif