1// Output streams -*- C++ -*-
2
3// Copyright (C) 1997-2026 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#ifdef _GLIBCXX_SYSHDR
37#pragma GCC system_header
38#endif
39
40#include <bits/requires_hosted.h> // iostreams
41
42#include <bits/ostream.h>
43
44#ifdef __glibcxx_print
45# include <format> // format_string, make_format_args
46#endif
47
48#ifndef _GLIBCXX_NO_INLINE_PRINT
49# include <bits/ostream_print.h>
50#endif
51
52# define __glibcxx_want_print
53#include <bits/version.h> // __cpp_lib_print, __glibcxx_syncbuf
54
55namespace std _GLIBCXX_VISIBILITY(default)
56{
57_GLIBCXX_BEGIN_NAMESPACE_VERSION
58
59 // Standard basic_ostream manipulators
60
61 /**
62 * @brief Write a newline and flush the stream.
63 *
64 * This manipulator is often mistakenly used when a simple newline is
65 * desired, leading to poor buffering performance. See
66 * https://gcc.gnu.org/onlinedocs/libstdc++/manual/streambufs.html#io.streambuf.buffering
67 * for more on this subject.
68 */
69 template<typename _CharT, typename _Traits>
70 inline basic_ostream<_CharT, _Traits>&
71 endl(basic_ostream<_CharT, _Traits>& __os)
72 { return flush(__os.put(__os.widen('\n'))); }
73
74 /**
75 * @brief Write a null character into the output sequence.
76 *
77 * <em>Null character</em> is @c CharT() by definition. For CharT
78 * of @c char, this correctly writes the ASCII @c NUL character
79 * string terminator.
80 */
81 template<typename _CharT, typename _Traits>
82 inline basic_ostream<_CharT, _Traits>&
83 ends(basic_ostream<_CharT, _Traits>& __os)
84 { return __os.put(_CharT()); }
85
86 /**
87 * @brief Flushes the output stream.
88 *
89 * This manipulator simply calls the stream's @c flush() member function.
90 */
91 template<typename _CharT, typename _Traits>
92 inline basic_ostream<_CharT, _Traits>&
93 flush(basic_ostream<_CharT, _Traits>& __os)
94 { return __os.flush(); }
95
96#ifdef __glibcxx_syncbuf // C++ >= 20 && HOSTED && CXX11ABI
97 template<typename _CharT, typename _Traits>
98 class __syncbuf_base : public basic_streambuf<_CharT, _Traits>
99 {
100 public:
101 static bool*
102 _S_get(basic_streambuf<_CharT, _Traits>* __buf [[maybe_unused]]) noexcept
103 {
104#if __cpp_rtti
105 if (auto __p = dynamic_cast<__syncbuf_base*>(__buf))
106 return &__p->_M_emit_on_sync;
107#endif
108 return nullptr;
109 }
110
111 protected:
112 __syncbuf_base(basic_streambuf<_CharT, _Traits>* __w = nullptr)
113 : _M_wrapped(__w)
114 { }
115
116 basic_streambuf<_CharT, _Traits>* _M_wrapped = nullptr;
117 bool _M_emit_on_sync = false;
118 bool _M_needs_sync = false;
119 };
120
121 template<typename _CharT, typename _Traits>
122 inline basic_ostream<_CharT, _Traits>&
123 emit_on_flush(basic_ostream<_CharT, _Traits>& __os)
124 {
125 if (bool* __flag = __syncbuf_base<_CharT, _Traits>::_S_get(__os.rdbuf()))
126 *__flag = true;
127 return __os;
128 }
129
130 template<typename _CharT, typename _Traits>
131 inline basic_ostream<_CharT, _Traits>&
132 noemit_on_flush(basic_ostream<_CharT, _Traits>& __os)
133 {
134 if (bool* __flag = __syncbuf_base<_CharT, _Traits>::_S_get(__os.rdbuf()))
135 *__flag = false;
136 return __os;
137 }
138
139 template<typename _CharT, typename _Traits>
140 inline basic_ostream<_CharT, _Traits>&
141 flush_emit(basic_ostream<_CharT, _Traits>& __os)
142 {
143 struct _Restore
144 {
145 ~_Restore() { *_M_flag = _M_prev; }
146
147 bool _M_prev = false;
148 bool* _M_flag = &_M_prev;
149 } __restore;
150
151 if (bool* __flag = __syncbuf_base<_CharT, _Traits>::_S_get(__os.rdbuf()))
152 {
153 __restore._M_prev = *__flag;
154 __restore._M_flag = __flag;
155 *__flag = true;
156 }
157
158 __os.flush();
159 return __os;
160 }
161#endif // __glibcxx_syncbuf
162
163#if __cpp_lib_print // C++ >= 23
164 void
165 vprint_nonunicode(ostream& __os, string_view __fmt, format_args __args);
166
167 void
168 vprint_unicode(ostream& __os, string_view __fmt, format_args __args);
169
170 template<typename... _Args>
171 inline void
172 print(ostream& __os, format_string<_Args...> __fmt, _Args&&... __args)
173 {
174 auto __fmtargs = std::make_format_args(__args...);
175#if defined(_WIN32) && !defined(__CYGWIN__)
176 if constexpr (__unicode::__literal_encoding_is_utf8())
177 std::vprint_unicode(__os, __fmt.get(), __fmtargs);
178 else
179#endif
180 std::vprint_nonunicode(__os, __fmt.get(), __fmtargs);
181 }
182
183 template<typename... _Args>
184 inline void
185 println(ostream& __os, format_string<_Args...> __fmt, _Args&&... __args)
186 {
187 auto __fmtargs = std::make_format_args(__args...);
188 std::string __fmtn;
189 __fmtn.reserve(__fmt.get().size() + 1);
190 __fmtn = __fmt.get();
191 __fmtn += '\n';
192#if defined(_WIN32) && !defined(__CYGWIN__)
193 if constexpr (__unicode::__literal_encoding_is_utf8())
194 std::vprint_unicode(__os, __fmtn, __fmtargs);
195 else
196#endif
197 std::vprint_nonunicode(__os, __fmtn, __fmtargs);
198 }
199
200 // Defined for C++26, supported as an extension to C++23.
201 inline void println(ostream& __os)
202 {
203#if defined(_WIN32) && !defined(__CYGWIN__)
204 if constexpr (__unicode::__literal_encoding_is_utf8())
205 std::vprint_unicode(__os, "\n", std::make_format_args());
206 else
207#endif
208 __os.put('\n');
209 }
210#endif // __cpp_lib_print
211
212_GLIBCXX_END_NAMESPACE_VERSION
213} // namespace std
214
215#include <bits/ostream.tcc>
216
217#endif /* _GLIBCXX_OSTREAM */
218