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