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