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