Line data Source code
1 : // Output streams -*- C++ -*-
2 :
3 : // Copyright (C) 1997-2013 Free Software Foundation, Inc.
4 : //
5 : // This file is part of the GNU ISO C++ Library. This library is free
6 : // software; you can redistribute it and/or modify it under the
7 : // terms of the GNU General Public License as published by the
8 : // Free Software Foundation; either version 3, or (at your option)
9 : // any later version.
10 :
11 : // This library is distributed in the hope that it will be useful,
12 : // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 : // GNU General Public License for more details.
15 :
16 : // Under Section 7 of GPL version 3, you are granted additional
17 : // permissions described in the GCC Runtime Library Exception, version
18 : // 3.1, as published by the Free Software Foundation.
19 :
20 : // You should have received a copy of the GNU General Public License and
21 : // a copy of the GCC Runtime Library Exception along with this program;
22 : // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 : // <http://www.gnu.org/licenses/>.
24 :
25 : /** @file include/ostream
26 : * This is a Standard C++ Library header.
27 : */
28 :
29 : //
30 : // ISO C++ 14882: 27.6.2 Output streams
31 : //
32 :
33 : #ifndef _GLIBCXX_OSTREAM
34 : #define _GLIBCXX_OSTREAM 1
35 :
36 : #pragma GCC system_header
37 :
38 : #include <ios>
39 : #include <bits/ostream_insert.h>
40 :
41 : namespace std _GLIBCXX_VISIBILITY(default)
42 : {
43 : _GLIBCXX_BEGIN_NAMESPACE_VERSION
44 :
45 : /**
46 : * @brief Template class basic_ostream.
47 : * @ingroup io
48 : *
49 : * @tparam _CharT Type of character stream.
50 : * @tparam _Traits Traits for character type, defaults to
51 : * char_traits<_CharT>.
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):
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 : /**
77 : * @brief Base constructor.
78 : *
79 : * This ctor is almost never called by the user directly, rather from
80 : * derived classes' initialization lists, which pass a pointer to
81 : * their own stream buffer.
82 : */
83 : explicit
84 : basic_ostream(__streambuf_type* __sb)
85 : { this->init(__sb); }
86 :
87 : /**
88 : * @brief Base destructor.
89 : *
90 : * This does very little apart from providing a virtual base dtor.
91 : */
92 : virtual
93 : ~basic_ostream() { }
94 :
95 : /// Safe prefix/suffix operations.
96 : class sentry;
97 : friend class sentry;
98 :
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 0 : 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&
127 : operator<<(ios_base& (*__pf) (ios_base&))
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 0 : __pf(*this);
133 : return *this;
134 : }
135 : //@}
136 :
137 : //@{
138 : /**
139 : * @name 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 : /**
158 : * @brief Integer arithmetic inserters
159 : * @param __n A variable of builtin integral type.
160 : * @return @c *this if successful
161 : *
162 : * These functions use the stream's current locale (specifically, the
163 : * @c num_get facet) to perform numeric formatting.
164 : */
165 : __ostream_type&
166 : operator<<(long __n)
167 : { return _M_insert(__n); }
168 :
169 : __ostream_type&
170 : operator<<(unsigned long __n)
171 : { return _M_insert(__n); }
172 :
173 : __ostream_type&
174 : operator<<(bool __n)
175 : { return _M_insert(__n); }
176 :
177 : __ostream_type&
178 : operator<<(short __n);
179 :
180 : __ostream_type&
181 : operator<<(unsigned short __n)
182 : {
183 : // _GLIBCXX_RESOLVE_LIB_DEFECTS
184 : // 117. basic_ostream uses nonexistent num_put member functions.
185 : return _M_insert(static_cast<unsigned long>(__n));
186 : }
187 :
188 : __ostream_type&
189 : operator<<(int __n);
190 :
191 : __ostream_type&
192 : operator<<(unsigned int __n)
193 : {
194 : // _GLIBCXX_RESOLVE_LIB_DEFECTS
195 : // 117. basic_ostream uses nonexistent num_put member functions.
196 : return _M_insert(static_cast<unsigned long>(__n));
197 : }
198 :
199 : #ifdef _GLIBCXX_USE_LONG_LONG
200 : __ostream_type&
201 : operator<<(long long __n)
202 : { return _M_insert(__n); }
203 :
204 : __ostream_type&
205 : operator<<(unsigned long long __n)
206 0 : { return _M_insert(__n); }
207 : #endif
208 : //@}
209 :
210 : //@{
211 : /**
212 : * @brief Floating point arithmetic inserters
213 : * @param __f A variable of builtin floating point type.
214 : * @return @c *this if successful
215 : *
216 : * These functions use the stream's current locale (specifically, the
217 : * @c num_get facet) to perform numeric formatting.
218 : */
219 : __ostream_type&
220 : operator<<(double __f)
221 : { return _M_insert(__f); }
222 :
223 : __ostream_type&
224 : operator<<(float __f)
225 : {
226 : // _GLIBCXX_RESOLVE_LIB_DEFECTS
227 : // 117. basic_ostream uses nonexistent num_put member functions.
228 : return _M_insert(static_cast<double>(__f));
229 : }
230 :
231 : __ostream_type&
232 : operator<<(long double __f)
233 : { return _M_insert(__f); }
234 : //@}
235 :
236 : /**
237 : * @brief Pointer arithmetic inserters
238 : * @param __p A variable of pointer type.
239 : * @return @c *this if successful
240 : *
241 : * These functions use the stream's current locale (specifically, the
242 : * @c num_get facet) to perform numeric formatting.
243 : */
244 : __ostream_type&
245 : operator<<(const void* __p)
246 : { return _M_insert(__p); }
247 :
248 : /**
249 : * @brief Extracting from another streambuf.
250 : * @param __sb A pointer to a streambuf
251 : *
252 : * This function behaves like one of the basic arithmetic extractors,
253 : * in that it also constructs a sentry object and has the same error
254 : * handling behavior.
255 : *
256 : * If @p __sb is NULL, the stream will set failbit in its error state.
257 : *
258 : * Characters are extracted from @p __sb and inserted into @c *this
259 : * until one of the following occurs:
260 : *
261 : * - the input stream reaches end-of-file,
262 : * - insertion into the output sequence fails (in this case, the
263 : * character that would have been inserted is not extracted), or
264 : * - an exception occurs while getting a character from @p __sb, which
265 : * sets failbit in the error state
266 : *
267 : * If the function inserts no characters, failbit is set.
268 : */
269 : __ostream_type&
270 : operator<<(__streambuf_type* __sb);
271 : //@}
272 :
273 : //@{
274 : /**
275 : * @name Unformatted Output Functions
276 : *
277 : * All the unformatted output functions have some common behavior.
278 : * Each starts by constructing a temporary object of type
279 : * std::basic_ostream::sentry. This has several effects, concluding
280 : * with the setting of a status flag; see the sentry documentation
281 : * for more.
282 : *
283 : * If the sentry status is good, the function tries to generate
284 : * whatever data is appropriate for the type of the argument.
285 : *
286 : * If an exception is thrown during insertion, ios_base::badbit
287 : * will be turned on in the stream's error state. If badbit is on in
288 : * the stream's exceptions mask, the exception will be rethrown
289 : * without completing its actions.
290 : */
291 :
292 : /**
293 : * @brief Simple insertion.
294 : * @param __c The character to insert.
295 : * @return *this
296 : *
297 : * Tries to insert @p __c.
298 : *
299 : * @note This function is not overloaded on signed char and
300 : * unsigned char.
301 : */
302 : __ostream_type&
303 : put(char_type __c);
304 :
305 : /**
306 : * @brief Core write functionality, without sentry.
307 : * @param __s The array to insert.
308 : * @param __n Maximum number of characters to insert.
309 : */
310 : void
311 : _M_write(const char_type* __s, streamsize __n)
312 : {
313 : const streamsize __put = this->rdbuf()->sputn(__s, __n);
314 : if (__put != __n)
315 : this->setstate(ios_base::badbit);
316 : }
317 :
318 : /**
319 : * @brief Character string insertion.
320 : * @param __s The array to insert.
321 : * @param __n Maximum number of characters to insert.
322 : * @return *this
323 : *
324 : * Characters are copied from @p __s and inserted into the stream until
325 : * one of the following happens:
326 : *
327 : * - @p __n characters are inserted
328 : * - inserting into the output sequence fails (in this case, badbit
329 : * will be set in the stream's error state)
330 : *
331 : * @note This function is not overloaded on signed char and
332 : * unsigned char.
333 : */
334 : __ostream_type&
335 : write(const char_type* __s, streamsize __n);
336 : //@}
337 :
338 : /**
339 : * @brief Synchronizing the stream buffer.
340 : * @return *this
341 : *
342 : * If @c rdbuf() is a null pointer, changes nothing.
343 : *
344 : * Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
345 : * sets badbit.
346 : */
347 : __ostream_type&
348 : flush();
349 :
350 : /**
351 : * @brief Getting the current write position.
352 : * @return A file position object.
353 : *
354 : * If @c fail() is not false, returns @c pos_type(-1) to indicate
355 : * failure. Otherwise returns @c rdbuf()->pubseekoff(0,cur,out).
356 : */
357 : pos_type
358 : tellp();
359 :
360 : /**
361 : * @brief Changing the current write position.
362 : * @param __pos A file position object.
363 : * @return *this
364 : *
365 : * If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos). If
366 : * that function fails, sets failbit.
367 : */
368 : __ostream_type&
369 : seekp(pos_type);
370 :
371 : /**
372 : * @brief Changing the current write position.
373 : * @param __off A file offset object.
374 : * @param __dir The direction in which to seek.
375 : * @return *this
376 : *
377 : * If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
378 : * If that function fails, sets failbit.
379 : */
380 : __ostream_type&
381 : seekp(off_type, ios_base::seekdir);
382 :
383 : protected:
384 : basic_ostream()
385 : { this->init(0); }
386 :
387 : template<typename _ValueT>
388 : __ostream_type&
389 : _M_insert(_ValueT __v);
390 : };
391 :
392 : /**
393 : * @brief Performs setup work for output streams.
394 : *
395 : * Objects of this class are created before all of the standard
396 : * inserters are run. It is responsible for <em>exception-safe prefix and
397 : * suffix operations</em>.
398 : */
399 : template <typename _CharT, typename _Traits>
400 : class basic_ostream<_CharT, _Traits>::sentry
401 : {
402 : // Data Members.
403 : bool _M_ok;
404 : basic_ostream<_CharT, _Traits>& _M_os;
405 :
406 : public:
407 : /**
408 : * @brief The constructor performs preparatory work.
409 : * @param __os The output stream to guard.
410 : *
411 : * If the stream state is good (@a __os.good() is true), then if the
412 : * stream is tied to another output stream, @c is.tie()->flush()
413 : * is called to synchronize the output sequences.
414 : *
415 : * If the stream state is still good, then the sentry state becomes
416 : * true (@a okay).
417 : */
418 : explicit
419 : sentry(basic_ostream<_CharT, _Traits>& __os);
420 :
421 : /**
422 : * @brief Possibly flushes the stream.
423 : *
424 : * If @c ios_base::unitbuf is set in @c os.flags(), and
425 : * @c std::uncaught_exception() is true, the sentry destructor calls
426 : * @c flush() on the output stream.
427 : */
428 : ~sentry()
429 : {
430 : // XXX MT
431 : if (bool(_M_os.flags() & ios_base::unitbuf) && !uncaught_exception())
432 : {
433 : // Can't call flush directly or else will get into recursive lock.
434 : if (_M_os.rdbuf() && _M_os.rdbuf()->pubsync() == -1)
435 : _M_os.setstate(ios_base::badbit);
436 : }
437 : }
438 :
439 : /**
440 : * @brief Quick status checking.
441 : * @return The sentry state.
442 : *
443 : * For ease of use, sentries may be converted to booleans. The
444 : * return value is that of the sentry state (true == okay).
445 : */
446 : #if __cplusplus >= 201103L
447 : explicit
448 : #endif
449 : operator bool() const
450 : { return _M_ok; }
451 : };
452 :
453 : //@{
454 : /**
455 : * @brief Character inserters
456 : * @param __out An output stream.
457 : * @param __c A character.
458 : * @return out
459 : *
460 : * Behaves like one of the formatted arithmetic inserters described in
461 : * std::basic_ostream. After constructing a sentry object with good
462 : * status, this function inserts a single character and any required
463 : * padding (as determined by [22.2.2.2.2]). @c __out.width(0) is then
464 : * called.
465 : *
466 : * If @p __c is of type @c char and the character type of the stream is not
467 : * @c char, the character is widened before insertion.
468 : */
469 : template<typename _CharT, typename _Traits>
470 : inline basic_ostream<_CharT, _Traits>&
471 : operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c)
472 : { return __ostream_insert(__out, &__c, 1); }
473 :
474 : template<typename _CharT, typename _Traits>
475 : inline basic_ostream<_CharT, _Traits>&
476 : operator<<(basic_ostream<_CharT, _Traits>& __out, char __c)
477 : { return (__out << __out.widen(__c)); }
478 :
479 : // Specialization
480 : template <class _Traits>
481 : inline basic_ostream<char, _Traits>&
482 : operator<<(basic_ostream<char, _Traits>& __out, char __c)
483 : { return __ostream_insert(__out, &__c, 1); }
484 :
485 : // Signed and unsigned
486 : template<class _Traits>
487 : inline basic_ostream<char, _Traits>&
488 : operator<<(basic_ostream<char, _Traits>& __out, signed char __c)
489 : { return (__out << static_cast<char>(__c)); }
490 :
491 : template<class _Traits>
492 : inline basic_ostream<char, _Traits>&
493 : operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c)
494 : { return (__out << static_cast<char>(__c)); }
495 : //@}
496 :
497 : //@{
498 : /**
499 : * @brief String inserters
500 : * @param __out An output stream.
501 : * @param __s A character string.
502 : * @return out
503 : * @pre @p __s must be a non-NULL pointer
504 : *
505 : * Behaves like one of the formatted arithmetic inserters described in
506 : * std::basic_ostream. After constructing a sentry object with good
507 : * status, this function inserts @c traits::length(__s) characters starting
508 : * at @p __s, widened if necessary, followed by any required padding (as
509 : * determined by [22.2.2.2.2]). @c __out.width(0) is then called.
510 : */
511 : template<typename _CharT, typename _Traits>
512 : inline basic_ostream<_CharT, _Traits>&
513 : operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s)
514 : {
515 : if (!__s)
516 : __out.setstate(ios_base::badbit);
517 : else
518 : __ostream_insert(__out, __s,
519 : static_cast<streamsize>(_Traits::length(__s)));
520 : return __out;
521 : }
522 :
523 : template<typename _CharT, typename _Traits>
524 : basic_ostream<_CharT, _Traits> &
525 : operator<<(basic_ostream<_CharT, _Traits>& __out, const char* __s);
526 :
527 : // Partial specializations
528 : template<class _Traits>
529 : inline basic_ostream<char, _Traits>&
530 : operator<<(basic_ostream<char, _Traits>& __out, const char* __s)
531 : {
532 : if (!__s)
533 : __out.setstate(ios_base::badbit);
534 : else
535 : __ostream_insert(__out, __s,
536 : static_cast<streamsize>(_Traits::length(__s)));
537 : return __out;
538 : }
539 :
540 : // Signed and unsigned
541 : template<class _Traits>
542 : inline basic_ostream<char, _Traits>&
543 : operator<<(basic_ostream<char, _Traits>& __out, const signed char* __s)
544 : { return (__out << reinterpret_cast<const char*>(__s)); }
545 :
546 : template<class _Traits>
547 : inline basic_ostream<char, _Traits> &
548 : operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s)
549 : { return (__out << reinterpret_cast<const char*>(__s)); }
550 : //@}
551 :
552 : // Standard basic_ostream manipulators
553 :
554 : /**
555 : * @brief Write a newline and flush the stream.
556 : *
557 : * This manipulator is often mistakenly used when a simple newline is
558 : * desired, leading to poor buffering performance. See
559 : * http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch25s02.html
560 : * for more on this subject.
561 : */
562 : template<typename _CharT, typename _Traits>
563 : inline basic_ostream<_CharT, _Traits>&
564 : endl(basic_ostream<_CharT, _Traits>& __os)
565 : { return flush(__os.put(__os.widen('\n'))); }
566 :
567 : /**
568 : * @brief Write a null character into the output sequence.
569 : *
570 : * <em>Null character</em> is @c CharT() by definition. For CharT
571 : * of @c char, this correctly writes the ASCII @c NUL character
572 : * string terminator.
573 : */
574 : template<typename _CharT, typename _Traits>
575 : inline basic_ostream<_CharT, _Traits>&
576 : ends(basic_ostream<_CharT, _Traits>& __os)
577 : { return __os.put(_CharT()); }
578 :
579 : /**
580 : * @brief Flushes the output stream.
581 : *
582 : * This manipulator simply calls the stream's @c flush() member function.
583 : */
584 : template<typename _CharT, typename _Traits>
585 : inline basic_ostream<_CharT, _Traits>&
586 : flush(basic_ostream<_CharT, _Traits>& __os)
587 : { return __os.flush(); }
588 :
589 : #if __cplusplus >= 201103L
590 : /**
591 : * @brief Generic inserter for rvalue stream
592 : * @param __os An input stream.
593 : * @param __x A reference to the object being inserted.
594 : * @return os
595 : *
596 : * This is just a forwarding function to allow insertion to
597 : * rvalue streams since they won't bind to the inserter functions
598 : * that take an lvalue reference.
599 : */
600 : template<typename _CharT, typename _Traits, typename _Tp>
601 : inline basic_ostream<_CharT, _Traits>&
602 : operator<<(basic_ostream<_CharT, _Traits>&& __os, const _Tp& __x)
603 : {
604 : __os << __x;
605 : return __os;
606 : }
607 : #endif // C++11
608 :
609 : _GLIBCXX_END_NAMESPACE_VERSION
610 : } // namespace std
611 :
612 : #include <bits/ostream.tcc>
613 :
614 : #endif /* _GLIBCXX_OSTREAM */
|
