basic_ios.h revision 117397
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 /** 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) : ios_base() 246 { this->init(__sb); } 247 248 /** 249 * @brief Empty. 250 * 251 * The destructor does nothing. More specifically, it does not 252 * destroy the streambuf held by rdbuf(). 253 */ 254 virtual 255 ~basic_ios() { } 256 257 // Members: 258 /** 259 * @brief Fetches the current @e tied stream. 260 * @return A pointer to the tied stream, or NULL if the stream is 261 * not tied. 262 * 263 * A stream may be @e tied (or synchronized) to a second output 264 * stream. When this stream performs any I/O, the tied stream is 265 * first flushed. For example, @c std::cin is tied to @c std::cout. 266 */ 267 basic_ostream<_CharT, _Traits>* 268 tie() const 269 { return _M_tie; } 270 271 /** 272 * @brief Ties this stream to an output stream. 273 * @param tiestr The output stream. 274 * @return The previously tied output stream, or NULL if the stream 275 * was not tied. 276 * 277 * This sets up a new tie; see tie() for more. 278 */ 279 basic_ostream<_CharT, _Traits>* 280 tie(basic_ostream<_CharT, _Traits>* __tiestr) 281 { 282 basic_ostream<_CharT, _Traits>* __old = _M_tie; 283 _M_tie = __tiestr; 284 return __old; 285 } 286 287 /** 288 * @brief Accessing the underlying buffer. 289 * @return The current stream buffer. 290 * 291 * This does not change the state of the stream. 292 */ 293 basic_streambuf<_CharT, _Traits>* 294 rdbuf() const 295 { return _M_streambuf; } 296 297 /** 298 * @brief Changing the underlying buffer. 299 * @param sb The new stream buffer. 300 * @return The previous stream buffer. 301 * 302 * Associates a new buffer with the current stream, and clears the 303 * error state. 304 * 305 * Due to historical accidents which the LWG refuses to correct, the 306 * I/O library suffers from a design error: this function is hidden 307 * in derived classes by overrides of the zero-argument @c rdbuf(), 308 * which is non-virtual for hysterical raisins. As a result, you 309 * must use explicit qualifications to access this function via any 310 * derived class. 311 */ 312 basic_streambuf<_CharT, _Traits>* 313 rdbuf(basic_streambuf<_CharT, _Traits>* __sb); 314 315 /** 316 * @doctodo 317 */ 318 basic_ios& 319 copyfmt(const basic_ios& __rhs); 320 321 /** 322 * @brief Retreives the "empty" character. 323 * @return The current fill character. 324 * 325 * It defaults to a space (' ') in the current locale. 326 */ 327 char_type 328 fill() const 329 { 330 if (!_M_fill_init) 331 { 332 _M_fill = this->widen(' '); 333 _M_fill_init = true; 334 } 335 return _M_fill; 336 } 337 338 /** 339 * @brief Sets a new "empty" character. 340 * @param ch The new character. 341 * @return The previous fill character. 342 * 343 * The fill character is used to fill out space when P+ characters 344 * have been requested (e.g., via setw), Q characters are actually 345 * used, and Q<P. It defaults to a space (' ') in the current locale. 346 */ 347 char_type 348 fill(char_type __ch) 349 { 350 char_type __old = this->fill(); 351 _M_fill = __ch; 352 return __old; 353 } 354 355 // Locales: 356 /** 357 * @brief Moves to a new locale. 358 * @param loc The new locale. 359 * @return The previous locale. 360 * 361 * Calls @c ios_base::imbue(loc), and if a stream buffer is associated 362 * with this stream, calls that buffer's @c pubimbue(loc). 363 * 364 * Additional l10n notes are at 365 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 366 */ 367 locale 368 imbue(const locale& __loc); 369 370 /** 371 * @brief Squeezes characters. 372 * @param c The character to narrow. 373 * @param dfault The character to narrow. 374 * @return The narrowed character. 375 * 376 * Maps a character of @c char_type to a character of @c char, 377 * if possible. 378 * 379 * Returns the result of 380 * @code 381 * std::use_facet< ctype<char_type> >(getloc()).narrow(c,dfault) 382 * @endcode 383 * 384 * Additional l10n notes are at 385 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 386 */ 387 char 388 narrow(char_type __c, char __dfault) const; 389 390 /** 391 * @brief Widens characters. 392 * @param c The character to widen. 393 * @return The widened character. 394 * 395 * Maps a character of @c char to a character of @c char_type. 396 * 397 * Returns the result of 398 * @code 399 * std::use_facet< ctype<char_type> >(getloc()).widen(c) 400 * @endcode 401 * 402 * Additional l10n notes are at 403 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 404 */ 405 char_type 406 widen(char __c) const; 407 408 protected: 409 // 27.4.5.1 basic_ios constructors 410 /** 411 * @brief Empty. 412 * 413 * The default constructor does nothing and is not normally 414 * accessible to users. 415 */ 416 basic_ios() : ios_base() 417 { } 418 419 /** 420 * @brief All setup is performed here. 421 * 422 * This is called from the public constructor. It is not virtual and 423 * cannot be redefined. The second argument, __cache, is used 424 * to initialize the standard streams without allocating 425 * memory. 426 */ 427 void 428 init(basic_streambuf<_CharT, _Traits>* __sb); 429 430 bool 431 _M_check_facet(const locale::facet* __f) const 432 { 433 if (!__f) 434 __throw_bad_cast(); 435 return true; 436 } 437 438 void 439 _M_cache_locale(const locale& __loc); 440 441#if 1 442 // XXX GLIBCXX_ABI Deprecated, compatibility only. 443 void 444 _M_cache_facets(const locale& __loc); 445#endif 446 447 // Internal state setter that won't throw, only set the state bits. 448 // Used to guarantee we don't throw when setting badbit. 449 void 450 _M_setstate(iostate __state) { _M_streambuf_state |= __state; } 451 }; 452} // namespace std 453 454#ifdef _GLIBCPP_NO_TEMPLATE_EXPORT 455# define export 456#include <bits/basic_ios.tcc> 457#endif 458 459#endif /* _CPP_BITS_BASICIOS_H */ 460