00001 // Iostreams base classes -*- C++ -*- 00002 00003 // Copyright (C) 1997, 1998, 1999, 2001, 2002, 2003 00004 // Free Software Foundation, Inc. 00005 // 00006 // This file is part of the GNU ISO C++ Library. This library is free 00007 // software; you can redistribute it and/or modify it under the 00008 // terms of the GNU General Public License as published by the 00009 // Free Software Foundation; either version 2, or (at your option) 00010 // any later version. 00011 00012 // This library is distributed in the hope that it will be useful, 00013 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00014 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00015 // GNU General Public License for more details. 00016 00017 // You should have received a copy of the GNU General Public License along 00018 // with this library; see the file COPYING. If not, write to the Free 00019 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, 00020 // USA. 00021 00022 // As a special exception, you may use this file as part of a free software 00023 // library without restriction. Specifically, if other files instantiate 00024 // templates or use macros or inline functions from this file, or you compile 00025 // this file and link it with other files to produce an executable, this 00026 // file does not by itself cause the resulting executable to be covered by 00027 // the GNU General Public License. This exception does not however 00028 // invalidate any other reasons why the executable file might be covered by 00029 // the GNU General Public License. 00030 00031 /** @file basic_ios.h 00032 * This is an internal header file, included by other library headers. 00033 * You should not attempt to use it directly. 00034 */ 00035 00036 #ifndef _CPP_BITS_BASICIOS_H 00037 #define _CPP_BITS_BASICIOS_H 1 00038 00039 #pragma GCC system_header 00040 00041 #include <bits/streambuf_iterator.h> 00042 #include <bits/localefwd.h> 00043 #include <bits/locale_classes.h> 00044 #include <bits/locale_facets.h> 00045 00046 namespace std 00047 { 00048 // 27.4.5 Template class basic_ios 00049 /** 00050 * @brief Virtual base class for all stream classes. 00051 * 00052 * Most of the member functions called dispatched on stream objects 00053 * (e.g., @c std::cout.foo(bar);) are consolidated in this class. 00054 */ 00055 template<typename _CharT, typename _Traits> 00056 class basic_ios : public ios_base 00057 { 00058 public: 00059 //@{ 00060 /** 00061 * These are standard types. They permit a standardized way of 00062 * referring to names of (or names dependant on) the template 00063 * parameters, which are specific to the implementation. 00064 */ 00065 typedef _CharT char_type; 00066 typedef typename _Traits::int_type int_type; 00067 typedef typename _Traits::pos_type pos_type; 00068 typedef typename _Traits::off_type off_type; 00069 typedef _Traits traits_type; 00070 //@} 00071 00072 //@{ 00073 /** 00074 * @if maint 00075 * These are non-standard types. 00076 * @endif 00077 */ 00078 typedef ctype<_CharT> __ctype_type; 00079 typedef ostreambuf_iterator<_CharT, _Traits> __ostreambuf_iter; 00080 typedef num_put<_CharT, __ostreambuf_iter> __numput_type; 00081 typedef istreambuf_iterator<_CharT, _Traits> __istreambuf_iter; 00082 typedef num_get<_CharT, __istreambuf_iter> __numget_type; 00083 //@} 00084 00085 friend void ios_base::Init::_S_ios_create(bool); 00086 00087 // Data members: 00088 protected: 00089 basic_ostream<_CharT, _Traits>* _M_tie; 00090 mutable char_type _M_fill; 00091 mutable bool _M_fill_init; 00092 basic_streambuf<_CharT, _Traits>* _M_streambuf; 00093 00094 // Cached use_facet<ctype>, which is based on the current locale info. 00095 const __ctype_type* _M_fctype; 00096 // From ostream. 00097 const __numput_type* _M_fnumput; 00098 // From istream. 00099 const __numget_type* _M_fnumget; 00100 00101 public: 00102 //@{ 00103 /** 00104 * @brief The quick-and-easy status check. 00105 * 00106 * This allows you to write constructs such as 00107 * "if (!a_stream) ..." and "while (a_stream) ..." 00108 */ 00109 operator void*() const 00110 { return this->fail() ? 0 : const_cast<basic_ios*>(this); } 00111 00112 bool 00113 operator!() const 00114 { return this->fail(); } 00115 //@} 00116 00117 /** 00118 * @brief Returns the error state of the stream buffer. 00119 * @return A bit pattern (well, isn't everything?) 00120 * 00121 * See std::ios_base::iostate for the possible bit values. Most 00122 * users will call one of the interpreting wrappers, e.g., good(). 00123 */ 00124 iostate 00125 rdstate() const 00126 { return _M_streambuf_state; } 00127 00128 /** 00129 * @brief [Re]sets the error state. 00130 * @param state The new state flag(s) to set. 00131 * 00132 * See std::ios_base::iostate for the possible bit values. Most 00133 * users will not need to pass an argument. 00134 */ 00135 void 00136 clear(iostate __state = goodbit); 00137 00138 /** 00139 * @brief Sets additional flags in the error state. 00140 * @param state The additional state flag(s) to set. 00141 * 00142 * See std::ios_base::iostate for the possible bit values. 00143 */ 00144 void 00145 setstate(iostate __state) 00146 { this->clear(this->rdstate() | __state); } 00147 00148 // Flip the internal state on for the proper state bits, then re 00149 // throws the propagated exception if bit also set in 00150 // exceptions(). 00151 void 00152 _M_setstate(iostate __state) 00153 { 00154 // 27.6.1.2.1 Common requirements. 00155 // Turn this on without causing an ios::failure to be thrown. 00156 _M_streambuf_state |= __state; 00157 if (this->exceptions() & __state) 00158 __throw_exception_again; 00159 } 00160 00161 /** 00162 * @brief Fast error checking. 00163 * @return True if no error flags are set. 00164 * 00165 * A wrapper around rdstate. 00166 */ 00167 bool 00168 good() const 00169 { return this->rdstate() == 0; } 00170 00171 /** 00172 * @brief Fast error checking. 00173 * @return True if the eofbit is set. 00174 * 00175 * Note that other iostate flags may also be set. 00176 */ 00177 bool 00178 eof() const 00179 { return (this->rdstate() & eofbit) != 0; } 00180 00181 /** 00182 * @brief Fast error checking. 00183 * @return True if either the badbit or the failbit is set. 00184 * 00185 * Checking the badbit in fail() is historical practice. 00186 * Note that other iostate flags may also be set. 00187 */ 00188 bool 00189 fail() const 00190 { return (this->rdstate() & (badbit | failbit)) != 0; } 00191 00192 /** 00193 * @brief Fast error checking. 00194 * @return True if the badbit is set. 00195 * 00196 * Note that other iostate flags may also be set. 00197 */ 00198 bool 00199 bad() const 00200 { return (this->rdstate() & badbit) != 0; } 00201 00202 /** 00203 * @brief Throwing exceptions on errors. 00204 * @return The current exceptions mask. 00205 * 00206 * This changes nothing in the stream. See the one-argument version 00207 * of exceptions(iostate) for the meaning of the return value. 00208 */ 00209 iostate 00210 exceptions() const 00211 { return _M_exception; } 00212 00213 /** 00214 * @brief Throwing exceptions on errors. 00215 * @param except The new exceptions mask. 00216 * 00217 * By default, error flags are set silently. You can set an 00218 * exceptions mask for each stream; if a bit in the mask becomes set 00219 * in the error flags, then an exception of type 00220 * std::ios_base::failure is thrown. 00221 * 00222 * If the error flage is already set when the exceptions mask is 00223 * added, the exception is immediately thrown. Try running the 00224 * following under GCC 3.1 or later: 00225 * @code 00226 * #include <iostream> 00227 * #include <fstream> 00228 * #include <exception> 00229 * 00230 * int main() 00231 * { 00232 * std::set_terminate (__gnu_cxx::__verbose_terminate_handler); 00233 * 00234 * std::ifstream f ("/etc/motd"); 00235 * 00236 * std::cerr << "Setting badbit\n"; 00237 * f.setstate (std::ios_base::badbit); 00238 * 00239 * std::cerr << "Setting exception mask\n"; 00240 * f.exceptions (std::ios_base::badbit); 00241 * } 00242 * @endcode 00243 */ 00244 void 00245 exceptions(iostate __except) 00246 { 00247 _M_exception = __except; 00248 this->clear(_M_streambuf_state); 00249 } 00250 00251 // Constructor/destructor: 00252 /** 00253 * @brief Constructor performs initialization. 00254 * 00255 * The parameter is passed by derived streams. 00256 */ 00257 explicit 00258 basic_ios(basic_streambuf<_CharT, _Traits>* __sb) 00259 : ios_base(), _M_fctype(0), _M_fnumput(0), _M_fnumget(0) 00260 { this->init(__sb); } 00261 00262 /** 00263 * @brief Empty. 00264 * 00265 * The destructor does nothing. More specifically, it does not 00266 * destroy the streambuf held by rdbuf(). 00267 */ 00268 virtual 00269 ~basic_ios() { } 00270 00271 // Members: 00272 /** 00273 * @brief Fetches the current @e tied stream. 00274 * @return A pointer to the tied stream, or NULL if the stream is 00275 * not tied. 00276 * 00277 * A stream may be @e tied (or synchronized) to a second output 00278 * stream. When this stream performs any I/O, the tied stream is 00279 * first flushed. For example, @c std::cin is tied to @c std::cout. 00280 */ 00281 basic_ostream<_CharT, _Traits>* 00282 tie() const 00283 { return _M_tie; } 00284 00285 /** 00286 * @brief Ties this stream to an output stream. 00287 * @param tiestr The output stream. 00288 * @return The previously tied output stream, or NULL if the stream 00289 * was not tied. 00290 * 00291 * This sets up a new tie; see tie() for more. 00292 */ 00293 basic_ostream<_CharT, _Traits>* 00294 tie(basic_ostream<_CharT, _Traits>* __tiestr) 00295 { 00296 basic_ostream<_CharT, _Traits>* __old = _M_tie; 00297 _M_tie = __tiestr; 00298 return __old; 00299 } 00300 00301 /** 00302 * @brief Accessing the underlying buffer. 00303 * @return The current stream buffer. 00304 * 00305 * This does not change the state of the stream. 00306 */ 00307 basic_streambuf<_CharT, _Traits>* 00308 rdbuf() const 00309 { return _M_streambuf; } 00310 00311 /** 00312 * @brief Changing the underlying buffer. 00313 * @param sb The new stream buffer. 00314 * @return The previous stream buffer. 00315 * 00316 * Associates a new buffer with the current stream, and clears the 00317 * error state. 00318 * 00319 * Due to historical accidents which the LWG refuses to correct, the 00320 * I/O library suffers from a design error: this function is hidden 00321 * in derived classes by overrides of the zero-argument @c rdbuf(), 00322 * which is non-virtual for hysterical raisins. As a result, you 00323 * must use explicit qualifications to access this function via any 00324 * derived class. 00325 */ 00326 basic_streambuf<_CharT, _Traits>* 00327 rdbuf(basic_streambuf<_CharT, _Traits>* __sb); 00328 00329 /** 00330 * @doctodo 00331 */ 00332 basic_ios& 00333 copyfmt(const basic_ios& __rhs); 00334 00335 /** 00336 * @brief Retreives the "empty" character. 00337 * @return The current fill character. 00338 * 00339 * It defaults to a space (' ') in the current locale. 00340 */ 00341 char_type 00342 fill() const 00343 { 00344 if (!_M_fill_init) 00345 { 00346 _M_fill = this->widen(' '); 00347 _M_fill_init = true; 00348 } 00349 return _M_fill; 00350 } 00351 00352 /** 00353 * @brief Sets a new "empty" character. 00354 * @param ch The new character. 00355 * @return The previous fill character. 00356 * 00357 * The fill character is used to fill out space when P+ characters 00358 * have been requested (e.g., via setw), Q characters are actually 00359 * used, and Q<P. It defaults to a space (' ') in the current locale. 00360 */ 00361 char_type 00362 fill(char_type __ch) 00363 { 00364 char_type __old = this->fill(); 00365 _M_fill = __ch; 00366 return __old; 00367 } 00368 00369 // Locales: 00370 /** 00371 * @brief Moves to a new locale. 00372 * @param loc The new locale. 00373 * @return The previous locale. 00374 * 00375 * Calls @c ios_base::imbue(loc), and if a stream buffer is associated 00376 * with this stream, calls that buffer's @c pubimbue(loc). 00377 * 00378 * Additional l10n notes are at 00379 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 00380 */ 00381 locale 00382 imbue(const locale& __loc); 00383 00384 /** 00385 * @brief Squeezes characters. 00386 * @param c The character to narrow. 00387 * @param dfault The character to narrow. 00388 * @return The narrowed character. 00389 * 00390 * Maps a character of @c char_type to a character of @c char, 00391 * if possible. 00392 * 00393 * Returns the result of 00394 * @code 00395 * std::use_facet< ctype<char_type> >(getloc()).narrow(c,dfault) 00396 * @endcode 00397 * 00398 * Additional l10n notes are at 00399 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 00400 */ 00401 char 00402 narrow(char_type __c, char __dfault) const; 00403 00404 /** 00405 * @brief Widens characters. 00406 * @param c The character to widen. 00407 * @return The widened character. 00408 * 00409 * Maps a character of @c char to a character of @c char_type. 00410 * 00411 * Returns the result of 00412 * @code 00413 * std::use_facet< ctype<char_type> >(getloc()).widen(c) 00414 * @endcode 00415 * 00416 * Additional l10n notes are at 00417 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 00418 */ 00419 char_type 00420 widen(char __c) const; 00421 00422 protected: 00423 // 27.4.5.1 basic_ios constructors 00424 /** 00425 * @brief Empty. 00426 * 00427 * The default constructor does nothing and is not normally 00428 * accessible to users. 00429 */ 00430 basic_ios() : ios_base() 00431 { } 00432 00433 /** 00434 * @brief All setup is performed here. 00435 * 00436 * This is called from the public constructor. It is not virtual and 00437 * cannot be redefined. The second argument, __cache, is used 00438 * to initialize the standard streams without allocating 00439 * memory. 00440 */ 00441 void 00442 init(basic_streambuf<_CharT, _Traits>* __sb); 00443 00444 bool 00445 _M_check_facet(const locale::facet* __f) const 00446 { 00447 if (!__f) 00448 __throw_bad_cast(); 00449 return true; 00450 } 00451 00452 void 00453 _M_cache_locale(const locale& __loc); 00454 00455 #if 1 00456 // XXX GLIBCXX_ABI Deprecated, compatibility only. 00457 void 00458 _M_cache_facets(const locale& __loc); 00459 #endif 00460 }; 00461 } // namespace std 00462 00463 #ifdef _GLIBCPP_NO_TEMPLATE_EXPORT 00464 # define export 00465 #include <bits/basic_ios.tcc> 00466 #endif 00467 00468 #endif /* _CPP_BITS_BASICIOS_H */