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