# basic_ios.h

Go to the documentation of this file.

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