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