# 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
    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 2, 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 // You should have received a copy of the GNU General Public License along
    00019 // with this library; see the file COPYING.  If not, write to the Free
    00020 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
    00021 // USA.
    00022
    00023 // As a special exception, you may use this file as part of a free software
    00024 // library without restriction.  Specifically, if other files instantiate
    00025 // templates or use macros or inline functions from this file, or you compile
    00026 // this file and link it with other files to produce an executable, this
    00027 // file does not by itself cause the resulting executable to be covered by
    00028 // the GNU General Public License.  This exception does not however
    00029 // invalidate any other reasons why the executable file might be covered by
    00030 // the GNU General Public License.
    00031
    00032 /** @file basic_ios.h
    00033  *  This is an internal header file, included by other library headers.
    00034  *  You should not attempt to use it directly.
    00035  */
    00036
    00037 #ifndef _BASIC_IOS_H
    00038 #define _BASIC_IOS_H 1
    00039
    00040 #pragma GCC system_header
    00041
    00042 #include <bits/localefwd.h>
    00043 #include <bits/locale_classes.h>
    00044 #include <bits/locale_facets.h>
    00045 #include <bits/streambuf_iterator.h>
    00046
    00047 _GLIBCXX_BEGIN_NAMESPACE(std)
    00048
    00049   template<typename _Facet>
    00050     inline const _Facet&
    00051     __check_facet(const _Facet* __f)
    00052     {
    00053       if (!__f)
    00054     __throw_bad_cast();
    00055       return *__f;
    00056     }
    00057
    00058   // 27.4.5  Template class basic_ios
    00059   /**
    00060    *  @brief  Virtual base class for all stream classes.
    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 dependant 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        *  "if (!a_stream) ..." and "while (a_stream) ..."
    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 "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 "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++/22_locale/howto.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++/22_locale/howto.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++/22_locale/howto.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
    00473
    00474 #ifndef _GLIBCXX_EXPORT_TEMPLATE
    00475 #include <bits/basic_ios.tcc>
    00476 #endif
    00477
    00478 #endif /* _BASIC_IOS_H */