libstdc++
basic_ios.h
Go to the documentation of this file.
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 */