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

Generated on Thu Jul 23 21:15:57 2009 for libstdc++ by  doxygen 1.5.8