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