home *** CD-ROM | disk | FTP | other *** search
/ Beginning C++ Through Gam…rogramming (2nd Edition) / BCGP2E.ISO / bloodshed / devcpp-4.9.9.2_setup.exe / basic_ios.h < prev    next >
C/C++ Source or Header  |  2005-01-29  |  15KB  |  468 lines
  1. // Iostreams base classes -*- C++ -*-
  2.  
  3. // Copyright (C) 1997, 1998, 1999, 2001, 2002, 2003, 2004
  4. // Free Software Foundation, Inc.
  5. //
  6. // This file is part of the GNU ISO C++ Library.  This library is free
  7. // software; you can redistribute it and/or modify it under the
  8. // terms of the GNU General Public License as published by the
  9. // Free Software Foundation; either version 2, or (at your option)
  10. // any later version.
  11.  
  12. // This library is distributed in the hope that it will be useful,
  13. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15. // GNU General Public License for more details.
  16.  
  17. // You should have received a copy of the GNU General Public License along
  18. // with this library; see the file COPYING.  If not, write to the Free
  19. // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  20. // USA.
  21.  
  22. // As a special exception, you may use this file as part of a free software
  23. // library without restriction.  Specifically, if other files instantiate
  24. // templates or use macros or inline functions from this file, or you compile
  25. // this file and link it with other files to produce an executable, this
  26. // file does not by itself cause the resulting executable to be covered by
  27. // the GNU General Public License.  This exception does not however
  28. // invalidate any other reasons why the executable file might be covered by
  29. // the GNU General Public License.
  30.  
  31. /** @file basic_ios.h
  32.  *  This is an internal header file, included by other library headers.
  33.  *  You should not attempt to use it directly.
  34.  */
  35.  
  36. #ifndef _BASIC_IOS_H
  37. #define _BASIC_IOS_H 1
  38.  
  39. #pragma GCC system_header
  40.  
  41. #include <bits/streambuf_iterator.h>
  42. #include <bits/localefwd.h>
  43. #include <bits/locale_classes.h>
  44. #include <bits/locale_facets.h>
  45.  
  46. namespace std
  47. {
  48.   // 27.4.5  Template class basic_ios
  49.   /**
  50.    *  @brief  Virtual base class for all stream classes.
  51.    *
  52.    *  Most of the member functions called dispatched on stream objects
  53.    *  (e.g., @c std::cout.foo(bar);) are consolidated in this class.
  54.   */
  55.   template<typename _CharT, typename _Traits>
  56.     class basic_ios : public ios_base
  57.     {
  58.     public:
  59.       //@{
  60.       /**
  61.        *  These are standard types.  They permit a standardized way of
  62.        *  referring to names of (or names dependant on) the template
  63.        *  parameters, which are specific to the implementation.
  64.       */
  65.       typedef _CharT                                 char_type;
  66.       typedef typename _Traits::int_type             int_type;
  67.       typedef typename _Traits::pos_type             pos_type;
  68.       typedef typename _Traits::off_type             off_type;
  69.       typedef _Traits                                traits_type;
  70.       //@}
  71.  
  72.       //@{
  73.       /**
  74.        *  @if maint
  75.        *  These are non-standard types.
  76.        *  @endif
  77.       */
  78.       typedef ctype<_CharT>                          __ctype_type;
  79.       typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> >
  80.                              __num_put_type;
  81.       typedef num_get<_CharT, istreambuf_iterator<_CharT, _Traits> >
  82.                              __num_get_type;
  83.       //@}
  84.  
  85.       // Data members:
  86.     protected:
  87.       basic_ostream<_CharT, _Traits>*                _M_tie;
  88.       mutable char_type                              _M_fill;
  89.       mutable bool                                   _M_fill_init;
  90.       basic_streambuf<_CharT, _Traits>*              _M_streambuf;
  91.  
  92.       // Cached use_facet<ctype>, which is based on the current locale info.
  93.       const __ctype_type*                            _M_ctype;
  94.       // For ostream.
  95.       const __num_put_type*                          _M_num_put;
  96.       // For istream.
  97.       const __num_get_type*                          _M_num_get;
  98.  
  99.     public:
  100.       //@{
  101.       /**
  102.        *  @brief  The quick-and-easy status check.
  103.        *
  104.        *  This allows you to write constructs such as
  105.        *  "if (!a_stream) ..." and "while (a_stream) ..."
  106.       */
  107.       operator void*() const
  108.       { return this->fail() ? 0 : const_cast<basic_ios*>(this); }
  109.  
  110.       bool
  111.       operator!() const
  112.       { return this->fail(); }
  113.       //@}
  114.  
  115.       /**
  116.        *  @brief  Returns the error state of the stream buffer.
  117.        *  @return  A bit pattern (well, isn't everything?)
  118.        *
  119.        *  See std::ios_base::iostate for the possible bit values.  Most
  120.        *  users will call one of the interpreting wrappers, e.g., good().
  121.       */
  122.       iostate
  123.       rdstate() const
  124.       { return _M_streambuf_state; }
  125.  
  126.       /**
  127.        *  @brief  [Re]sets the error state.
  128.        *  @param  state  The new state flag(s) to set.
  129.        *
  130.        *  See std::ios_base::iostate for the possible bit values.  Most
  131.        *  users will not need to pass an argument.
  132.       */
  133.       void
  134.       clear(iostate __state = goodbit);
  135.  
  136.       /**
  137.        *  @brief  Sets additional flags in the error state.
  138.        *  @param  state  The additional state flag(s) to set.
  139.        *
  140.        *  See std::ios_base::iostate for the possible bit values.
  141.       */
  142.       void
  143.       setstate(iostate __state)
  144.       { this->clear(this->rdstate() | __state); }
  145.  
  146.       // Flip the internal state on for the proper state bits, then re
  147.       // throws the propagated exception if bit also set in
  148.       // exceptions().
  149.       void
  150.       _M_setstate(iostate __state)
  151.       {
  152.     // 27.6.1.2.1 Common requirements.
  153.     // Turn this on without causing an ios::failure to be thrown.
  154.     _M_streambuf_state |= __state;
  155.     if (this->exceptions() & __state)
  156.       __throw_exception_again;
  157.       }
  158.  
  159.       /**
  160.        *  @brief  Fast error checking.
  161.        *  @return  True if no error flags are set.
  162.        *
  163.        *  A wrapper around rdstate.
  164.       */
  165.       bool
  166.       good() const
  167.       { return this->rdstate() == 0; }
  168.  
  169.       /**
  170.        *  @brief  Fast error checking.
  171.        *  @return  True if the eofbit is set.
  172.        *
  173.        *  Note that other iostate flags may also be set.
  174.       */
  175.       bool
  176.       eof() const
  177.       { return (this->rdstate() & eofbit) != 0; }
  178.  
  179.       /**
  180.        *  @brief  Fast error checking.
  181.        *  @return  True if either the badbit or the failbit is set.
  182.        *
  183.        *  Checking the badbit in fail() is historical practice.
  184.        *  Note that other iostate flags may also be set.
  185.       */
  186.       bool
  187.       fail() const
  188.       { return (this->rdstate() & (badbit | failbit)) != 0; }
  189.  
  190.       /**
  191.        *  @brief  Fast error checking.
  192.        *  @return  True if the badbit is set.
  193.        *
  194.        *  Note that other iostate flags may also be set.
  195.       */
  196.       bool
  197.       bad() const
  198.       { return (this->rdstate() & badbit) != 0; }
  199.  
  200.       /**
  201.        *  @brief  Throwing exceptions on errors.
  202.        *  @return  The current exceptions mask.
  203.        *
  204.        *  This changes nothing in the stream.  See the one-argument version
  205.        *  of exceptions(iostate) for the meaning of the return value.
  206.       */
  207.       iostate
  208.       exceptions() const
  209.       { return _M_exception; }
  210.  
  211.       /**
  212.        *  @brief  Throwing exceptions on errors.
  213.        *  @param  except  The new exceptions mask.
  214.        *
  215.        *  By default, error flags are set silently.  You can set an
  216.        *  exceptions mask for each stream; if a bit in the mask becomes set
  217.        *  in the error flags, then an exception of type
  218.        *  std::ios_base::failure is thrown.
  219.        *
  220.        *  If the error flage is already set when the exceptions mask is
  221.        *  added, the exception is immediately thrown.  Try running the
  222.        *  following under GCC 3.1 or later:
  223.        *  @code
  224.        *  #include <iostream>
  225.        *  #include <fstream>
  226.        *  #include <exception>
  227.        *
  228.        *  int main()
  229.        *  {
  230.        *      std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
  231.        *
  232.        *      std::ifstream f ("/etc/motd");
  233.        *
  234.        *      std::cerr << "Setting badbit\n";
  235.        *      f.setstate (std::ios_base::badbit);
  236.        *
  237.        *      std::cerr << "Setting exception mask\n";
  238.        *      f.exceptions (std::ios_base::badbit);
  239.        *  }
  240.        *  @endcode
  241.       */
  242.       void
  243.       exceptions(iostate __except)
  244.       {
  245.         _M_exception = __except;
  246.         this->clear(_M_streambuf_state);
  247.       }
  248.  
  249.       // Constructor/destructor:
  250.       /**
  251.        *  @brief  Constructor performs initialization.
  252.        *
  253.        *  The parameter is passed by derived streams.
  254.       */
  255.       explicit
  256.       basic_ios(basic_streambuf<_CharT, _Traits>* __sb)
  257.       : ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0),
  258.       _M_ctype(0), _M_num_put(0), _M_num_get(0)
  259.       { this->init(__sb); }
  260.  
  261.       /**
  262.        *  @brief  Empty.
  263.        *
  264.        *  The destructor does nothing.  More specifically, it does not
  265.        *  destroy the streambuf held by rdbuf().
  266.       */
  267.       virtual
  268.       ~basic_ios() { }
  269.  
  270.       // Members:
  271.       /**
  272.        *  @brief  Fetches the current @e tied stream.
  273.        *  @return  A pointer to the tied stream, or NULL if the stream is
  274.        *           not tied.
  275.        *
  276.        *  A stream may be @e tied (or synchronized) to a second output
  277.        *  stream.  When this stream performs any I/O, the tied stream is
  278.        *  first flushed.  For example, @c std::cin is tied to @c std::cout.
  279.       */
  280.       basic_ostream<_CharT, _Traits>*
  281.       tie() const
  282.       { return _M_tie; }
  283.  
  284.       /**
  285.        *  @brief  Ties this stream to an output stream.
  286.        *  @param  tiestr  The output stream.
  287.        *  @return  The previously tied output stream, or NULL if the stream
  288.        *           was not tied.
  289.        *
  290.        *  This sets up a new tie; see tie() for more.
  291.       */
  292.       basic_ostream<_CharT, _Traits>*
  293.       tie(basic_ostream<_CharT, _Traits>* __tiestr)
  294.       {
  295.         basic_ostream<_CharT, _Traits>* __old = _M_tie;
  296.         _M_tie = __tiestr;
  297.         return __old;
  298.       }
  299.  
  300.       /**
  301.        *  @brief  Accessing the underlying buffer.
  302.        *  @return  The current stream buffer.
  303.        *
  304.        *  This does not change the state of the stream.
  305.       */
  306.       basic_streambuf<_CharT, _Traits>*
  307.       rdbuf() const
  308.       { return _M_streambuf; }
  309.  
  310.       /**
  311.        *  @brief  Changing the underlying buffer.
  312.        *  @param  sb  The new stream buffer.
  313.        *  @return  The previous stream buffer.
  314.        *
  315.        *  Associates a new buffer with the current stream, and clears the
  316.        *  error state.
  317.        *
  318.        *  Due to historical accidents which the LWG refuses to correct, the
  319.        *  I/O library suffers from a design error:  this function is hidden
  320.        *  in derived classes by overrides of the zero-argument @c rdbuf(),
  321.        *  which is non-virtual for hysterical raisins.  As a result, you
  322.        *  must use explicit qualifications to access this function via any
  323.        *  derived class.  For example:
  324.        *
  325.        *  @code
  326.        *  std::fstream     foo;         // or some other derived type
  327.        *  std::streambuf*  p = .....;
  328.        *
  329.        *  foo.ios::rdbuf(p);            // ios == basic_ios<char>
  330.        *  @endcode
  331.       */
  332.       basic_streambuf<_CharT, _Traits>*
  333.       rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
  334.  
  335.       /**
  336.        *  @brief  Copies fields of __rhs into this.
  337.        *  @param  __rhs  The source values for the copies.
  338.        *  @return  Reference to this object.
  339.        *
  340.        *  All fields of __rhs are copied into this object except that rdbuf()
  341.        *  and rdstate() remain unchanged.  All values in the pword and iword
  342.        *  arrays are copied.  Before copying, each callback is invoked with
  343.        *  erase_event.  After copying, each (new) callback is invoked with
  344.        *  copyfmt_event.  The final step is to copy exceptions().
  345.       */
  346.       basic_ios&
  347.       copyfmt(const basic_ios& __rhs);
  348.  
  349.       /**
  350.        *  @brief  Retreives the "empty" character.
  351.        *  @return  The current fill character.
  352.        *
  353.        *  It defaults to a space (' ') in the current locale.
  354.       */
  355.       char_type
  356.       fill() const
  357.       {
  358.     if (!_M_fill_init)
  359.       {
  360.         _M_fill = this->widen(' ');
  361.         _M_fill_init = true;
  362.       }
  363.     return _M_fill;
  364.       }
  365.  
  366.       /**
  367.        *  @brief  Sets a new "empty" character.
  368.        *  @param  ch  The new character.
  369.        *  @return  The previous fill character.
  370.        *
  371.        *  The fill character is used to fill out space when P+ characters
  372.        *  have been requested (e.g., via setw), Q characters are actually
  373.        *  used, and Q<P.  It defaults to a space (' ') in the current locale.
  374.       */
  375.       char_type
  376.       fill(char_type __ch)
  377.       {
  378.     char_type __old = this->fill();
  379.     _M_fill = __ch;
  380.     return __old;
  381.       }
  382.  
  383.       // Locales:
  384.       /**
  385.        *  @brief  Moves to a new locale.
  386.        *  @param  loc  The new locale.
  387.        *  @return  The previous locale.
  388.        *
  389.        *  Calls @c ios_base::imbue(loc), and if a stream buffer is associated
  390.        *  with this stream, calls that buffer's @c pubimbue(loc).
  391.        *
  392.        *  Additional l10n notes are at
  393.        *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
  394.       */
  395.       locale
  396.       imbue(const locale& __loc);
  397.  
  398.       /**
  399.        *  @brief  Squeezes characters.
  400.        *  @param  c  The character to narrow.
  401.        *  @param  dfault  The character to narrow.
  402.        *  @return  The narrowed character.
  403.        *
  404.        *  Maps a character of @c char_type to a character of @c char,
  405.        *  if possible.
  406.        *
  407.        *  Returns the result of
  408.        *  @code
  409.        *    std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault)
  410.        *  @endcode
  411.        *
  412.        *  Additional l10n notes are at
  413.        *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
  414.       */
  415.       char
  416.       narrow(char_type __c, char __dfault) const;
  417.  
  418.       /**
  419.        *  @brief  Widens characters.
  420.        *  @param  c  The character to widen.
  421.        *  @return  The widened character.
  422.        *
  423.        *  Maps a character of @c char to a character of @c char_type.
  424.        *
  425.        *  Returns the result of
  426.        *  @code
  427.        *    std::use_facet<ctype<char_type> >(getloc()).widen(c)
  428.        *  @endcode
  429.        *
  430.        *  Additional l10n notes are at
  431.        *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
  432.       */
  433.       char_type
  434.       widen(char __c) const;
  435.  
  436.     protected:
  437.       // 27.4.5.1  basic_ios constructors
  438.       /**
  439.        *  @brief  Empty.
  440.        *
  441.        *  The default constructor does nothing and is not normally
  442.        *  accessible to users.
  443.       */
  444.       basic_ios()
  445.       : ios_base(), _M_tie(0), _M_fill(char_type()), _M_fill_init(false), 
  446.       _M_streambuf(0), _M_ctype(0), _M_num_put(0), _M_num_get(0)
  447.       { }
  448.  
  449.       /**
  450.        *  @brief  All setup is performed here.
  451.        *
  452.        *  This is called from the public constructor.  It is not virtual and
  453.        *  cannot be redefined.
  454.       */
  455.       void
  456.       init(basic_streambuf<_CharT, _Traits>* __sb);
  457.  
  458.       void
  459.       _M_cache_locale(const locale& __loc);
  460.     };
  461. } // namespace std
  462.  
  463. #ifndef _GLIBCXX_EXPORT_TEMPLATE
  464. #include <bits/basic_ios.tcc>
  465. #endif
  466.  
  467. #endif /* _BASIC_IOS_H */
  468.