home *** CD-ROM | disk | FTP | other *** search
/ Beginning C++ Through Gam…rogramming (2nd Edition) / BCGP2E.ISO / bloodshed / devcpp-4.9.9.2_setup.exe / ostream < prev    next >
Text File  |  2005-01-29  |  19KB  |  549 lines
  1. // Output streams -*- C++ -*-
  2.  
  3. // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003
  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. //
  32. // ISO C++ 14882: 27.6.2  Output streams
  33. //
  34.  
  35. /** @file ostream
  36.  *  This is a Standard C++ Library header.  You should @c #include this header
  37.  *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
  38.  */
  39.  
  40. #ifndef _GLIBCXX_OSTREAM
  41. #define _GLIBCXX_OSTREAM 1
  42.  
  43. #pragma GCC system_header
  44.  
  45. #include <ios>
  46.  
  47. namespace std
  48. {
  49.   // [27.6.2.1] Template class basic_ostream
  50.   /**
  51.    *  @brief  Controlling output.
  52.    *
  53.    *  This is the base class for all output streams.  It provides text
  54.    *  formatting of all builtin types, and communicates with any class
  55.    *  derived from basic_streambuf to do the actual output.
  56.   */
  57.   template<typename _CharT, typename _Traits>
  58.     class basic_ostream : virtual public basic_ios<_CharT, _Traits>
  59.     {
  60.     public:
  61.       // Types (inherited from basic_ios (27.4.4)):
  62.       typedef _CharT                             char_type;
  63.       typedef typename _Traits::int_type         int_type;
  64.       typedef typename _Traits::pos_type         pos_type;
  65.       typedef typename _Traits::off_type         off_type;
  66.       typedef _Traits                            traits_type;
  67.       
  68.       // Non-standard Types:
  69.       typedef basic_streambuf<_CharT, _Traits>         __streambuf_type;
  70.       typedef basic_ios<_CharT, _Traits>        __ios_type;
  71.       typedef basic_ostream<_CharT, _Traits>        __ostream_type;
  72.       typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> >        
  73.                                   __num_put_type;
  74.       typedef ctype<_CharT>                       __ctype_type;
  75.  
  76.       template<typename _CharT2, typename _Traits2>
  77.         friend basic_ostream<_CharT2, _Traits2>&
  78.         operator<<(basic_ostream<_CharT2, _Traits2>&, _CharT2);
  79.  
  80.       template<typename _Traits2>
  81.         friend basic_ostream<char, _Traits2>&
  82.         operator<<(basic_ostream<char, _Traits2>&, char);
  83.  
  84.       template<typename _CharT2, typename _Traits2>
  85.         friend basic_ostream<_CharT2, _Traits2>&
  86.         operator<<(basic_ostream<_CharT2, _Traits2>&, const _CharT2*);
  87.  
  88.       template<typename _Traits2>
  89.         friend basic_ostream<char, _Traits2>&
  90.         operator<<(basic_ostream<char, _Traits2>&, const char*);
  91.  
  92.       template<typename _CharT2, typename _Traits2>
  93.         friend basic_ostream<_CharT2, _Traits2>&
  94.         operator<<(basic_ostream<_CharT2, _Traits2>&, const char*);
  95.  
  96.       // [27.6.2.2] constructor/destructor
  97.       /**
  98.        *  @brief  Base constructor.
  99.        *
  100.        *  This ctor is almost never called by the user directly, rather from
  101.        *  derived classes' initialization lists, which pass a pointer to
  102.        *  their own stream buffer.
  103.       */
  104.       explicit 
  105.       basic_ostream(__streambuf_type* __sb)
  106.       { this->init(__sb); }
  107.  
  108.       /**
  109.        *  @brief  Base destructor.
  110.        *
  111.        *  This does very little apart from providing a virtual base dtor.
  112.       */
  113.       virtual 
  114.       ~basic_ostream() { }
  115.  
  116.       // [27.6.2.3] prefix/suffix
  117.       class sentry;
  118.       friend class sentry;
  119.       
  120.       // [27.6.2.5] formatted output
  121.       // [27.6.2.5.3]  basic_ostream::operator<<
  122.       //@{
  123.       /**
  124.        *  @brief  Interface for manipulators.
  125.        *
  126.        *  Manuipulators such as @c std::endl and @c std::hex use these
  127.        *  functions in constructs like "std::cout << std::endl".  For more
  128.        *  information, see the iomanip header.
  129.       */
  130.       inline __ostream_type&
  131.       operator<<(__ostream_type& (*__pf)(__ostream_type&));
  132.       
  133.       inline __ostream_type&
  134.       operator<<(__ios_type& (*__pf)(__ios_type&));
  135.       
  136.       inline __ostream_type&
  137.       operator<<(ios_base& (*__pf) (ios_base&));
  138.       //@}
  139.  
  140.       // [27.6.2.5.2] arithmetic inserters
  141.       /**
  142.        *  @name Arithmetic Inserters
  143.        *
  144.        *  All the @c operator<< functions (aka <em>formatted output
  145.        *  functions</em>) have some common behavior.  Each starts by
  146.        *  constructing a temporary object of type std::basic_ostream::sentry.
  147.        *  This can have several effects, concluding with the setting of a
  148.        *  status flag; see the sentry documentation for more.
  149.        *
  150.        *  If the sentry status is good, the function tries to generate
  151.        *  whatever data is appropriate for the type of the argument.
  152.        *
  153.        *  If an exception is thrown during insertion, ios_base::badbit
  154.        *  will be turned on in the stream's error state without causing an
  155.        *  ios_base::failure to be thrown.  The original exception will then
  156.        *  be rethrown.
  157.       */
  158.       //@{
  159.       /**
  160.        *  @brief  Basic arithmetic inserters
  161.        *  @param  A variable of builtin type.
  162.        *  @return  @c *this if successful
  163.        *
  164.        *  These functions use the stream's current locale (specifically, the
  165.        *  @c num_get facet) to perform numeric formatting.
  166.       */
  167.       __ostream_type& 
  168.       operator<<(long __n);
  169.       
  170.       __ostream_type& 
  171.       operator<<(unsigned long __n);
  172.  
  173.       __ostream_type& 
  174.       operator<<(bool __n);
  175.  
  176.       __ostream_type& 
  177.       operator<<(short __n)
  178.       { 
  179.     ios_base::fmtflags __fmt = this->flags() & ios_base::basefield;
  180.     if (__fmt & ios_base::oct || __fmt & ios_base::hex)
  181.       return this->operator<<(static_cast<unsigned long>
  182.                   (static_cast<unsigned short>(__n)));
  183.     else
  184.       return this->operator<<(static_cast<long>(__n));
  185.       }
  186.  
  187.       __ostream_type& 
  188.       operator<<(unsigned short __n)
  189.       { return this->operator<<(static_cast<unsigned long>(__n)); }
  190.  
  191.       __ostream_type& 
  192.       operator<<(int __n)
  193.       { 
  194.     ios_base::fmtflags __fmt = this->flags() & ios_base::basefield;
  195.     if (__fmt & ios_base::oct || __fmt & ios_base::hex)
  196.       return this->operator<<(static_cast<unsigned long>
  197.                   (static_cast<unsigned int>(__n)));
  198.     else
  199.       return this->operator<<(static_cast<long>(__n));
  200.       }
  201.  
  202.       __ostream_type& 
  203.       operator<<(unsigned int __n)
  204.       { return this->operator<<(static_cast<unsigned long>(__n)); }
  205.  
  206. #ifdef _GLIBCXX_USE_LONG_LONG
  207.       __ostream_type& 
  208.       operator<<(long long __n);
  209.  
  210.       __ostream_type& 
  211.       operator<<(unsigned long long __n);
  212. #endif
  213.  
  214.       __ostream_type& 
  215.       operator<<(double __f);
  216.  
  217.       __ostream_type& 
  218.       operator<<(float __f)
  219.       { return this->operator<<(static_cast<double>(__f)); }
  220.  
  221.       __ostream_type& 
  222.       operator<<(long double __f);
  223.  
  224.       __ostream_type& 
  225.       operator<<(const void* __p);
  226.  
  227.       /**
  228.        *  @brief  Extracting from another streambuf.
  229.        *  @param  sb  A pointer to a streambuf
  230.        *
  231.        *  This function behaves like one of the basic arithmetic extractors,
  232.        *  in that it also constructs a sentry object and has the same error
  233.        *  handling behavior.
  234.        *
  235.        *  If @a sb is NULL, the stream will set failbit in its error state.
  236.        *
  237.        *  Characters are extracted from @a sb and inserted into @c *this
  238.        *  until one of the following occurs:
  239.        *
  240.        *  - the input stream reaches end-of-file,
  241.        *  - insertion into the output sequence fails (in this case, the
  242.        *    character that would have been inserted is not extracted), or
  243.        *  - an exception occurs while getting a character from @a sb, which
  244.        *    sets failbit in the error state
  245.        *
  246.        *  If the function inserts no characters, failbit is set.
  247.       */
  248.       __ostream_type& 
  249.       operator<<(__streambuf_type* __sb);
  250.       //@}
  251.  
  252.       // [27.6.2.6] unformatted output functions
  253.       /**
  254.        *  @name Unformatted Output Functions
  255.        *
  256.        *  All the unformatted output functions have some common behavior.
  257.        *  Each starts by constructing a temporary object of type
  258.        *  std::basic_ostream::sentry.  This has several effects, concluding
  259.        *  with the setting of a status flag; see the sentry documentation
  260.        *  for more.
  261.        *
  262.        *  If the sentry status is good, the function tries to generate
  263.        *  whatever data is appropriate for the type of the argument.
  264.        *
  265.        *  If an exception is thrown during insertion, ios_base::badbit
  266.        *  will be turned on in the stream's error state.  If badbit is on in
  267.        *  the stream's exceptions mask, the exception will be rethrown
  268.        *  without completing its actions.
  269.       */
  270.       //@{
  271.       /**
  272.        *  @brief  Simple insertion.
  273.        *  @param  c  The character to insert.
  274.        *  @return  *this
  275.        *
  276.        *  Tries to insert @a c.
  277.        *
  278.        *  @note  This function is not overloaded on signed char and
  279.        *         unsigned char.
  280.       */
  281.       __ostream_type& 
  282.       put(char_type __c);
  283.  
  284.       // Core write functionality, without sentry.
  285.       void
  286.       _M_write(const char_type* __s, streamsize __n)
  287.       {
  288.     streamsize __put = this->rdbuf()->sputn(__s, __n);
  289.     if (__put != __n)
  290.       this->setstate(ios_base::badbit);
  291.       }
  292.  
  293.       /**
  294.        *  @brief  Character string insertion.
  295.        *  @param  s  The array to insert.
  296.        *  @param  n  Maximum number of characters to insert.
  297.        *  @return  *this
  298.        *
  299.        *  Characters are copied from @a s and inserted into the stream until
  300.        *  one of the following happens:
  301.        *
  302.        *  - @a n characters are inserted
  303.        *  - inserting into the output sequence fails (in this case, badbit
  304.        *    will be set in the stream's error state)
  305.        *
  306.        *  @note  This function is not overloaded on signed char and
  307.        *         unsigned char.
  308.       */
  309.       __ostream_type& 
  310.       write(const char_type* __s, streamsize __n);
  311.       //@}
  312.  
  313.       /**
  314.        *  @brief  Synchronizing the stream buffer.
  315.        *  @return  *this
  316.        *
  317.        *  If @c rdbuf() is a null pointer, changes nothing.
  318.        *
  319.        *  Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
  320.        *  sets badbit.
  321.       */
  322.       __ostream_type& 
  323.       flush();
  324.  
  325.       // [27.6.2.4] seek members
  326.       /**
  327.        *  @brief  Getting the current write position.
  328.        *  @return  A file position object.
  329.        *
  330.        *  If @c fail() is not false, returns @c pos_type(-1) to indicate
  331.        *  failure.  Otherwise returns @c rdbuf()->pubseekoff(0,cur,out).
  332.       */
  333.       pos_type 
  334.       tellp();
  335.  
  336.       /**
  337.        *  @brief  Changing the current write position.
  338.        *  @param  pos  A file position object.
  339.        *  @return  *this
  340.        *
  341.        *  If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos).  If
  342.        *  that function fails, sets failbit.
  343.       */
  344.       __ostream_type& 
  345.       seekp(pos_type);
  346.  
  347.       /**
  348.        *  @brief  Changing the current write position.
  349.        *  @param  off  A file offset object.
  350.        *  @param  dir  The direction in which to seek.
  351.        *  @return  *this
  352.        *
  353.        *  If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
  354.        *  If that function fails, sets failbit.
  355.       */
  356.        __ostream_type& 
  357.       seekp(off_type, ios_base::seekdir);
  358.       
  359.     protected:
  360.       explicit 
  361.       basic_ostream() { }
  362.     };
  363.  
  364.   /**
  365.    *  @brief  Performs setup work for output streams.
  366.    *
  367.    *  Objects of this class are created before all of the standard
  368.    *  inserters are run.  It is responsible for "exception-safe prefix and
  369.    *  suffix operations."  Additional actions may be added by the
  370.    *  implementation, and we list them in
  371.    *  http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5
  372.    *  under [27.6] notes.
  373.   */
  374.   template <typename _CharT, typename _Traits>
  375.     class basic_ostream<_CharT, _Traits>::sentry
  376.     {
  377.       // Data Members:
  378.       bool                 _M_ok;
  379.       basic_ostream<_CharT,_Traits>&     _M_os;
  380.       
  381.     public:
  382.       /**
  383.        *  @brief  The constructor performs preparatory work.
  384.        *  @param  os  The output stream to guard.
  385.        *
  386.        *  If the stream state is good (@a os.good() is true), then if the
  387.        *  stream is tied to another output stream, @c is.tie()->flush()
  388.        *  is called to synchronize the output sequences.
  389.        *
  390.        *  If the stream state is still good, then the sentry state becomes
  391.        *  true ("okay").
  392.       */
  393.       explicit
  394.       sentry(basic_ostream<_CharT,_Traits>& __os);
  395.  
  396.       /**
  397.        *  @brief  Possibly flushes the stream.
  398.        *
  399.        *  If @c ios_base::unitbuf is set in @c os.flags(), and
  400.        *  @c std::uncaught_exception() is true, the sentry destructor calls
  401.        *  @c flush() on the output stream.
  402.       */
  403.       ~sentry()
  404.       {
  405.     // XXX MT
  406.     if (_M_os.flags() & ios_base::unitbuf && !uncaught_exception())
  407.       {
  408.         // Can't call flush directly or else will get into recursive lock.
  409.         if (_M_os.rdbuf() && _M_os.rdbuf()->pubsync() == -1)
  410.           _M_os.setstate(ios_base::badbit);
  411.       }
  412.       }
  413.  
  414.       /**
  415.        *  @brief  Quick status checking.
  416.        *  @return  The sentry state.
  417.        *
  418.        *  For ease of use, sentries may be converted to booleans.  The
  419.        *  return value is that of the sentry state (true == okay).
  420.       */
  421.       operator bool() const
  422.       { return _M_ok; }
  423.     };
  424.  
  425.   // [27.6.2.5.4] character insertion templates
  426.   //@{
  427.   /**
  428.    *  @brief  Character inserters
  429.    *  @param  out  An output stream.
  430.    *  @param  c  A character.
  431.    *  @return  out
  432.    *
  433.    *  Behaves like one of the formatted arithmetic inserters described in
  434.    *  std::basic_ostream.  After constructing a sentry object with good
  435.    *  status, this function inserts a single character and any required
  436.    *  padding (as determined by [22.2.2.2.2]).  @c out.width(0) is then
  437.    *  called.
  438.    *
  439.    *  If @a c is of type @c char and the character type of the stream is not
  440.    *  @c char, the character is widened before insertion.
  441.   */
  442.   template<typename _CharT, typename _Traits>
  443.     basic_ostream<_CharT, _Traits>&
  444.     operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c);
  445.  
  446.   template<typename _CharT, typename _Traits>
  447.     basic_ostream<_CharT, _Traits>&
  448.     operator<<(basic_ostream<_CharT, _Traits>& __out, char __c)
  449.     { return (__out << __out.widen(__c)); }
  450.  
  451.   // Specialization
  452.   template <class _Traits> 
  453.     basic_ostream<char, _Traits>&
  454.     operator<<(basic_ostream<char, _Traits>& __out, char __c);
  455.  
  456.   // Signed and unsigned
  457.   template<class _Traits>
  458.     basic_ostream<char, _Traits>&
  459.     operator<<(basic_ostream<char, _Traits>& __out, signed char __c)
  460.     { return (__out << static_cast<char>(__c)); }
  461.   
  462.   template<class _Traits>
  463.     basic_ostream<char, _Traits>&
  464.     operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c)
  465.     { return (__out << static_cast<char>(__c)); }
  466.   //@}
  467.   
  468.   //@{
  469.   /**
  470.    *  @brief  String inserters
  471.    *  @param  out  An output stream.
  472.    *  @param  s  A character string.
  473.    *  @return  out
  474.    *  @pre  @a s must be a non-NULL pointer
  475.    *
  476.    *  Behaves like one of the formatted arithmetic inserters described in
  477.    *  std::basic_ostream.  After constructing a sentry object with good
  478.    *  status, this function inserts @c traits::length(s) characters starting
  479.    *  at @a s, widened if necessary, followed by any required padding (as
  480.    *  determined by [22.2.2.2.2]).  @c out.width(0) is then called.
  481.   */
  482.   template<typename _CharT, typename _Traits>
  483.     basic_ostream<_CharT, _Traits>&
  484.     operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s);
  485.  
  486.   template<typename _CharT, typename _Traits>
  487.     basic_ostream<_CharT, _Traits> &
  488.     operator<<(basic_ostream<_CharT, _Traits>& __out, const char* __s);
  489.  
  490.   // Partial specializationss
  491.   template<class _Traits>
  492.     basic_ostream<char, _Traits>&
  493.     operator<<(basic_ostream<char, _Traits>& __out, const char* __s);
  494.  
  495.   // Signed and unsigned
  496.   template<class _Traits>
  497.     basic_ostream<char, _Traits>&
  498.     operator<<(basic_ostream<char, _Traits>& __out, const signed char* __s)
  499.     { return (__out << reinterpret_cast<const char*>(__s)); }
  500.  
  501.   template<class _Traits>
  502.     basic_ostream<char, _Traits> &
  503.     operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s)
  504.     { return (__out << reinterpret_cast<const char*>(__s)); }
  505.   //@}
  506.  
  507.   // [27.6.2.7] standard basic_ostream manipulators
  508.   /**
  509.    *  @brief  Write a newline and flush the stream.
  510.    *
  511.    *  This manipulator is often mistakenly used when a simple newline is
  512.    *  desired, leading to poor buffering performance.  See
  513.    *  http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for more
  514.    *  on this subject.
  515.   */
  516.   template<typename _CharT, typename _Traits>
  517.     basic_ostream<_CharT, _Traits>& 
  518.     endl(basic_ostream<_CharT, _Traits>& __os)
  519.     { return flush(__os.put(__os.widen('\n'))); }
  520.  
  521.   /**
  522.    *  @brief  Write a null character into the output sequence.
  523.    *
  524.    *  "Null character" is @c CharT() by definition.  For CharT of @c char,
  525.    *  this correctly writes the ASCII @c NUL character string terminator.
  526.   */
  527.   template<typename _CharT, typename _Traits>
  528.     basic_ostream<_CharT, _Traits>& 
  529.     ends(basic_ostream<_CharT, _Traits>& __os)
  530.     { return __os.put(_CharT()); }
  531.   
  532.   /**
  533.    *  @brief  Flushes the output stream.
  534.    *
  535.    *  This manipulator simply calls the stream's @c flush() member function.
  536.   */
  537.   template<typename _CharT, typename _Traits>
  538.     basic_ostream<_CharT, _Traits>& 
  539.     flush(basic_ostream<_CharT, _Traits>& __os)
  540.     { return __os.flush(); }
  541.  
  542. } // namespace std
  543.  
  544. #ifndef _GLIBCXX_EXPORT_TEMPLATE
  545. # include <bits/ostream.tcc>
  546. #endif
  547.  
  548. #endif    /* _GLIBCXX_OSTREAM */
  549.