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