Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/c++/15/bits/basic_ios.h
1 // Iostreams base classes -*- C++ -*- 2 3 // Copyright (C) 1997-2025 Free Software Foundation, Inc. 4 // 5 // This file is part of the GNU ISO C++ Library. This library is free 6 // software; you can redistribute it and/or modify it under the 7 // terms of the GNU General Public License as published by the 8 // Free Software Foundation; either version 3, or (at your option) 9 // any later version. 10 11 // This library is distributed in the hope that it will be useful, 12 // but WITHOUT ANY WARRANTY; without even the implied warranty of 13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 // GNU General Public License for more details. 15 16 // Under Section 7 of GPL version 3, you are granted additional 17 // permissions described in the GCC Runtime Library Exception, version 18 // 3.1, as published by the Free Software Foundation. 19 20 // You should have received a copy of the GNU General Public License and 21 // a copy of the GCC Runtime Library Exception along with this program; 22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see 23 // <http://www.gnu.org/licenses/>. 24 25 /** @file bits/basic_ios.h 26 * This is an internal header file, included by other library headers. 27 * Do not attempt to use it directly. @headername{ios} 28 */ 29 30 #ifndef _BASIC_IOS_H 31 #define _BASIC_IOS_H 1 32 33 #ifdef _GLIBCXX_SYSHDR 34 #pragma GCC system_header 35 #endif 36 37 #include <bits/localefwd.h> 38 #include <bits/locale_classes.h> 39 #include <bits/locale_facets.h> 40 #include <bits/streambuf_iterator.h> 41 #include <bits/move.h> 42 43 namespace std _GLIBCXX_VISIBILITY(default) 44 { 45 _GLIBCXX_BEGIN_NAMESPACE_VERSION 46 47 template<typename _Facet> 48 inline const _Facet& 49 __check_facet(const _Facet* __f) 50 { 51 if (!__f) 52 __throw_bad_cast(); 53 return *__f; 54 } 55 56 /** 57 * @brief Template class basic_ios, virtual base class for all 58 * stream classes. 59 * @ingroup io 60 * 61 * @tparam _CharT Type of character stream. 62 * @tparam _Traits Traits for character type, defaults to 63 * char_traits<_CharT>. 64 * 65 * Most of the member functions called dispatched on stream objects 66 * (e.g., @c std::cout.foo(bar);) are consolidated in this class. 67 */ 68 template<typename _CharT, typename _Traits> 69 class basic_ios : public ios_base 70 { 71 #if __cplusplus >= 202002L 72 static_assert(is_same_v<_CharT, typename _Traits::char_type>); 73 #endif 74 75 public: 76 ///@{ 77 /** 78 * These are standard types. They permit a standardized way of 79 * referring to names of (or names dependent on) the template 80 * parameters, which are specific to the implementation. 81 */ 82 typedef _CharT char_type; 83 typedef typename _Traits::int_type int_type; 84 typedef typename _Traits::pos_type pos_type; 85 typedef typename _Traits::off_type off_type; 86 typedef _Traits traits_type; 87 ///@} 88 89 ///@{ 90 /** 91 * These are non-standard types. 92 */ 93 typedef ctype<_CharT> __ctype_type; 94 typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> > 95 __num_put_type; 96 typedef num_get<_CharT, istreambuf_iterator<_CharT, _Traits> > 97 __num_get_type; 98 ///@} 99 100 // Data members: 101 protected: 102 basic_ostream<_CharT, _Traits>* _M_tie; 103 mutable char_type _M_fill; 104 mutable bool _M_fill_init; 105 basic_streambuf<_CharT, _Traits>* _M_streambuf; 106 107 // Cached use_facet<ctype>, which is based on the current locale info. 108 const __ctype_type* _M_ctype; 109 // For ostream. 110 const __num_put_type* _M_num_put; 111 // For istream. 112 const __num_get_type* _M_num_get; 113 114 public: 115 ///@{ 116 /** 117 * @brief The quick-and-easy status check. 118 * 119 * This allows you to write constructs such as 120 * <code>if (!a_stream) ...</code> and <code>while (a_stream) ...</code> 121 */ 122 #if __cplusplus >= 201103L 123 _GLIBCXX_NODISCARD 124 explicit operator bool() const 125 { return !this->fail(); } 126 #else 127 operator void*() const 128 { return this->fail() ? 0 : const_cast<basic_ios*>(this); } 129 #endif 130 131 _GLIBCXX_NODISCARD 132 bool 133 operator!() const 134 { return this->fail(); } 135 ///@} 136 137 /** 138 * @brief Returns the error state of the stream buffer. 139 * @return A bit pattern (well, isn't everything?) 140 * 141 * See std::ios_base::iostate for the possible bit values. Most 142 * users will call one of the interpreting wrappers, e.g., good(). 143 */ 144 _GLIBCXX_NODISCARD 145 iostate 146 rdstate() const 147 { return _M_streambuf_state; } 148 149 /** 150 * @brief [Re]sets the error state. 151 * @param __state The new state flag(s) to set. 152 * 153 * See std::ios_base::iostate for the possible bit values. Most 154 * users will not need to pass an argument. 155 */ 156 void 157 clear(iostate __state = goodbit); 158 159 /** 160 * @brief Sets additional flags in the error state. 161 * @param __state The additional state flag(s) to set. 162 * 163 * See std::ios_base::iostate for the possible bit values. 164 */ 165 void 166 setstate(iostate __state) 167 { this->clear(this->rdstate() | __state); } 168 169 // Flips the internal state on for the proper state bits, then 170 // rethrows the propagated exception if bit also set in 171 // exceptions(). Must only be called within a catch handler. 172 void 173 _M_setstate(iostate __state) 174 { 175 // 27.6.1.2.1 Common requirements. 176 // Turn this on without causing an ios::failure to be thrown. 177 _M_streambuf_state |= __state; 178 if (this->exceptions() & __state) 179 { __throw_exception_again; } 180 } 181 182 /** 183 * @brief Fast error checking. 184 * @return True if no error flags are set. 185 * 186 * A wrapper around rdstate. 187 */ 188 _GLIBCXX_NODISCARD 189 bool 190 good() const 191 { return this->rdstate() == 0; } 192 193 /** 194 * @brief Fast error checking. 195 * @return True if the eofbit is set. 196 * 197 * Note that other iostate flags may also be set. 198 */ 199 _GLIBCXX_NODISCARD 200 bool 201 eof() const 202 { return (this->rdstate() & eofbit) != 0; } 203 204 /** 205 * @brief Fast error checking. 206 * @return True if either the badbit or the failbit is set. 207 * 208 * Checking the badbit in fail() is historical practice. 209 * Note that other iostate flags may also be set. 210 */ 211 _GLIBCXX_NODISCARD 212 bool 213 fail() const 214 { return (this->rdstate() & (badbit | failbit)) != 0; } 215 216 /** 217 * @brief Fast error checking. 218 * @return True if the badbit is set. 219 * 220 * Note that other iostate flags may also be set. 221 */ 222 _GLIBCXX_NODISCARD 223 bool 224 bad() const 225 { return (this->rdstate() & badbit) != 0; } 226 227 /** 228 * @brief Throwing exceptions on errors. 229 * @return The current exceptions mask. 230 * 231 * This changes nothing in the stream. See the one-argument version 232 * of exceptions(iostate) for the meaning of the return value. 233 */ 234 _GLIBCXX_NODISCARD 235 iostate 236 exceptions() const 237 { return _M_exception; } 238 239 /** 240 * @brief Throwing exceptions on errors. 241 * @param __except The new exceptions mask. 242 * 243 * By default, error flags are set silently. You can set an 244 * exceptions mask for each stream; if a bit in the mask becomes set 245 * in the error flags, then an exception of type 246 * std::ios_base::failure is thrown. 247 * 248 * If the error flag is already set when the exceptions mask is 249 * added, the exception is immediately thrown. Try running the 250 * following under GCC 3.1 or later: 251 * @code 252 * #include <iostream> 253 * #include <fstream> 254 * #include <exception> 255 * 256 * int main() 257 * { 258 * std::set_terminate (__gnu_cxx::__verbose_terminate_handler); 259 * 260 * std::ifstream f ("/etc/motd"); 261 * 262 * std::cerr << "Setting badbit\n"; 263 * f.setstate (std::ios_base::badbit); 264 * 265 * std::cerr << "Setting exception mask\n"; 266 * f.exceptions (std::ios_base::badbit); 267 * } 268 * @endcode 269 */ 270 void 271 exceptions(iostate __except) 272 { 273 _M_exception = __except; 274 this->clear(_M_streambuf_state); 275 } 276 277 // Constructor/destructor: 278 /** 279 * @brief Constructor performs initialization. 280 * 281 * The parameter is passed by derived streams. 282 */ 283 explicit 284 basic_ios(basic_streambuf<_CharT, _Traits>* __sb) 285 : ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0), 286 _M_ctype(0), _M_num_put(0), _M_num_get(0) 287 { this->init(__sb); } 288 289 /** 290 * @brief Empty. 291 * 292 * The destructor does nothing. More specifically, it does not 293 * destroy the streambuf held by rdbuf(). 294 */ 295 virtual 296 ~basic_ios() { } 297 298 // Members: 299 /** 300 * @brief Fetches the current @e tied stream. 301 * @return A pointer to the tied stream, or NULL if the stream is 302 * not tied. 303 * 304 * A stream may be @e tied (or synchronized) to a second output 305 * stream. When this stream performs any I/O, the tied stream is 306 * first flushed. For example, @c std::cin is tied to @c std::cout. 307 */ 308 _GLIBCXX_NODISCARD 309 basic_ostream<_CharT, _Traits>* 310 tie() const 311 { return _M_tie; } 312 313 /** 314 * @brief Ties this stream to an output stream. 315 * @param __tiestr The output stream. 316 * @return The previously tied output stream, or NULL if the stream 317 * was not tied. 318 * 319 * This sets up a new tie; see tie() for more. 320 */ 321 basic_ostream<_CharT, _Traits>* 322 tie(basic_ostream<_CharT, _Traits>* __tiestr) 323 { 324 basic_ostream<_CharT, _Traits>* __old = _M_tie; 325 _M_tie = __tiestr; 326 return __old; 327 } 328 329 /** 330 * @brief Accessing the underlying buffer. 331 * @return The current stream buffer. 332 * 333 * This does not change the state of the stream. 334 */ 335 _GLIBCXX_NODISCARD 336 basic_streambuf<_CharT, _Traits>* 337 rdbuf() const 338 { return _M_streambuf; } 339 340 /** 341 * @brief Changing the underlying buffer. 342 * @param __sb The new stream buffer. 343 * @return The previous stream buffer. 344 * 345 * Associates a new buffer with the current stream, and clears the 346 * error state. 347 * 348 * Due to historical accidents which the LWG refuses to correct, the 349 * I/O library suffers from a design error: this function is hidden 350 * in derived classes by overrides of the zero-argument @c rdbuf(), 351 * which is non-virtual for hysterical raisins. As a result, you 352 * must use explicit qualifications to access this function via any 353 * derived class. For example: 354 * 355 * @code 356 * std::fstream foo; // or some other derived type 357 * std::streambuf* p = .....; 358 * 359 * foo.ios::rdbuf(p); // ios == basic_ios<char> 360 * @endcode 361 */ 362 basic_streambuf<_CharT, _Traits>* 363 rdbuf(basic_streambuf<_CharT, _Traits>* __sb); 364 365 /** 366 * @brief Copies fields of __rhs into this. 367 * @param __rhs The source values for the copies. 368 * @return Reference to this object. 369 * 370 * All fields of __rhs are copied into this object except that rdbuf() 371 * and rdstate() remain unchanged. All values in the pword and iword 372 * arrays are copied. Before copying, each callback is invoked with 373 * erase_event. After copying, each (new) callback is invoked with 374 * copyfmt_event. The final step is to copy exceptions(). 375 */ 376 basic_ios& 377 copyfmt(const basic_ios& __rhs); 378 379 /** 380 * @brief Retrieves the @a empty character. 381 * @return The current fill character. 382 * 383 * It defaults to a space (' ') in the current locale. 384 */ 385 _GLIBCXX_NODISCARD 386 char_type 387 fill() const 388 { 389 if (__builtin_expect(!_M_fill_init, false)) 390 return this->widen(' '); 391 return _M_fill; 392 } 393 394 /** 395 * @brief Sets a new @a empty character. 396 * @param __ch The new character. 397 * @return The previous fill character. 398 * 399 * The fill character is used to fill out space when P+ characters 400 * have been requested (e.g., via setw), Q characters are actually 401 * used, and Q<P. It defaults to a space (' ') in the current locale. 402 */ 403 char_type 404 fill(char_type __ch) 405 { 406 char_type __old = _M_fill; 407 _M_fill = __ch; 408 _M_fill_init = true; 409 return __old; 410 } 411 412 // Locales: 413 /** 414 * @brief Moves to a new locale. 415 * @param __loc The new locale. 416 * @return The previous locale. 417 * 418 * Calls @c ios_base::imbue(loc), and if a stream buffer is associated 419 * with this stream, calls that buffer's @c pubimbue(loc). 420 * 421 * Additional l10n notes are at 422 * https://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html 423 */ 424 locale 425 imbue(const locale& __loc); 426 427 /** 428 * @brief Squeezes characters. 429 * @param __c The character to narrow. 430 * @param __dfault The character to narrow. 431 * @return The narrowed character. 432 * 433 * Maps a character of @c char_type to a character of @c char, 434 * if possible. 435 * 436 * Returns the result of 437 * @code 438 * std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault) 439 * @endcode 440 * 441 * Additional l10n notes are at 442 * https://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html 443 */ 444 char 445 narrow(char_type __c, char __dfault) const 446 { return __check_facet(_M_ctype).narrow(__c, __dfault); } 447 448 /** 449 * @brief Widens characters. 450 * @param __c The character to widen. 451 * @return The widened character. 452 * 453 * Maps a character of @c char to a character of @c char_type. 454 * 455 * Returns the result of 456 * @code 457 * std::use_facet<ctype<char_type> >(getloc()).widen(c) 458 * @endcode 459 * 460 * Additional l10n notes are at 461 * https://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html 462 */ 463 char_type 464 widen(char __c) const 465 { return __check_facet(_M_ctype).widen(__c); } 466 467 protected: 468 // 27.4.5.1 basic_ios constructors 469 /** 470 * @brief Empty. 471 * 472 * The default constructor does nothing and is not normally 473 * accessible to users. 474 */ 475 basic_ios() 476 : ios_base(), _M_tie(0), _M_fill(char_type()), _M_fill_init(false), 477 _M_streambuf(0), _M_ctype(0), _M_num_put(0), _M_num_get(0) 478 { } 479 480 /** 481 * @brief All setup is performed here. 482 * 483 * This is called from the public constructor. It is not virtual and 484 * cannot be redefined. 485 */ 486 void 487 init(basic_streambuf<_CharT, _Traits>* __sb); 488 489 #if __cplusplus >= 201103L 490 basic_ios(const basic_ios&) = delete; 491 basic_ios& operator=(const basic_ios&) = delete; 492 493 void 494 move(basic_ios& __rhs) 495 { 496 ios_base::_M_move(__rhs); 497 _M_cache_locale(_M_ios_locale); 498 this->tie(__rhs.tie(nullptr)); 499 _M_fill = __rhs._M_fill; 500 _M_fill_init = __rhs._M_fill_init; 501 _M_streambuf = nullptr; 502 } 503 504 void 505 move(basic_ios&& __rhs) 506 { this->move(__rhs); } 507 508 void 509 swap(basic_ios& __rhs) noexcept 510 { 511 ios_base::_M_swap(__rhs); 512 _M_cache_locale(_M_ios_locale); 513 __rhs._M_cache_locale(__rhs._M_ios_locale); 514 std::swap(_M_tie, __rhs._M_tie); 515 std::swap(_M_fill, __rhs._M_fill); 516 std::swap(_M_fill_init, __rhs._M_fill_init); 517 } 518 519 void 520 set_rdbuf(basic_streambuf<_CharT, _Traits>* __sb) 521 { _M_streambuf = __sb; } 522 #endif 523 524 void 525 _M_cache_locale(const locale& __loc); 526 }; 527 528 _GLIBCXX_END_NAMESPACE_VERSION 529 } // namespace 530 531 #include <bits/basic_ios.tcc> 532 533 #endif /* _BASIC_IOS_H */
