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