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