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