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