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 */

Generated on Wed Apr 27 18:35:09 2005 for libstdc++ source by  doxygen 1.4.2