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 46namespace 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 // Flip the internal state on for the proper state bits, then re 149 // throws the propagated exception if bit also set in 150 // exceptions(). 151 void 152 _M_setstate(iostate __state) 153 { 154 // 27.6.1.2.1 Common requirements. 155 // Turn this on without causing an ios::failure to be thrown. 156 _M_streambuf_state |= __state; 157 if (this->exceptions() & __state) 158 __throw_exception_again; 159 } 160 161 /** 162 * @brief Fast error checking. 163 * @return True if no error flags are set. 164 * 165 * A wrapper around rdstate. 166 */ 167 bool 168 good() const 169 { return this->rdstate() == 0; } 170 171 /** 172 * @brief Fast error checking. 173 * @return True if the eofbit is set. 174 * 175 * Note that other iostate flags may also be set. 176 */ 177 bool 178 eof() const 179 { return (this->rdstate() & eofbit) != 0; } 180 181 /** 182 * @brief Fast error checking. 183 * @return True if either the badbit or the failbit is set. 184 * 185 * Checking the badbit in fail() is historical practice. 186 * Note that other iostate flags may also be set. 187 */ 188 bool 189 fail() const 190 { return (this->rdstate() & (badbit | failbit)) != 0; } 191 192 /** 193 * @brief Fast error checking. 194 * @return True if the badbit is set. 195 * 196 * Note that other iostate flags may also be set. 197 */ 198 bool 199 bad() const 200 { return (this->rdstate() & badbit) != 0; } 201 202 /** 203 * @brief Throwing exceptions on errors. 204 * @return The current exceptions mask. 205 * 206 * This changes nothing in the stream. See the one-argument version 207 * of exceptions(iostate) for the meaning of the return value. 208 */ 209 iostate 210 exceptions() const 211 { return _M_exception; } 212 213 /** 214 * @brief Throwing exceptions on errors. 215 * @param except The new exceptions mask. 216 * 217 * By default, error flags are set silently. You can set an 218 * exceptions mask for each stream; if a bit in the mask becomes set 219 * in the error flags, then an exception of type 220 * std::ios_base::failure is thrown. 221 * 222 * If the error flage is already set when the exceptions mask is 223 * added, the exception is immediately thrown. Try running the 224 * following under GCC 3.1 or later: 225 * @code 226 * #include <iostream> 227 * #include <fstream> 228 * #include <exception> 229 * 230 * int main() 231 * { 232 * std::set_terminate (__gnu_cxx::__verbose_terminate_handler); 233 * 234 * std::ifstream f ("/etc/motd"); 235 * 236 * std::cerr << "Setting badbit\n"; 237 * f.setstate (std::ios_base::badbit); 238 * 239 * std::cerr << "Setting exception mask\n"; 240 * f.exceptions (std::ios_base::badbit); 241 * } 242 * @endcode 243 */ 244 void 245 exceptions(iostate __except) 246 { 247 _M_exception = __except; 248 this->clear(_M_streambuf_state); 249 } 250 251 // Constructor/destructor: 252 /** 253 * @brief Constructor performs initialization. 254 * 255 * The parameter is passed by derived streams. 256 */ 257 explicit 258 basic_ios(basic_streambuf<_CharT, _Traits>* __sb) 259 : ios_base(), _M_fctype(0), _M_fnumput(0), _M_fnumget(0) 260 { this->init(__sb); } 261 262 /** 263 * @brief Empty. 264 * 265 * The destructor does nothing. More specifically, it does not 266 * destroy the streambuf held by rdbuf(). 267 */ 268 virtual 269 ~basic_ios() { } 270 271 // Members: 272 /** 273 * @brief Fetches the current @e tied stream. 274 * @return A pointer to the tied stream, or NULL if the stream is 275 * not tied. 276 * 277 * A stream may be @e tied (or synchronized) to a second output 278 * stream. When this stream performs any I/O, the tied stream is 279 * first flushed. For example, @c std::cin is tied to @c std::cout. 280 */ 281 basic_ostream<_CharT, _Traits>* 282 tie() const 283 { return _M_tie; } 284 285 /** 286 * @brief Ties this stream to an output stream. 287 * @param tiestr The output stream. 288 * @return The previously tied output stream, or NULL if the stream 289 * was not tied. 290 * 291 * This sets up a new tie; see tie() for more. 292 */ 293 basic_ostream<_CharT, _Traits>* 294 tie(basic_ostream<_CharT, _Traits>* __tiestr) 295 { 296 basic_ostream<_CharT, _Traits>* __old = _M_tie; 297 _M_tie = __tiestr; 298 return __old; 299 } 300 301 /** 302 * @brief Accessing the underlying buffer. 303 * @return The current stream buffer. 304 * 305 * This does not change the state of the stream. 306 */ 307 basic_streambuf<_CharT, _Traits>* 308 rdbuf() const 309 { return _M_streambuf; } 310 311 /** 312 * @brief Changing the underlying buffer. 313 * @param sb The new stream buffer. 314 * @return The previous stream buffer. 315 * 316 * Associates a new buffer with the current stream, and clears the 317 * error state. 318 * 319 * Due to historical accidents which the LWG refuses to correct, the 320 * I/O library suffers from a design error: this function is hidden 321 * in derived classes by overrides of the zero-argument @c rdbuf(), 322 * which is non-virtual for hysterical raisins. As a result, you 323 * must use explicit qualifications to access this function via any 324 * derived class. 325 */ 326 basic_streambuf<_CharT, _Traits>* 327 rdbuf(basic_streambuf<_CharT, _Traits>* __sb); 328 329 /** 330 * @doctodo 331 */ 332 basic_ios& 333 copyfmt(const basic_ios& __rhs); 334 335 /** 336 * @brief Retreives the "empty" character. 337 * @return The current fill character. 338 * 339 * It defaults to a space (' ') in the current locale. 340 */ 341 char_type 342 fill() const 343 { 344 if (!_M_fill_init) 345 { 346 _M_fill = this->widen(' '); 347 _M_fill_init = true; 348 } 349 return _M_fill; 350 } 351 352 /** 353 * @brief Sets a new "empty" character. 354 * @param ch The new character. 355 * @return The previous fill character. 356 * 357 * The fill character is used to fill out space when P+ characters 358 * have been requested (e.g., via setw), Q characters are actually 359 * used, and Q<P. It defaults to a space (' ') in the current locale. 360 */ 361 char_type 362 fill(char_type __ch) 363 { 364 char_type __old = this->fill(); 365 _M_fill = __ch; 366 return __old; 367 } 368 369 // Locales: 370 /** 371 * @brief Moves to a new locale. 372 * @param loc The new locale. 373 * @return The previous locale. 374 * 375 * Calls @c ios_base::imbue(loc), and if a stream buffer is associated 376 * with this stream, calls that buffer's @c pubimbue(loc). 377 * 378 * Additional l10n notes are at 379 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 380 */ 381 locale 382 imbue(const locale& __loc); 383 384 /** 385 * @brief Squeezes characters. 386 * @param c The character to narrow. 387 * @param dfault The character to narrow. 388 * @return The narrowed character. 389 * 390 * Maps a character of @c char_type to a character of @c char, 391 * if possible. 392 * 393 * Returns the result of 394 * @code 395 * std::use_facet< ctype<char_type> >(getloc()).narrow(c,dfault) 396 * @endcode 397 * 398 * Additional l10n notes are at 399 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 400 */ 401 char 402 narrow(char_type __c, char __dfault) const; 403 404 /** 405 * @brief Widens characters. 406 * @param c The character to widen. 407 * @return The widened character. 408 * 409 * Maps a character of @c char to a character of @c char_type. 410 * 411 * Returns the result of 412 * @code 413 * std::use_facet< ctype<char_type> >(getloc()).widen(c) 414 * @endcode 415 * 416 * Additional l10n notes are at 417 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 418 */ 419 char_type 420 widen(char __c) const; 421 422 protected: 423 // 27.4.5.1 basic_ios constructors 424 /** 425 * @brief Empty. 426 * 427 * The default constructor does nothing and is not normally 428 * accessible to users. 429 */ 430 basic_ios() : ios_base() 431 { } 432 433 /** 434 * @brief All setup is performed here. 435 * 436 * This is called from the public constructor. It is not virtual and 437 * cannot be redefined. The second argument, __cache, is used 438 * to initialize the standard streams without allocating 439 * memory. 440 */ 441 void 442 init(basic_streambuf<_CharT, _Traits>* __sb); 443 444 bool 445 _M_check_facet(const locale::facet* __f) const 446 { 447 if (!__f) 448 __throw_bad_cast(); 449 return true; 450 } 451 452 void 453 _M_cache_locale(const locale& __loc); 454 455#if 1 456 // XXX GLIBCXX_ABI Deprecated, compatibility only. 457 void 458 _M_cache_facets(const locale& __loc); 459#endif 460 }; 461} // namespace std 462 463#ifdef _GLIBCPP_NO_TEMPLATE_EXPORT 464# define export 465#include <bits/basic_ios.tcc> 466#endif 467 468#endif /* _CPP_BITS_BASICIOS_H */ 469