# ostream

Go to the documentation of this file.

    00001 // Output streams -*- C++ -*-
    00002
    00003 // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
    00004 // 2006, 2007, 2008, 2009, 2010
    00005 // Free Software Foundation, Inc.
    00006 //
    00007 // This file is part of the GNU ISO C++ Library.  This library is free
    00008 // software; you can redistribute it and/or modify it under the
    00009 // terms of the GNU General Public License as published by the
    00010 // Free Software Foundation; either version 3, or (at your option)
    00011 // any later version.
    00012
    00013 // This library is distributed in the hope that it will be useful,
    00014 // but WITHOUT ANY WARRANTY; without even the implied warranty of
    00015 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    00016 // GNU General Public License for more details.
    00017
    00018 // Under Section 7 of GPL version 3, you are granted additional
    00019 // permissions described in the GCC Runtime Library Exception, version
    00020 // 3.1, as published by the Free Software Foundation.
    00021
    00022 // You should have received a copy of the GNU General Public License and
    00023 // a copy of the GCC Runtime Library Exception along with this program;
    00024 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
    00025 // <http://www.gnu.org/licenses/>.
    00026
    00027 /** @file ostream
    00028  *  This is a Standard C++ Library header.
    00029  */
    00030
    00031 //
    00032 // ISO C++ 14882: 27.6.2  Output streams
    00033 //
    00034
    00035 #ifndef _GLIBCXX_OSTREAM
    00036 #define _GLIBCXX_OSTREAM 1
    00037
    00038 #pragma GCC system_header
    00039
    00040 #include <ios>
    00041 #include <bits/ostream_insert.h>
    00042
    00043 _GLIBCXX_BEGIN_NAMESPACE(std)
    00044
    00045   // [27.6.2.1] Template class basic_ostream
    00046   /**
    00047    *  @brief  Controlling output.
    00048    *  @ingroup io
    00049    *
    00050    *  This is the base class for all output streams.  It provides text
    00051    *  formatting of all builtin types, and communicates with any class
    00052    *  derived from basic_streambuf to do the actual output.
    00053   */
    00054   template<typename _CharT, typename _Traits>
    00055     class basic_ostream : virtual public basic_ios<_CharT, _Traits>
    00056     {
    00057     public:
    00058       // Types (inherited from basic_ios (27.4.4)):
    00059       typedef _CharT                            char_type;
    00060       typedef typename _Traits::int_type        int_type;
    00061       typedef typename _Traits::pos_type        pos_type;
    00062       typedef typename _Traits::off_type        off_type;
    00063       typedef _Traits                           traits_type;
    00064
    00065       // Non-standard Types:
    00066       typedef basic_streambuf<_CharT, _Traits>      __streambuf_type;
    00067       typedef basic_ios<_CharT, _Traits>        __ios_type;
    00068       typedef basic_ostream<_CharT, _Traits>        __ostream_type;
    00069       typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> >
    00070                                 __num_put_type;
    00071       typedef ctype<_CharT>                     __ctype_type;
    00072
    00073       // [27.6.2.2] constructor/destructor
    00074       /**
    00075        *  @brief  Base constructor.
    00076        *
    00077        *  This ctor is almost never called by the user directly, rather from
    00078        *  derived classes' initialization lists, which pass a pointer to
    00079        *  their own stream buffer.
    00080       */
    00081       explicit
    00082       basic_ostream(__streambuf_type* __sb)
    00083       { this->init(__sb); }
    00084
    00085       /**
    00086        *  @brief  Base destructor.
    00087        *
    00088        *  This does very little apart from providing a virtual base dtor.
    00089       */
    00090       virtual
    00091       ~basic_ostream() { }
    00092
    00093       // [27.6.2.3] prefix/suffix
    00094       class sentry;
    00095       friend class sentry;
    00096
    00097       // [27.6.2.5] formatted output
    00098       // [27.6.2.5.3]  basic_ostream::operator<<
    00099       //@{
    00100       /**
    00101        *  @brief  Interface for manipulators.
    00102        *
    00103        *  Manipulators such as @c std::endl and @c std::hex use these
    00104        *  functions in constructs like "std::cout << std::endl".  For more
    00105        *  information, see the iomanip header.
    00106       */
    00107       __ostream_type&
    00108       operator<<(__ostream_type& (*__pf)(__ostream_type&))
    00109       {
    00110     // _GLIBCXX_RESOLVE_LIB_DEFECTS
    00111     // DR 60. What is a formatted input function?
    00112     // The inserters for manipulators are *not* formatted output functions.
    00113     return __pf(*this);
    00114       }
    00115
    00116       __ostream_type&
    00117       operator<<(__ios_type& (*__pf)(__ios_type&))
    00118       {
    00119     // _GLIBCXX_RESOLVE_LIB_DEFECTS
    00120     // DR 60. What is a formatted input function?
    00121     // The inserters for manipulators are *not* formatted output functions.
    00122     __pf(*this);
    00123     return *this;
    00124       }
    00125
    00126       __ostream_type&
    00127       operator<<(ios_base& (*__pf) (ios_base&))
    00128       {
    00129     // _GLIBCXX_RESOLVE_LIB_DEFECTS
    00130     // DR 60. What is a formatted input function?
    00131     // The inserters for manipulators are *not* formatted output functions.
    00132     __pf(*this);
    00133     return *this;
    00134       }
    00135       //@}
    00136
    00137       // [27.6.2.5.2] arithmetic inserters
    00138       /**
    00139        *  @name Arithmetic Inserters
    00140        *
    00141        *  All the @c operator<< functions (aka <em>formatted output
    00142        *  functions</em>) have some common behavior.  Each starts by
    00143        *  constructing a temporary object of type std::basic_ostream::sentry.
    00144        *  This can have several effects, concluding with the setting of a
    00145        *  status flag; see the sentry documentation for more.
    00146        *
    00147        *  If the sentry status is good, the function tries to generate
    00148        *  whatever data is appropriate for the type of the argument.
    00149        *
    00150        *  If an exception is thrown during insertion, ios_base::badbit
    00151        *  will be turned on in the stream's error state without causing an
    00152        *  ios_base::failure to be thrown.  The original exception will then
    00153        *  be rethrown.
    00154       */
    00155       //@{
    00156       /**
    00157        *  @brief  Basic arithmetic inserters
    00158        *  @param  A variable of builtin type.
    00159        *  @return  @c *this if successful
    00160        *
    00161        *  These functions use the stream's current locale (specifically, the
    00162        *  @c num_get facet) to perform numeric formatting.
    00163       */
    00164       __ostream_type&
    00165       operator<<(long __n)
    00166       { return _M_insert(__n); }
    00167
    00168       __ostream_type&
    00169       operator<<(unsigned long __n)
    00170       { return _M_insert(__n); }
    00171
    00172       __ostream_type&
    00173       operator<<(bool __n)
    00174       { return _M_insert(__n); }
    00175
    00176       __ostream_type&
    00177       operator<<(short __n);
    00178
    00179       __ostream_type&
    00180       operator<<(unsigned short __n)
    00181       {
    00182     // _GLIBCXX_RESOLVE_LIB_DEFECTS
    00183     // 117. basic_ostream uses nonexistent num_put member functions.
    00184     return _M_insert(static_cast<unsigned long>(__n));
    00185       }
    00186
    00187       __ostream_type&
    00188       operator<<(int __n);
    00189
    00190       __ostream_type&
    00191       operator<<(unsigned int __n)
    00192       {
    00193     // _GLIBCXX_RESOLVE_LIB_DEFECTS
    00194     // 117. basic_ostream uses nonexistent num_put member functions.
    00195     return _M_insert(static_cast<unsigned long>(__n));
    00196       }
    00197
    00198 #ifdef _GLIBCXX_USE_LONG_LONG
    00199       __ostream_type&
    00200       operator<<(long long __n)
    00201       { return _M_insert(__n); }
    00202
    00203       __ostream_type&
    00204       operator<<(unsigned long long __n)
    00205       { return _M_insert(__n); }
    00206 #endif
    00207
    00208       __ostream_type&
    00209       operator<<(double __f)
    00210       { return _M_insert(__f); }
    00211
    00212       __ostream_type&
    00213       operator<<(float __f)
    00214       {
    00215     // _GLIBCXX_RESOLVE_LIB_DEFECTS
    00216     // 117. basic_ostream uses nonexistent num_put member functions.
    00217     return _M_insert(static_cast<double>(__f));
    00218       }
    00219
    00220       __ostream_type&
    00221       operator<<(long double __f)
    00222       { return _M_insert(__f); }
    00223
    00224       __ostream_type&
    00225       operator<<(const void* __p)
    00226       { return _M_insert(__p); }
    00227
    00228       /**
    00229        *  @brief  Extracting from another streambuf.
    00230        *  @param  sb  A pointer to a streambuf
    00231        *
    00232        *  This function behaves like one of the basic arithmetic extractors,
    00233        *  in that it also constructs a sentry object and has the same error
    00234        *  handling behavior.
    00235        *
    00236        *  If @a sb is NULL, the stream will set failbit in its error state.
    00237        *
    00238        *  Characters are extracted from @a sb and inserted into @c *this
    00239        *  until one of the following occurs:
    00240        *
    00241        *  - the input stream reaches end-of-file,
    00242        *  - insertion into the output sequence fails (in this case, the
    00243        *    character that would have been inserted is not extracted), or
    00244        *  - an exception occurs while getting a character from @a sb, which
    00245        *    sets failbit in the error state
    00246        *
    00247        *  If the function inserts no characters, failbit is set.
    00248       */
    00249       __ostream_type&
    00250       operator<<(__streambuf_type* __sb);
    00251       //@}
    00252
    00253       // [27.6.2.6] unformatted output functions
    00254       /**
    00255        *  @name Unformatted Output Functions
    00256        *
    00257        *  All the unformatted output functions have some common behavior.
    00258        *  Each starts by constructing a temporary object of type
    00259        *  std::basic_ostream::sentry.  This has several effects, concluding
    00260        *  with the setting of a status flag; see the sentry documentation
    00261        *  for more.
    00262        *
    00263        *  If the sentry status is good, the function tries to generate
    00264        *  whatever data is appropriate for the type of the argument.
    00265        *
    00266        *  If an exception is thrown during insertion, ios_base::badbit
    00267        *  will be turned on in the stream's error state.  If badbit is on in
    00268        *  the stream's exceptions mask, the exception will be rethrown
    00269        *  without completing its actions.
    00270       */
    00271       //@{
    00272       /**
    00273        *  @brief  Simple insertion.
    00274        *  @param  c  The character to insert.
    00275        *  @return  *this
    00276        *
    00277        *  Tries to insert @a c.
    00278        *
    00279        *  @note  This function is not overloaded on signed char and
    00280        *         unsigned char.
    00281       */
    00282       __ostream_type&
    00283       put(char_type __c);
    00284
    00285       // Core write functionality, without sentry.
    00286       void
    00287       _M_write(const char_type* __s, streamsize __n)
    00288       {
    00289     const streamsize __put = this->rdbuf()->sputn(__s, __n);
    00290     if (__put != __n)
    00291       this->setstate(ios_base::badbit);
    00292       }
    00293
    00294       /**
    00295        *  @brief  Character string insertion.
    00296        *  @param  s  The array to insert.
    00297        *  @param  n  Maximum number of characters to insert.
    00298        *  @return  *this
    00299        *
    00300        *  Characters are copied from @a s and inserted into the stream until
    00301        *  one of the following happens:
    00302        *
    00303        *  - @a n characters are inserted
    00304        *  - inserting into the output sequence fails (in this case, badbit
    00305        *    will be set in the stream's error state)
    00306        *
    00307        *  @note  This function is not overloaded on signed char and
    00308        *         unsigned char.
    00309       */
    00310       __ostream_type&
    00311       write(const char_type* __s, streamsize __n);
    00312       //@}
    00313
    00314       /**
    00315        *  @brief  Synchronizing the stream buffer.
    00316        *  @return  *this
    00317        *
    00318        *  If @c rdbuf() is a null pointer, changes nothing.
    00319        *
    00320        *  Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
    00321        *  sets badbit.
    00322       */
    00323       __ostream_type&
    00324       flush();
    00325
    00326       // [27.6.2.4] seek members
    00327       /**
    00328        *  @brief  Getting the current write position.
    00329        *  @return  A file position object.
    00330        *
    00331        *  If @c fail() is not false, returns @c pos_type(-1) to indicate
    00332        *  failure.  Otherwise returns @c rdbuf()->pubseekoff(0,cur,out).
    00333       */
    00334       pos_type
    00335       tellp();
    00336
    00337       /**
    00338        *  @brief  Changing the current write position.
    00339        *  @param  pos  A file position object.
    00340        *  @return  *this
    00341        *
    00342        *  If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos).  If
    00343        *  that function fails, sets failbit.
    00344       */
    00345       __ostream_type&
    00346       seekp(pos_type);
    00347
    00348       /**
    00349        *  @brief  Changing the current write position.
    00350        *  @param  off  A file offset object.
    00351        *  @param  dir  The direction in which to seek.
    00352        *  @return  *this
    00353        *
    00354        *  If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
    00355        *  If that function fails, sets failbit.
    00356       */
    00357        __ostream_type&
    00358       seekp(off_type, ios_base::seekdir);
    00359
    00360     protected:
    00361       basic_ostream()
    00362       { this->init(0); }
    00363
    00364       template<typename _ValueT>
    00365         __ostream_type&
    00366         _M_insert(_ValueT __v);
    00367     };
    00368
    00369   /**
    00370    *  @brief  Performs setup work for output streams.
    00371    *
    00372    *  Objects of this class are created before all of the standard
    00373    *  inserters are run.  It is responsible for <em>exception-safe prefix and
    00374    *  suffix operations</em>.
    00375   */
    00376   template <typename _CharT, typename _Traits>
    00377     class basic_ostream<_CharT, _Traits>::sentry
    00378     {
    00379       // Data Members.
    00380       bool              _M_ok;
    00381       basic_ostream<_CharT, _Traits>&   _M_os;
    00382
    00383     public:
    00384       /**
    00385        *  @brief  The constructor performs preparatory work.
    00386        *  @param  os  The output stream to guard.
    00387        *
    00388        *  If the stream state is good (@a os.good() is true), then if the
    00389        *  stream is tied to another output stream, @c is.tie()->flush()
    00390        *  is called to synchronize the output sequences.
    00391        *
    00392        *  If the stream state is still good, then the sentry state becomes
    00393        *  true (@a okay).
    00394       */
    00395       explicit
    00396       sentry(basic_ostream<_CharT, _Traits>& __os);
    00397
    00398       /**
    00399        *  @brief  Possibly flushes the stream.
    00400        *
    00401        *  If @c ios_base::unitbuf is set in @c os.flags(), and
    00402        *  @c std::uncaught_exception() is true, the sentry destructor calls
    00403        *  @c flush() on the output stream.
    00404       */
    00405       ~sentry()
    00406       {
    00407     // XXX MT
    00408     if (bool(_M_os.flags() & ios_base::unitbuf) && !uncaught_exception())
    00409       {
    00410         // Can't call flush directly or else will get into recursive lock.
    00411         if (_M_os.rdbuf() && _M_os.rdbuf()->pubsync() == -1)
    00412           _M_os.setstate(ios_base::badbit);
    00413       }
    00414       }
    00415
    00416       /**
    00417        *  @brief  Quick status checking.
    00418        *  @return  The sentry state.
    00419        *
    00420        *  For ease of use, sentries may be converted to booleans.  The
    00421        *  return value is that of the sentry state (true == okay).
    00422       */
    00423 #ifdef __GXX_EXPERIMENTAL_CXX0X__
    00424       explicit
    00425 #endif
    00426       operator bool() const
    00427       { return _M_ok; }
    00428     };
    00429
    00430   // [27.6.2.5.4] character insertion templates
    00431   //@{
    00432   /**
    00433    *  @brief  Character inserters
    00434    *  @param  out  An output stream.
    00435    *  @param  c  A character.
    00436    *  @return  out
    00437    *
    00438    *  Behaves like one of the formatted arithmetic inserters described in
    00439    *  std::basic_ostream.  After constructing a sentry object with good
    00440    *  status, this function inserts a single character and any required
    00441    *  padding (as determined by [22.2.2.2.2]).  @c out.width(0) is then
    00442    *  called.
    00443    *
    00444    *  If @a c is of type @c char and the character type of the stream is not
    00445    *  @c char, the character is widened before insertion.
    00446   */
    00447   template<typename _CharT, typename _Traits>
    00448     inline basic_ostream<_CharT, _Traits>&
    00449     operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c)
    00450     { return __ostream_insert(__out, &__c, 1); }
    00451
    00452   template<typename _CharT, typename _Traits>
    00453     inline basic_ostream<_CharT, _Traits>&
    00454     operator<<(basic_ostream<_CharT, _Traits>& __out, char __c)
    00455     { return (__out << __out.widen(__c)); }
    00456
    00457   // Specialization
    00458   template <class _Traits>
    00459     inline basic_ostream<char, _Traits>&
    00460     operator<<(basic_ostream<char, _Traits>& __out, char __c)
    00461     { return __ostream_insert(__out, &__c, 1); }
    00462
    00463   // Signed and unsigned
    00464   template<class _Traits>
    00465     inline basic_ostream<char, _Traits>&
    00466     operator<<(basic_ostream<char, _Traits>& __out, signed char __c)
    00467     { return (__out << static_cast<char>(__c)); }
    00468
    00469   template<class _Traits>
    00470     inline basic_ostream<char, _Traits>&
    00471     operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c)
    00472     { return (__out << static_cast<char>(__c)); }
    00473   //@}
    00474
    00475   //@{
    00476   /**
    00477    *  @brief  String inserters
    00478    *  @param  out  An output stream.
    00479    *  @param  s  A character string.
    00480    *  @return  out
    00481    *  @pre  @a s must be a non-NULL pointer
    00482    *
    00483    *  Behaves like one of the formatted arithmetic inserters described in
    00484    *  std::basic_ostream.  After constructing a sentry object with good
    00485    *  status, this function inserts @c traits::length(s) characters starting
    00486    *  at @a s, widened if necessary, followed by any required padding (as
    00487    *  determined by [22.2.2.2.2]).  @c out.width(0) is then called.
    00488   */
    00489   template<typename _CharT, typename _Traits>
    00490     inline basic_ostream<_CharT, _Traits>&
    00491     operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s)
    00492     {
    00493       if (!__s)
    00494     __out.setstate(ios_base::badbit);
    00495       else
    00496     __ostream_insert(__out, __s,
    00497              static_cast<streamsize>(_Traits::length(__s)));
    00498       return __out;
    00499     }
    00500
    00501   template<typename _CharT, typename _Traits>
    00502     basic_ostream<_CharT, _Traits> &
    00503     operator<<(basic_ostream<_CharT, _Traits>& __out, const char* __s);
    00504
    00505   // Partial specializations
    00506   template<class _Traits>
    00507     inline basic_ostream<char, _Traits>&
    00508     operator<<(basic_ostream<char, _Traits>& __out, const char* __s)
    00509     {
    00510       if (!__s)
    00511     __out.setstate(ios_base::badbit);
    00512       else
    00513     __ostream_insert(__out, __s,
    00514              static_cast<streamsize>(_Traits::length(__s)));
    00515       return __out;
    00516     }
    00517
    00518   // Signed and unsigned
    00519   template<class _Traits>
    00520     inline basic_ostream<char, _Traits>&
    00521     operator<<(basic_ostream<char, _Traits>& __out, const signed char* __s)
    00522     { return (__out << reinterpret_cast<const char*>(__s)); }
    00523
    00524   template<class _Traits>
    00525     inline basic_ostream<char, _Traits> &
    00526     operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s)
    00527     { return (__out << reinterpret_cast<const char*>(__s)); }
    00528   //@}
    00529
    00530   // [27.6.2.7] standard basic_ostream manipulators
    00531   /**
    00532    *  @brief  Write a newline and flush the stream.
    00533    *
    00534    *  This manipulator is often mistakenly used when a simple newline is
    00535    *  desired, leading to poor buffering performance.  See
    00536    *  http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch25s02.html
    00537    *  for more on this subject.
    00538   */
    00539   template<typename _CharT, typename _Traits>
    00540     inline basic_ostream<_CharT, _Traits>&
    00541     endl(basic_ostream<_CharT, _Traits>& __os)
    00542     { return flush(__os.put(__os.widen('\n'))); }
    00543
    00544   /**
    00545    *  @brief  Write a null character into the output sequence.
    00546    *
    00547    *  <em>Null character</em> is @c CharT() by definition.  For CharT of @c char,
    00548    *  this correctly writes the ASCII @c NUL character string terminator.
    00549   */
    00550   template<typename _CharT, typename _Traits>
    00551     inline basic_ostream<_CharT, _Traits>&
    00552     ends(basic_ostream<_CharT, _Traits>& __os)
    00553     { return __os.put(_CharT()); }
    00554
    00555   /**
    00556    *  @brief  Flushes the output stream.
    00557    *
    00558    *  This manipulator simply calls the stream's @c flush() member function.
    00559   */
    00560   template<typename _CharT, typename _Traits>
    00561     inline basic_ostream<_CharT, _Traits>&
    00562     flush(basic_ostream<_CharT, _Traits>& __os)
    00563     { return __os.flush(); }
    00564
    00565 #ifdef __GXX_EXPERIMENTAL_CXX0X__
    00566   // [27.7.2.9] Rvalue stream insertion
    00567   /**
    00568    *  @brief  Generic inserter for rvalue stream
    00569    *  @param  os  An input stream.
    00570    *  @param  x  A reference to the object being inserted.
    00571    *  @return  os
    00572    *
    00573    *  This is just a forwarding function to allow insertion to
    00574    *  rvalue streams since they won't bind to the inserter functions
    00575    *  that take an lvalue reference.
    00576   */
    00577   template<typename _CharT, typename _Traits, typename _Tp>
    00578     inline basic_ostream<_CharT, _Traits>&
    00579     operator<<(basic_ostream<_CharT, _Traits>&& __os, const _Tp& __x)
    00580     { return (__os << __x); }
    00581 #endif // __GXX_EXPERIMENTAL_CXX0X__
    00582
    00583 _GLIBCXX_END_NAMESPACE
    00584
    00585 #ifndef _GLIBCXX_EXPORT_TEMPLATE
    00586 # include <bits/ostream.tcc>
    00587 #endif
    00588
    00589 #endif  /* _GLIBCXX_OSTREAM */