1 // Output streams -*- C++ -*- 2 3 // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 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 _CPP_OSTREAM 41 #define _CPP_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 ostreambuf_iterator<_CharT, _Traits> __ostreambuf_iter; 73 typedef num_put<_CharT, __ostreambuf_iter> __numput_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 __ostream_type& 131 operator<<(__ostream_type& (*__pf)(__ostream_type&)); 132 133 __ostream_type& 134 operator<<(__ios_type& (*__pf)(__ios_type&)); 135 136 __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 _GLIBCPP_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 onject 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 /** 285 * @brief Character string insertion. 286 * @param s The array to insert. 287 * @param n Maximum number of characters to insert. 288 * @return *this 289 * 290 * Characters are copied from @a s and inserted into the stream until 291 * one of the following happens: 292 * 293 * - @a n characters are inserted 294 * - inserting into the output sequence fails (in this case, badbit 295 * will be set in the stream's error state) 296 * 297 * @note This function is not overloaded on signed char and 298 * unsigned char. 299 */ 300 __ostream_type& 301 write(const char_type* __s, streamsize __n); 302 //@} 303 304 /** 305 * @brief Synchronizing the stream buffer. 306 * @return *this 307 * 308 * If @c rdbuf() is a null pointer, changes nothing. 309 * 310 * Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1, 311 * sets badbit. 312 */ 313 __ostream_type& 314 flush(); 315 316 // [27.6.2.4] seek members 317 /** 318 * @brief Getting the current write position. 319 * @return A file position object. 320 * 321 * If @c fail() is not false, returns @c pos_type(-1) to indicate 322 * failure. Otherwise returns @c rdbuf()->pubseekoff(0,cur,out). 323 */ 324 pos_type 325 tellp(); 326 327 /** 328 * @brief Changing the current write position. 329 * @param pos A file position object. 330 * @return *this 331 * 332 * If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos). If 333 * that function fails, sets failbit. 334 */ 335 __ostream_type& 336 seekp(pos_type); 337 338 /** 339 * @brief Changing the current write position. 340 * @param off A file offset object. 341 * @param dir The direction in which to seek. 342 * @return *this 343 * 344 * If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir). 345 * If that function fails, sets failbit. 346 */ 347 __ostream_type& 348 seekp(off_type, ios_base::seekdir); 349 }; 350 351 /** 352 * @brief Performs setup work for output streams. 353 * 354 * Objects of this class are created before all of the standard 355 * inserters are run. It is responsible for "exception-safe prefix and 356 * suffix operations." Additional actions may be added by the 357 * implementation, and we list them in 358 * http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5 359 * under [27.6] notes. 360 */ 361 template <typename _CharT, typename _Traits> 362 class basic_ostream<_CharT, _Traits>::sentry 363 { 364 // Data Members: 365 bool _M_ok; 366 basic_ostream<_CharT,_Traits>& _M_os; 367 368 public: 369 /** 370 * @brief The constructor performs preparatory work. 371 * @param os The output stream to guard. 372 * 373 * If the stream state is good (@a os.good() is true), then if the 374 * stream is tied to another output stream, @c is.tie()->flush() 375 * is called to synchronize the output sequences. 376 * 377 * If the stream state is still good, then the sentry state becomes 378 * true ("okay"). 379 */ 380 explicit 381 sentry(basic_ostream<_CharT,_Traits>& __os); 382 383 /** 384 * @brief Possibly flushes the stream. 385 * 386 * If @c ios_base::unitbuf is set in @c os.flags(), and 387 * @c std::uncaught_exception() is true, the sentry destructor calls 388 * @c flush() on the output stream. 389 */ 390 ~sentry() 391 { 392 // XXX MT 393 if (_M_os.flags() & ios_base::unitbuf && !uncaught_exception()) 394 { 395 // Can't call flush directly or else will get into recursive lock. 396 if (_M_os.rdbuf() && _M_os.rdbuf()->pubsync() == -1) 397 _M_os.setstate(ios_base::badbit); 398 } 399 } 400 401 /** 402 * @brief Quick status checking. 403 * @return The sentry state. 404 * 405 * For ease of use, sentries may be converted to booleans. The 406 * return value is that of the sentry state (true == okay). 407 */ 408 operator bool() 409 { return _M_ok; } 410 }; 411 412 // [27.6.2.5.4] character insertion templates 413 //@{ 414 /** 415 * @brief Character inserters 416 * @param out An output stream. 417 * @param c A character. 418 * @return out 419 * 420 * Behaves like one of the formatted arithmetic inserters described in 421 * std::basic_ostream. After constructing a sentry object with good 422 * status, this function inserts a single character and any required 423 * padding (as determined by [22.2.2.2.2]). @c out.width(0) is then 424 * called. 425 * 426 * If @a c is of type @c char and the character type of the stream is not 427 * @c char, the character is widened before insertion. 428 */ 429 template<typename _CharT, typename _Traits> 430 basic_ostream<_CharT, _Traits>& 431 operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c); 432 433 template<typename _CharT, typename _Traits> 434 basic_ostream<_CharT, _Traits>& 435 operator<<(basic_ostream<_CharT, _Traits>& __out, char __c) 436 { return (__out << __out.widen(__c)); } 437 438 // Specialization 439 template <class _Traits> 440 basic_ostream<char, _Traits>& 441 operator<<(basic_ostream<char, _Traits>& __out, char __c); 442 443 // Signed and unsigned 444 template<class _Traits> 445 basic_ostream<char, _Traits>& 446 operator<<(basic_ostream<char, _Traits>& __out, signed char __c) 447 { return (__out << static_cast<char>(__c)); } 448 449 template<class _Traits> 450 basic_ostream<char, _Traits>& 451 operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c) 452 { return (__out << static_cast<char>(__c)); } 453 //@} 454 455 //@{ 456 /** 457 * @brief String inserters 458 * @param out An output stream. 459 * @param s A character string. 460 * @return out 461 * @pre @a s must be a non-NULL pointer 462 * 463 * Behaves like one of the formatted arithmetic inserters described in 464 * std::basic_ostream. After constructing a sentry object with good 465 * status, this function inserts @c traits::length(s) characters starting 466 * at @a s, widened if necessary, followed by any required padding (as 467 * determined by [22.2.2.2.2]). @c out.width(0) is then called. 468 */ 469 template<typename _CharT, typename _Traits> 470 basic_ostream<_CharT, _Traits>& 471 operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s); 472 473 template<typename _CharT, typename _Traits> 474 basic_ostream<_CharT, _Traits> & 475 operator<<(basic_ostream<_CharT, _Traits>& __out, const char* __s); 476 477 // Partial specializationss 478 template<class _Traits> 479 basic_ostream<char, _Traits>& 480 operator<<(basic_ostream<char, _Traits>& __out, const char* __s); 481 482 // Signed and unsigned 483 template<class _Traits> 484 basic_ostream<char, _Traits>& 485 operator<<(basic_ostream<char, _Traits>& __out, const signed char* __s) 486 { return (__out << reinterpret_cast<const char*>(__s)); } 487 488 template<class _Traits> 489 basic_ostream<char, _Traits> & 490 operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s) 491 { return (__out << reinterpret_cast<const char*>(__s)); } 492 //@} 493 494 // [27.6.2.7] standard basic_ostream manipulators 495 /** 496 * @brief Write a newline and flush the stream. 497 * 498 * This manipulator is often mistakenly used when a simple newline is 499 * desired, leading to poor buffering performance. See 500 * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for more 501 * on this subject. 502 */ 503 template<typename _CharT, typename _Traits> 504 basic_ostream<_CharT, _Traits>& 505 endl(basic_ostream<_CharT, _Traits>& __os) 506 { return flush(__os.put(__os.widen('\n'))); } 507 508 /** 509 * @brief Write a null character into the output sequence. 510 * 511 * "Null character" is @c CharT() by definition. For CharT of @c char, 512 * this correctly writes the ASCII @c NUL character string terminator. 513 */ 514 template<typename _CharT, typename _Traits> 515 basic_ostream<_CharT, _Traits>& 516 ends(basic_ostream<_CharT, _Traits>& __os) 517 { return __os.put(_CharT()); } 518 519 /** 520 * @brief Flushes the output stream. 521 * 522 * This manipulator simply calls the stream's @c flush() member function. 523 */ 524 template<typename _CharT, typename _Traits> 525 basic_ostream<_CharT, _Traits>& 526 flush(basic_ostream<_CharT, _Traits>& __os) 527 { return __os.flush(); } 528 529 } // namespace std 530 531 #ifdef _GLIBCPP_NO_TEMPLATE_EXPORT 532 # define export 533 #endif 534 #ifdef _GLIBCPP_FULLY_COMPLIANT_HEADERS 535 # include <bits/ostream.tcc> 536 #endif 537 538 #endif /* _CPP_OSTREAM */ 539