1 | // Output streams -*- C++ -*- |
2 | |
3 | // Copyright (C) 1997-2014 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 | 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 | __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 | { 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 | { return (__os << __x); } |
604 | #endif // C++11 |
605 | |
606 | _GLIBCXX_END_NAMESPACE_VERSION |
607 | } // namespace std |
608 | |
609 | #include <bits/ostream.tcc> |
610 | |
611 | #endif /* _GLIBCXX_OSTREAM */ |
612 | |