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
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
00019 // along with this library; see the file COPYING.  If not, write to
00020 // the Free Software Foundation, 51 Franklin Street, Fifth Floor,
00021 // Boston, MA 02110-1301, 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        *  Manipulators 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       basic_ostream()
00366       { this->init(0); }
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." 
00379   */
00380   template <typename _CharT, typename _Traits>
00381     class basic_ostream<_CharT, _Traits>::sentry
00382     {
00383       // Data Members:
00384       bool              _M_ok;
00385       basic_ostream<_CharT, _Traits>&   _M_os;
00386       
00387     public:
00388       /**
00389        *  @brief  The constructor performs preparatory work.
00390        *  @param  os  The output stream to guard.
00391        *
00392        *  If the stream state is good (@a os.good() is true), then if the
00393        *  stream is tied to another output stream, @c is.tie()->flush()
00394        *  is called to synchronize the output sequences.
00395        *
00396        *  If the stream state is still good, then the sentry state becomes
00397        *  true ("okay").
00398       */
00399       explicit
00400       sentry(basic_ostream<_CharT, _Traits>& __os);
00401 
00402       /**
00403        *  @brief  Possibly flushes the stream.
00404        *
00405        *  If @c ios_base::unitbuf is set in @c os.flags(), and
00406        *  @c std::uncaught_exception() is true, the sentry destructor calls
00407        *  @c flush() on the output stream.
00408       */
00409       ~sentry()
00410       {
00411     // XXX MT
00412     if (bool(_M_os.flags() & ios_base::unitbuf) && !uncaught_exception())
00413       {
00414         // Can't call flush directly or else will get into recursive lock.
00415         if (_M_os.rdbuf() && _M_os.rdbuf()->pubsync() == -1)
00416           _M_os.setstate(ios_base::badbit);
00417       }
00418       }
00419 
00420       /**
00421        *  @brief  Quick status checking.
00422        *  @return  The sentry state.
00423        *
00424        *  For ease of use, sentries may be converted to booleans.  The
00425        *  return value is that of the sentry state (true == okay).
00426       */
00427       operator bool() const
00428       { return _M_ok; }
00429     };
00430 
00431   // [27.6.2.5.4] character insertion templates
00432   //@{
00433   /**
00434    *  @brief  Character inserters
00435    *  @param  out  An output stream.
00436    *  @param  c  A character.
00437    *  @return  out
00438    *
00439    *  Behaves like one of the formatted arithmetic inserters described in
00440    *  std::basic_ostream.  After constructing a sentry object with good
00441    *  status, this function inserts a single character and any required
00442    *  padding (as determined by [22.2.2.2.2]).  @c out.width(0) is then
00443    *  called.
00444    *
00445    *  If @a c is of type @c char and the character type of the stream is not
00446    *  @c char, the character is widened before insertion.
00447   */
00448   template<typename _CharT, typename _Traits>
00449     inline basic_ostream<_CharT, _Traits>&
00450     operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c)
00451     { return __ostream_insert(__out, &__c, 1); }
00452 
00453   template<typename _CharT, typename _Traits>
00454     inline basic_ostream<_CharT, _Traits>&
00455     operator<<(basic_ostream<_CharT, _Traits>& __out, char __c)
00456     { return (__out << __out.widen(__c)); }
00457 
00458   // Specialization
00459   template <class _Traits> 
00460     inline basic_ostream<char, _Traits>&
00461     operator<<(basic_ostream<char, _Traits>& __out, char __c)
00462     { return __ostream_insert(__out, &__c, 1); }
00463 
00464   // Signed and unsigned
00465   template<class _Traits>
00466     inline basic_ostream<char, _Traits>&
00467     operator<<(basic_ostream<char, _Traits>& __out, signed char __c)
00468     { return (__out << static_cast<char>(__c)); }
00469   
00470   template<class _Traits>
00471     inline basic_ostream<char, _Traits>&
00472     operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c)
00473     { return (__out << static_cast<char>(__c)); }
00474   //@}
00475   
00476   //@{
00477   /**
00478    *  @brief  String inserters
00479    *  @param  out  An output stream.
00480    *  @param  s  A character string.
00481    *  @return  out
00482    *  @pre  @a s must be a non-NULL pointer
00483    *
00484    *  Behaves like one of the formatted arithmetic inserters described in
00485    *  std::basic_ostream.  After constructing a sentry object with good
00486    *  status, this function inserts @c traits::length(s) characters starting
00487    *  at @a s, widened if necessary, followed by any required padding (as
00488    *  determined by [22.2.2.2.2]).  @c out.width(0) is then called.
00489   */
00490   template<typename _CharT, typename _Traits>
00491     inline basic_ostream<_CharT, _Traits>&
00492     operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s)
00493     {
00494       if (!__s)
00495     __out.setstate(ios_base::badbit);
00496       else
00497     __ostream_insert(__out, __s,
00498              static_cast<streamsize>(_Traits::length(__s)));
00499       return __out;
00500     }
00501 
00502   template<typename _CharT, typename _Traits>
00503     basic_ostream<_CharT, _Traits> &
00504     operator<<(basic_ostream<_CharT, _Traits>& __out, const char* __s);
00505 
00506   // Partial specializations
00507   template<class _Traits>
00508     inline basic_ostream<char, _Traits>&
00509     operator<<(basic_ostream<char, _Traits>& __out, const char* __s)
00510     {
00511       if (!__s)
00512     __out.setstate(ios_base::badbit);
00513       else
00514     __ostream_insert(__out, __s,
00515              static_cast<streamsize>(_Traits::length(__s)));
00516       return __out;
00517     }
00518 
00519   // Signed and unsigned
00520   template<class _Traits>
00521     inline basic_ostream<char, _Traits>&
00522     operator<<(basic_ostream<char, _Traits>& __out, const signed char* __s)
00523     { return (__out << reinterpret_cast<const char*>(__s)); }
00524 
00525   template<class _Traits>
00526     inline basic_ostream<char, _Traits> &
00527     operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s)
00528     { return (__out << reinterpret_cast<const char*>(__s)); }
00529   //@}
00530 
00531   // [27.6.2.7] standard basic_ostream manipulators
00532   /**
00533    *  @brief  Write a newline and flush the stream.
00534    *
00535    *  This manipulator is often mistakenly used when a simple newline is
00536    *  desired, leading to poor buffering performance.  See
00537    *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for more
00538    *  on this subject.
00539   */
00540   template<typename _CharT, typename _Traits>
00541     inline basic_ostream<_CharT, _Traits>& 
00542     endl(basic_ostream<_CharT, _Traits>& __os)
00543     { return flush(__os.put(__os.widen('\n'))); }
00544 
00545   /**
00546    *  @brief  Write a null character into the output sequence.
00547    *
00548    *  "Null character" is @c CharT() by definition.  For CharT of @c char,
00549    *  this correctly writes the ASCII @c NUL character string terminator.
00550   */
00551   template<typename _CharT, typename _Traits>
00552     inline basic_ostream<_CharT, _Traits>& 
00553     ends(basic_ostream<_CharT, _Traits>& __os)
00554     { return __os.put(_CharT()); }
00555   
00556   /**
00557    *  @brief  Flushes the output stream.
00558    *
00559    *  This manipulator simply calls the stream's @c flush() member function.
00560   */
00561   template<typename _CharT, typename _Traits>
00562     inline basic_ostream<_CharT, _Traits>& 
00563     flush(basic_ostream<_CharT, _Traits>& __os)
00564     { return __os.flush(); }
00565 
00566 _GLIBCXX_END_NAMESPACE
00567 
00568 #ifndef _GLIBCXX_EXPORT_TEMPLATE
00569 # include <bits/ostream.tcc>
00570 #endif
00571 
00572 #endif  /* _GLIBCXX_OSTREAM */

Generated on Sat Dec 12 09:40:12 2009 for libstdc++ by  doxygen 1.5.6