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