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