libstdc++-v3/include/std/ostream

   1 // Output streams -*- C++ -*-
   2
   3 // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
   4 // 2006, 2007, 2008
   5 // Free Software Foundation, Inc.
   6 //
   7 // This file is part of the GNU ISO C++ Library.  This library is free
   8 // software; you can redistribute it and/or modify it under the
   9 // terms of the GNU General Public License as published by the
  10 // Free Software Foundation; either version 2, or (at your option)
  11 // any later version.
  12
  13 // This library is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17
  18 // You should have received a copy of the GNU General Public License
  19 // along with this library; see the file COPYING.  If not, write to
  20 // the Free Software Foundation, 51 Franklin Street, Fifth Floor,
  21 // Boston, MA 02110-1301, USA.
  22
  23 // As a special exception, you may use this file as part of a free software
  24 // library without restriction.  Specifically, if other files instantiate
  25 // templates or use macros or inline functions from this file, or you compile
  26 // this file and link it with other files to produce an executable, this
  27 // file does not by itself cause the resulting executable to be covered by
  28 // the GNU General Public License.  This exception does not however
  29 // invalidate any other reasons why the executable file might be covered by
  30 // the GNU General Public License.
  31
  32 /** @file ostream
  33  *  This is a Standard C++ Library header.
  34  */
  35
  36 //
  37 // ISO C++ 14882: 27.6.2  Output streams
  38 //
  39
  40 #ifndef _GLIBCXX_OSTREAM
  41 #define _GLIBCXX_OSTREAM 1
  42
  43 #pragma GCC system_header
  44
  45 #include <ios>
  46 #include <bits/ostream_insert.h>
  47
  48 #ifdef __GXX_EXPERIMENTAL_CXX0X__
  49 # include <system_error>
  50 #endif
  51
  52 _GLIBCXX_BEGIN_NAMESPACE(std)
  53
  54   // [27.6.2.1] Template class basic_ostream
  55   /**
  56    *  @brief  Controlling output.
  57    *
  58    *  This is the base class for all output streams.  It provides text
  59    *  formatting of all builtin types, and communicates with any class
  60    *  derived from basic_streambuf to do the actual output.
  61   */
  62   template<typename _CharT, typename _Traits>
  63     class basic_ostream : virtual public basic_ios<_CharT, _Traits>
  64     {
  65     public:
  66       // Types (inherited from basic_ios (27.4.4)):
  67       typedef _CharT                                    char_type;
  68       typedef typename _Traits::int_type                int_type;
  69       typedef typename _Traits::pos_type                pos_type;
  70       typedef typename _Traits::off_type                off_type;
  71       typedef _Traits                                   traits_type;
  72
  73       // Non-standard Types:
  74       typedef basic_streambuf<_CharT, _Traits>          __streambuf_type;
  75       typedef basic_ios<_CharT, _Traits>                __ios_type;
  76       typedef basic_ostream<_CharT, _Traits>            __ostream_type;
  77       typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> >
  78                                                         __num_put_type;
  79       typedef ctype<_CharT>                             __ctype_type;
  80
  81       // [27.6.2.2] constructor/destructor
  82       /**
  83        *  @brief  Base constructor.
  84        *
  85        *  This ctor is almost never called by the user directly, rather from
  86        *  derived classes' initialization lists, which pass a pointer to
  87        *  their own stream buffer.
  88       */
  89       explicit
  90       basic_ostream(__streambuf_type* __sb)
  91       { this->init(__sb); }
  92
  93       /**
  94        *  @brief  Base destructor.
  95        *
  96        *  This does very little apart from providing a virtual base dtor.
  97       */
  98       virtual
  99       ~basic_ostream() { }
 100
 101       // [27.6.2.3] prefix/suffix
 102       class sentry;
 103       friend class sentry;
 104
 105       // [27.6.2.5] formatted output
 106       // [27.6.2.5.3]  basic_ostream::operator<<
 107       //@{
 108       /**
 109        *  @brief  Interface for manipulators.
 110        *
 111        *  Manipulators such as @c std::endl and @c std::hex use these
 112        *  functions in constructs like "std::cout << std::endl".  For more
 113        *  information, see the iomanip header.
 114       */
 115       __ostream_type&
 116       operator<<(__ostream_type& (*__pf)(__ostream_type&))
 117       {
 118         // _GLIBCXX_RESOLVE_LIB_DEFECTS
 119         // DR 60. What is a formatted input function?
 120         // The inserters for manipulators are *not* formatted output functions.
 121         return __pf(*this);
 122       }
 123
 124       __ostream_type&
 125       operator<<(__ios_type& (*__pf)(__ios_type&))
 126       {
 127         // _GLIBCXX_RESOLVE_LIB_DEFECTS
 128         // DR 60. What is a formatted input function?
 129         // The inserters for manipulators are *not* formatted output functions.
 130         __pf(*this);
 131         return *this;
 132       }
 133
 134       __ostream_type&
 135       operator<<(ios_base& (*__pf) (ios_base&))
 136       {
 137         // _GLIBCXX_RESOLVE_LIB_DEFECTS
 138         // DR 60. What is a formatted input function?
 139         // The inserters for manipulators are *not* formatted output functions.
 140         __pf(*this);
 141         return *this;
 142       }
 143       //@}
 144
 145       // [27.6.2.5.2] arithmetic inserters
 146       /**
 147        *  @name Arithmetic Inserters
 148        *
 149        *  All the @c operator<< functions (aka <em>formatted output
 150        *  functions</em>) have some common behavior.  Each starts by
 151        *  constructing a temporary object of type std::basic_ostream::sentry.
 152        *  This can have several effects, concluding with the setting of a
 153        *  status flag; see the sentry documentation for more.
 154        *
 155        *  If the sentry status is good, the function tries to generate
 156        *  whatever data is appropriate for the type of the argument.
 157        *
 158        *  If an exception is thrown during insertion, ios_base::badbit
 159        *  will be turned on in the stream's error state without causing an
 160        *  ios_base::failure to be thrown.  The original exception will then
 161        *  be rethrown.
 162       */
 163       //@{
 164       /**
 165        *  @brief  Basic arithmetic inserters
 166        *  @param  A variable of builtin type.
 167        *  @return  @c *this if successful
 168        *
 169        *  These functions use the stream's current locale (specifically, the
 170        *  @c num_get facet) to perform numeric formatting.
 171       */
 172       __ostream_type&
 173       operator<<(long __n)
 174       { return _M_insert(__n); }
 175
 176       __ostream_type&
 177       operator<<(unsigned long __n)
 178       { return _M_insert(__n); }
 179
 180       __ostream_type&
 181       operator<<(bool __n)
 182       { return _M_insert(__n); }
 183
 184       __ostream_type&
 185       operator<<(short __n);
 186
 187       __ostream_type&
 188       operator<<(unsigned short __n)
 189       {
 190         // _GLIBCXX_RESOLVE_LIB_DEFECTS
 191         // 117. basic_ostream uses nonexistent num_put member functions.
 192         return _M_insert(static_cast<unsigned long>(__n));
 193       }
 194
 195       __ostream_type&
 196       operator<<(int __n);
 197
 198       __ostream_type&
 199       operator<<(unsigned int __n)
 200       {
 201         // _GLIBCXX_RESOLVE_LIB_DEFECTS
 202         // 117. basic_ostream uses nonexistent num_put member functions.
 203         return _M_insert(static_cast<unsigned long>(__n));
 204       }
 205
 206 #ifdef _GLIBCXX_USE_LONG_LONG
 207       __ostream_type&
 208       operator<<(long long __n)
 209       { return _M_insert(__n); }
 210
 211       __ostream_type&
 212       operator<<(unsigned long long __n)
 213       { return _M_insert(__n); }
 214 #endif
 215
 216       __ostream_type&
 217       operator<<(double __f)
 218       { return _M_insert(__f); }
 219
 220       __ostream_type&
 221       operator<<(float __f)
 222       {
 223         // _GLIBCXX_RESOLVE_LIB_DEFECTS
 224         // 117. basic_ostream uses nonexistent num_put member functions.
 225         return _M_insert(static_cast<double>(__f));
 226       }
 227
 228       __ostream_type&
 229       operator<<(long double __f)
 230       { return _M_insert(__f); }
 231
 232       __ostream_type&
 233       operator<<(const void* __p)
 234       { return _M_insert(__p); }
 235
 236       /**
 237        *  @brief  Extracting from another streambuf.
 238        *  @param  sb  A pointer to a streambuf
 239        *
 240        *  This function behaves like one of the basic arithmetic extractors,
 241        *  in that it also constructs a sentry object and has the same error
 242        *  handling behavior.
 243        *
 244        *  If @a sb is NULL, the stream will set failbit in its error state.
 245        *
 246        *  Characters are extracted from @a sb and inserted into @c *this
 247        *  until one of the following occurs:
 248        *
 249        *  - the input stream reaches end-of-file,
 250        *  - insertion into the output sequence fails (in this case, the
 251        *    character that would have been inserted is not extracted), or
 252        *  - an exception occurs while getting a character from @a sb, which
 253        *    sets failbit in the error state
 254        *
 255        *  If the function inserts no characters, failbit is set.
 256       */
 257       __ostream_type&
 258       operator<<(__streambuf_type* __sb);
 259       //@}
 260
 261       // [27.6.2.6] unformatted output functions
 262       /**
 263        *  @name Unformatted Output Functions
 264        *
 265        *  All the unformatted output functions have some common behavior.
 266        *  Each starts by constructing a temporary object of type
 267        *  std::basic_ostream::sentry.  This has several effects, concluding
 268        *  with the setting of a status flag; see the sentry documentation
 269        *  for more.
 270        *
 271        *  If the sentry status is good, the function tries to generate
 272        *  whatever data is appropriate for the type of the argument.
 273        *
 274        *  If an exception is thrown during insertion, ios_base::badbit
 275        *  will be turned on in the stream's error state.  If badbit is on in
 276        *  the stream's exceptions mask, the exception will be rethrown
 277        *  without completing its actions.
 278       */
 279       //@{
 280       /**
 281        *  @brief  Simple insertion.
 282        *  @param  c  The character to insert.
 283        *  @return  *this
 284        *
 285        *  Tries to insert @a c.
 286        *
 287        *  @note  This function is not overloaded on signed char and
 288        *         unsigned char.
 289       */
 290       __ostream_type&
 291       put(char_type __c);
 292
 293       // Core write functionality, without sentry.
 294       void
 295       _M_write(const char_type* __s, streamsize __n)
 296       {
 297         const streamsize __put = this->rdbuf()->sputn(__s, __n);
 298         if (__put != __n)
 299           this->setstate(ios_base::badbit);
 300       }
 301
 302       /**
 303        *  @brief  Character string insertion.
 304        *  @param  s  The array to insert.
 305        *  @param  n  Maximum number of characters to insert.
 306        *  @return  *this
 307        *
 308        *  Characters are copied from @a s and inserted into the stream until
 309        *  one of the following happens:
 310        *
 311        *  - @a n characters are inserted
 312        *  - inserting into the output sequence fails (in this case, badbit
 313        *    will be set in the stream's error state)
 314        *
 315        *  @note  This function is not overloaded on signed char and
 316        *         unsigned char.
 317       */
 318       __ostream_type&
 319       write(const char_type* __s, streamsize __n);
 320       //@}
 321
 322       /**
 323        *  @brief  Synchronizing the stream buffer.
 324        *  @return  *this
 325        *
 326        *  If @c rdbuf() is a null pointer, changes nothing.
 327        *
 328        *  Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
 329        *  sets badbit.
 330       */
 331       __ostream_type&
 332       flush();
 333
 334       // [27.6.2.4] seek members
 335       /**
 336        *  @brief  Getting the current write position.
 337        *  @return  A file position object.
 338        *
 339        *  If @c fail() is not false, returns @c pos_type(-1) to indicate
 340        *  failure.  Otherwise returns @c rdbuf()->pubseekoff(0,cur,out).
 341       */
 342       pos_type
 343       tellp();
 344
 345       /**
 346        *  @brief  Changing the current write position.
 347        *  @param  pos  A file position object.
 348        *  @return  *this
 349        *
 350        *  If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos).  If
 351        *  that function fails, sets failbit.
 352       */
 353       __ostream_type&
 354       seekp(pos_type);
 355
 356       /**
 357        *  @brief  Changing the current write position.
 358        *  @param  off  A file offset object.
 359        *  @param  dir  The direction in which to seek.
 360        *  @return  *this
 361        *
 362        *  If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
 363        *  If that function fails, sets failbit.
 364       */
 365        __ostream_type&
 366       seekp(off_type, ios_base::seekdir);
 367
 368     protected:
 369       basic_ostream()
 370       { this->init(0); }
 371
 372       template<typename _ValueT>
 373         __ostream_type&
 374         _M_insert(_ValueT __v);
 375     };
 376
 377   /**
 378    *  @brief  Performs setup work for output streams.
 379    *
 380    *  Objects of this class are created before all of the standard
 381    *  inserters are run.  It is responsible for "exception-safe prefix and
 382    *  suffix operations."  Additional actions may be added by the
 383    *  implementation, and we list them in
 384    *  http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5
 385    *  under [27.6] notes.
 386   */
 387   template <typename _CharT, typename _Traits>
 388     class basic_ostream<_CharT, _Traits>::sentry
 389     {
 390       // Data Members:
 391       bool                              _M_ok;
 392       basic_ostream<_CharT, _Traits>&   _M_os;
 393
 394     public:
 395       /**
 396        *  @brief  The constructor performs preparatory work.
 397        *  @param  os  The output stream to guard.
 398        *
 399        *  If the stream state is good (@a os.good() is true), then if the
 400        *  stream is tied to another output stream, @c is.tie()->flush()
 401        *  is called to synchronize the output sequences.
 402        *
 403        *  If the stream state is still good, then the sentry state becomes
 404        *  true ("okay").
 405       */
 406       explicit
 407       sentry(basic_ostream<_CharT, _Traits>& __os);
 408
 409       /**
 410        *  @brief  Possibly flushes the stream.
 411        *
 412        *  If @c ios_base::unitbuf is set in @c os.flags(), and
 413        *  @c std::uncaught_exception() is true, the sentry destructor calls
 414        *  @c flush() on the output stream.
 415       */
 416       ~sentry()
 417       {
 418         // XXX MT
 419         if (bool(_M_os.flags() & ios_base::unitbuf) && !uncaught_exception())
 420           {
 421             // Can't call flush directly or else will get into recursive lock.
 422             if (_M_os.rdbuf() && _M_os.rdbuf()->pubsync() == -1)
 423               _M_os.setstate(ios_base::badbit);
 424           }
 425       }
 426
 427       /**
 428        *  @brief  Quick status checking.
 429        *  @return  The sentry state.
 430        *
 431        *  For ease of use, sentries may be converted to booleans.  The
 432        *  return value is that of the sentry state (true == okay).
 433       */
 434       operator bool() const
 435       { return _M_ok; }
 436     };
 437
 438   // [27.6.2.5.4] character insertion templates
 439   //@{
 440   /**
 441    *  @brief  Character inserters
 442    *  @param  out  An output stream.
 443    *  @param  c  A character.
 444    *  @return  out
 445    *
 446    *  Behaves like one of the formatted arithmetic inserters described in
 447    *  std::basic_ostream.  After constructing a sentry object with good
 448    *  status, this function inserts a single character and any required
 449    *  padding (as determined by [22.2.2.2.2]).  @c out.width(0) is then
 450    *  called.
 451    *
 452    *  If @a c is of type @c char and the character type of the stream is not
 453    *  @c char, the character is widened before insertion.
 454   */
 455   template<typename _CharT, typename _Traits>
 456     inline basic_ostream<_CharT, _Traits>&
 457     operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c)
 458     { return __ostream_insert(__out, &__c, 1); }
 459
 460   template<typename _CharT, typename _Traits>
 461     inline basic_ostream<_CharT, _Traits>&
 462     operator<<(basic_ostream<_CharT, _Traits>& __out, char __c)
 463     { return (__out << __out.widen(__c)); }
 464
 465   // Specialization
 466   template <class _Traits>
 467     inline basic_ostream<char, _Traits>&
 468     operator<<(basic_ostream<char, _Traits>& __out, char __c)
 469     { return __ostream_insert(__out, &__c, 1); }
 470
 471   // Signed and unsigned
 472   template<class _Traits>
 473     inline basic_ostream<char, _Traits>&
 474     operator<<(basic_ostream<char, _Traits>& __out, signed char __c)
 475     { return (__out << static_cast<char>(__c)); }
 476
 477   template<class _Traits>
 478     inline basic_ostream<char, _Traits>&
 479     operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c)
 480     { return (__out << static_cast<char>(__c)); }
 481   //@}
 482
 483   //@{
 484   /**
 485    *  @brief  String inserters
 486    *  @param  out  An output stream.
 487    *  @param  s  A character string.
 488    *  @return  out
 489    *  @pre  @a s must be a non-NULL pointer
 490    *
 491    *  Behaves like one of the formatted arithmetic inserters described in
 492    *  std::basic_ostream.  After constructing a sentry object with good
 493    *  status, this function inserts @c traits::length(s) characters starting
 494    *  at @a s, widened if necessary, followed by any required padding (as
 495    *  determined by [22.2.2.2.2]).  @c out.width(0) is then called.
 496   */
 497   template<typename _CharT, typename _Traits>
 498     inline basic_ostream<_CharT, _Traits>&
 499     operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s)
 500     {
 501       if (!__s)
 502         __out.setstate(ios_base::badbit);
 503       else
 504         __ostream_insert(__out, __s,
 505                          static_cast<streamsize>(_Traits::length(__s)));
 506       return __out;
 507     }
 508
 509   template<typename _CharT, typename _Traits>
 510     basic_ostream<_CharT, _Traits> &
 511     operator<<(basic_ostream<_CharT, _Traits>& __out, const char* __s);
 512
 513   // Partial specializations
 514   template<class _Traits>
 515     inline basic_ostream<char, _Traits>&
 516     operator<<(basic_ostream<char, _Traits>& __out, const char* __s)
 517     {
 518       if (!__s)
 519         __out.setstate(ios_base::badbit);
 520       else
 521         __ostream_insert(__out, __s,
 522                          static_cast<streamsize>(_Traits::length(__s)));
 523       return __out;
 524     }
 525
 526   // Signed and unsigned
 527   template<class _Traits>
 528     inline basic_ostream<char, _Traits>&
 529     operator<<(basic_ostream<char, _Traits>& __out, const signed char* __s)
 530     { return (__out << reinterpret_cast<const char*>(__s)); }
 531
 532   template<class _Traits>
 533     inline basic_ostream<char, _Traits> &
 534     operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s)
 535     { return (__out << reinterpret_cast<const char*>(__s)); }
 536   //@}
 537
 538 #ifdef __GXX_EXPERIMENTAL_CXX0X__
 539   template<typename _CharT, typename _Traits>
 540     inline basic_ostream<_CharT, _Traits>&
 541     operator<<(basic_ostream<_CharT, _Traits>& __out, const error_code& __e)
 542     { return (__out << __e.category().name() << ':' << __e.value()); }
 543 #endif
 544
 545   // [27.6.2.7] standard basic_ostream manipulators
 546   /**
 547    *  @brief  Write a newline and flush the stream.
 548    *
 549    *  This manipulator is often mistakenly used when a simple newline is
 550    *  desired, leading to poor buffering performance.  See
 551    *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for more
 552    *  on this subject.
 553   */
 554   template<typename _CharT, typename _Traits>
 555     inline basic_ostream<_CharT, _Traits>&
 556     endl(basic_ostream<_CharT, _Traits>& __os)
 557     { return flush(__os.put(__os.widen('\n'))); }
 558
 559   /**
 560    *  @brief  Write a null character into the output sequence.
 561    *
 562    *  "Null character" is @c CharT() by definition.  For CharT of @c char,
 563    *  this correctly writes the ASCII @c NUL character string terminator.
 564   */
 565   template<typename _CharT, typename _Traits>
 566     inline basic_ostream<_CharT, _Traits>&
 567     ends(basic_ostream<_CharT, _Traits>& __os)
 568     { return __os.put(_CharT()); }
 569
 570   /**
 571    *  @brief  Flushes the output stream.
 572    *
 573    *  This manipulator simply calls the stream's @c flush() member function.
 574   */
 575   template<typename _CharT, typename _Traits>
 576     inline basic_ostream<_CharT, _Traits>&
 577     flush(basic_ostream<_CharT, _Traits>& __os)
 578     { return __os.flush(); }
 579
 580 _GLIBCXX_END_NAMESPACE
 581
 582 #ifndef _GLIBCXX_EXPORT_TEMPLATE
 583 # include <bits/ostream.tcc>
 584 #endif
 585
 586 #endif  /* _GLIBCXX_OSTREAM */