1// -*- C++ -*-
2//===----------------------------------------------------------------------===//
3//
4// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5// See https://llvm.org/LICENSE.txt for license information.
6// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef _LIBCPP_PRINT
11#define _LIBCPP_PRINT
12
13/*
14namespace std {
15 // [print.fun], print functions
16 template<class... Args>
17 void print(format_string<Args...> fmt, Args&&... args);
18 void println(); // Since C++26
19 template<class... Args>
20 void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
21 void println(FILE* stream); // Since C++26
22
23 template<class... Args>
24 void println(format_string<Args...> fmt, Args&&... args);
25 template<class... Args>
26 void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
27
28 void vprint_unicode(string_view fmt, format_args args);
29 void vprint_unicode(FILE* stream, string_view fmt, format_args args);
30
31 void vprint_nonunicode(string_view fmt, format_args args);
32 void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
33}
34*/
35
36#if __cplusplus < 201103L && defined(_LIBCPP_USE_FROZEN_CXX03_HEADERS)
37# include <__cxx03/__config>
38#else
39# include <__assert>
40# include <__concepts/same_as.h>
41# include <__config>
42# include <__system_error/throw_system_error.h>
43# include <__utility/forward.h>
44# include <cerrno>
45# include <cstdio>
46# include <format>
47# include <string>
48# include <string_view>
49# include <version>
50
51# if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
52# pragma GCC system_header
53# endif
54
55_LIBCPP_BEGIN_NAMESPACE_STD
56
57# ifdef _LIBCPP_WIN32API
58_LIBCPP_EXPORTED_FROM_ABI bool __is_windows_terminal(FILE* __stream);
59
60# if _LIBCPP_HAS_WIDE_CHARACTERS
61// A wrapper for WriteConsoleW which is used to write to the Windows
62// console. This function is in the dylib to avoid pulling in windows.h
63// in the library headers. The function itself uses some private parts
64// of the dylib too.
65//
66// The function does not depend on the language standard used. Guarding
67// it with C++23 would fail since the dylib is currently built using C++20.
68//
69// Note the function is only implemented on the Windows platform.
70_LIBCPP_EXPORTED_FROM_ABI void __write_to_windows_console(FILE* __stream, wstring_view __view);
71# endif // _LIBCPP_HAS_WIDE_CHARACTERS
72# elif __has_include(<unistd.h>)
73_LIBCPP_EXPORTED_FROM_ABI bool __is_posix_terminal(FILE* __stream);
74# endif // _LIBCPP_WIN32API
75
76# if _LIBCPP_STD_VER >= 23
77
78# if _LIBCPP_HAS_UNICODE
79// This is the code to transcode UTF-8 to UTF-16. This is used on
80// Windows for the native Unicode API. The code is modeled to make it
81// easier to extend to
82//
83// P2728R0 Unicode in the Library, Part 1: UTF Transcoding
84//
85// This paper is still under heavy development so it makes no sense yet
86// to strictly follow the paper.
87namespace __unicode {
88
89// The names of these concepts are modelled after P2728R0, but the
90// implementation is not. char16_t may contain 32-bits so depending on the
91// number of bits is an issue.
92# ifdef _LIBCPP_SHORT_WCHAR
93template <class _Tp>
94concept __utf16_code_unit =
95 same_as<_Tp, char16_t>
96# if _LIBCPP_HAS_WIDE_CHARACTERS
97 || same_as<_Tp, wchar_t>
98# endif
99 ;
100template <class _Tp>
101concept __utf32_code_unit = same_as<_Tp, char32_t>;
102# else // _LIBCPP_SHORT_WCHAR
103template <class _Tp>
104concept __utf16_code_unit = same_as<_Tp, char16_t>;
105template <class _Tp>
106concept __utf32_code_unit =
107 same_as<_Tp, char32_t>
108# if _LIBCPP_HAS_WIDE_CHARACTERS
109 || same_as<_Tp, wchar_t>
110# endif
111 ;
112# endif // _LIBCPP_SHORT_WCHAR
113
114// Pass by reference since an output_iterator may not be copyable.
115template <class _OutIt>
116_LIBCPP_HIDE_FROM_ABI constexpr void __encode(_OutIt&, char32_t) = delete;
117
118template <class _OutIt>
119 requires __utf16_code_unit<iter_value_t<_OutIt>>
120_LIBCPP_HIDE_FROM_ABI constexpr void __encode(_OutIt& __out_it, char32_t __value) {
121 // [print.fun]/7 : "if `out` contains invalid code units, the behavior is undefined and implementations are encouraged
122 // to diagnose it".
123 _LIBCPP_ASSERT_UNCATEGORIZED(__is_scalar_value(__value), "an invalid unicode scalar value results in invalid UTF-16");
124
125 if (__value < 0x10000) {
126 *__out_it++ = static_cast<iter_value_t<_OutIt>>(__value);
127 return;
128 }
129
130 __value -= 0x10000;
131 *__out_it++ = 0xd800 + (__value >> 10);
132 *__out_it++ = 0xdc00 + (__value & 0x3FF);
133}
134
135template <class _OutIt>
136 requires __utf32_code_unit<iter_value_t<_OutIt>>
137_LIBCPP_HIDE_FROM_ABI constexpr void __encode(_OutIt& __out_it, char32_t __value) {
138 // [print.fun]/7 : "if `out` contains invalid code units, the behavior is undefined and implementations are encouraged
139 // to diagnose it".
140 _LIBCPP_ASSERT_UNCATEGORIZED(__is_scalar_value(__value), "an invalid unicode scalar value results in invalid UTF-32");
141 *__out_it++ = __value;
142}
143
144template <class _OutIt, input_iterator _InIt>
145 requires output_iterator<_OutIt, const iter_value_t<_OutIt>&> && (!same_as<iter_value_t<_OutIt>, iter_value_t<_InIt>>)
146_LIBCPP_HIDE_FROM_ABI constexpr _OutIt __transcode(_InIt __first, _InIt __last, _OutIt __out_it) {
147 // The __code_point_view has a basic_string_view interface.
148 // When transcoding becomes part of the standard we probably want to
149 // look at smarter algorithms.
150 // For example, when processing a code point that is encoded in
151 // 1 to 3 code units in UTF-8, the result will always be encoded
152 // in 1 code unit in UTF-16 (code points that require 4 code
153 // units in UTF-8 will require 2 code units in UTF-16).
154 //
155 // Note if P2728 is accepted types like int may become valid. In that case
156 // the __code_point_view should use a span. Libc++ will remove support for
157 // char_traits<int>.
158
159 // TODO PRINT Validate with clang-tidy
160 // NOLINTNEXTLINE(bugprone-dangling-handle)
161 basic_string_view<iter_value_t<_InIt>> __data{__first, __last};
162 __code_point_view<iter_value_t<_InIt>> __view{__data.begin(), __data.end()};
163 while (!__view.__at_end())
164 __unicode::__encode(__out_it, __view.__consume().__code_point);
165 return __out_it;
166}
167
168} // namespace __unicode
169
170# endif // _LIBCPP_HAS_UNICODE
171
172namespace __print {
173
174// [print.fun]/2
175// Effects: If the ordinary literal encoding ([lex.charset]) is UTF-8, equivalent to:
176// vprint_unicode(stream, fmt.str, make_format_args(args...));
177// Otherwise, equivalent to:
178// vprint_nonunicode(stream, fmt.str, make_format_args(args...));
179//
180// Based on the compiler and its compilation flags this value is or is
181// not true. As mentioned in P2093R14 this only affects Windows. The
182// test below could also be done for
183// - GCC using __GNUC_EXECUTION_CHARSET_NAME
184// https://gcc.gnu.org/onlinedocs/cpp/Common-Predefined-Macros.html
185// - Clang using __clang_literal_encoding__
186// https://clang.llvm.org/docs/LanguageExtensions.html#builtin-macros
187// (note at the time of writing Clang is hard-coded to UTF-8.)
188//
189
190# if !_LIBCPP_HAS_UNICODE
191inline constexpr bool __use_unicode_execution_charset = false;
192# elif defined(_MSVC_EXECUTION_CHARACTER_SET)
193// This is the same test MSVC STL uses in their implementation of <print>
194// See: https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers
195inline constexpr bool __use_unicode_execution_charset = _MSVC_EXECUTION_CHARACTER_SET == 65001;
196# else
197inline constexpr bool __use_unicode_execution_charset = true;
198# endif
199
200_LIBCPP_HIDE_FROM_ABI inline bool __is_terminal([[maybe_unused]] FILE* __stream) {
201 // The macro _LIBCPP_TESTING_PRINT_IS_TERMINAL is used to change
202 // the behavior in the test. This is not part of the public API.
203# ifdef _LIBCPP_TESTING_PRINT_IS_TERMINAL
204 return _LIBCPP_TESTING_PRINT_IS_TERMINAL(__stream);
205# elif _LIBCPP_AVAILABILITY_HAS_PRINT == 0 || !_LIBCPP_HAS_TERMINAL
206 return false;
207# elif defined(_LIBCPP_WIN32API)
208 return std::__is_windows_terminal(__stream);
209# elif __has_include(<unistd.h>)
210 return std::__is_posix_terminal(__stream);
211# else
212# error "Provide a way to determine whether a FILE* is a terminal"
213# endif
214}
215
216template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
217_LIBCPP_HIDE_FROM_ABI inline void
218__vprint_nonunicode(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl) {
219 _LIBCPP_ASSERT_NON_NULL(__stream, "__stream must be a valid pointer to an output C stream");
220 string __str = std::vformat(__fmt, __args);
221 if (__write_nl)
222 __str.push_back(c: '\n');
223
224 size_t __size = fwrite(ptr: __str.data(), size: 1, n: __str.size(), s: __stream);
225 if (__size < __str.size()) {
226 if (std::feof(__stream))
227 std::__throw_system_error(EIO, what_arg: "EOF while writing the formatted output");
228 std::__throw_system_error(ev: std::ferror(__stream), what_arg: "failed to write formatted output");
229 }
230}
231
232# if _LIBCPP_HAS_UNICODE
233
234// Note these helper functions are mainly used to aid testing.
235// On POSIX systems and Windows the output is no longer considered a
236// terminal when the output is redirected. Typically during testing the
237// output is redirected to be able to capture it. This makes it hard to
238// test this code path.
239template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
240_LIBCPP_HIDE_FROM_ABI inline void
241__vprint_unicode_posix(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl, bool __is_terminal) {
242 // TODO PRINT Should flush errors throw too?
243 if (__is_terminal)
244 std::fflush(__stream);
245
246 __print::__vprint_nonunicode(__stream, __fmt, __args, __write_nl);
247}
248
249# if _LIBCPP_HAS_WIDE_CHARACTERS
250template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
251_LIBCPP_HIDE_FROM_ABI inline void
252__vprint_unicode_windows(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl, bool __is_terminal) {
253 if (!__is_terminal)
254 return __print::__vprint_nonunicode(__stream, __fmt, __args, __write_nl);
255
256 // TODO PRINT Should flush errors throw too?
257 std::fflush(__stream);
258
259 string __str = std::vformat(__fmt, __args);
260 // UTF-16 uses the same number or less code units than UTF-8.
261 // However the size of the code unit is 16 bits instead of 8 bits.
262 //
263 // The buffer uses the worst-case estimate and should never resize.
264 // However when the string is large this could lead to OOM. Using a
265 // smaller size might work, but since the buffer uses a grow factor
266 // the final size might be larger when the estimate is wrong.
267 //
268 // TODO PRINT profile and improve the speed of this code.
269 __format::__retarget_buffer<wchar_t> __buffer{__str.size()};
270 __unicode::__transcode(first: __str.begin(), last: __str.end(), out_it: __buffer.__make_output_iterator());
271 if (__write_nl)
272 __buffer.push_back(c: L'\n');
273
274 [[maybe_unused]] wstring_view __view = __buffer.__view();
275
276 // The macro _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION is used to change
277 // the behavior in the test. This is not part of the public API.
278# ifdef _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION
279 _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION(__stream, __view);
280# elif defined(_LIBCPP_WIN32API)
281 std::__write_to_windows_console(__stream, __view);
282# else
283 std::__throw_runtime_error("No defintion of _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION and "
284 "__write_to_windows_console is not available.");
285# endif
286}
287# endif // _LIBCPP_HAS_WIDE_CHARACTERS
288
289template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
290_LIBCPP_HIDE_FROM_ABI inline void
291__vprint_unicode([[maybe_unused]] FILE* __stream,
292 [[maybe_unused]] string_view __fmt,
293 [[maybe_unused]] format_args __args,
294 [[maybe_unused]] bool __write_nl) {
295 _LIBCPP_ASSERT_NON_NULL(__stream, "__stream must be a valid pointer to an output C stream");
296
297 // [print.fun]
298 // 7 - Effects: If stream refers to a terminal capable of displaying
299 // Unicode, writes out to the terminal using the native Unicode
300 // API; if out contains invalid code units, the behavior is
301 // undefined and implementations are encouraged to diagnose it.
302 // Otherwise writes out to stream unchanged. If the native
303 // Unicode API is used, the function flushes stream before
304 // writing out.
305 // 8 - Throws: Any exception thrown by the call to vformat
306 // ([format.err.report]). system_error if writing to the terminal
307 // or stream fails. May throw bad_alloc.
308 // 9 - Recommended practice: If invoking the native Unicode API
309 // requires transcoding, implementations should substitute
310 // invalid code units with U+FFFD replacement character per the
311 // Unicode Standard, Chapter 3.9 U+FFFD Substitution in
312 // Conversion.
313
314 // On non-Windows platforms the Unicode API is the normal file I/O API
315 // so there the call can be forwarded to the non_unicode API. On
316 // Windows there is a different API. This API requires transcoding.
317
318# ifndef _LIBCPP_WIN32API
319 __print::__vprint_unicode_posix(__stream, __fmt, __args, __write_nl, is_terminal: __print::__is_terminal(__stream));
320# elif _LIBCPP_HAS_WIDE_CHARACTERS
321 __print::__vprint_unicode_windows(__stream, __fmt, __args, __write_nl, __print::__is_terminal(__stream));
322# else
323# error "Windows builds with wchar_t disabled are not supported."
324# endif
325}
326
327# endif // _LIBCPP_HAS_UNICODE
328
329} // namespace __print
330
331template <class... _Args>
332_LIBCPP_HIDE_FROM_ABI void print(FILE* __stream, format_string<_Args...> __fmt, _Args&&... __args) {
333# if _LIBCPP_HAS_UNICODE
334 if constexpr (__print::__use_unicode_execution_charset)
335 __print::__vprint_unicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
336 else
337 __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
338# else // _LIBCPP_HAS_UNICODE
339 __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
340# endif // _LIBCPP_HAS_UNICODE
341}
342
343template <class... _Args>
344_LIBCPP_HIDE_FROM_ABI void print(format_string<_Args...> __fmt, _Args&&... __args) {
345 std::print(stdout, __fmt, std::forward<_Args>(__args)...);
346}
347
348template <class... _Args>
349_LIBCPP_HIDE_FROM_ABI void println(FILE* __stream, format_string<_Args...> __fmt, _Args&&... __args) {
350# if _LIBCPP_HAS_UNICODE
351 // Note the wording in the Standard is inefficient. The output of
352 // std::format is a std::string which is then copied. This solution
353 // just appends a newline at the end of the output.
354 if constexpr (__print::__use_unicode_execution_charset)
355 __print::__vprint_unicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
356 else
357 __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
358# else // _LIBCPP_HAS_UNICODE
359 __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
360# endif // _LIBCPP_HAS_UNICODE
361}
362
363template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
364_LIBCPP_HIDE_FROM_ABI inline void println(FILE* __stream) {
365 std::print(__stream, fmt: "\n");
366}
367
368template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
369_LIBCPP_HIDE_FROM_ABI inline void println() {
370 println(stdout);
371}
372
373template <class... _Args>
374_LIBCPP_HIDE_FROM_ABI void println(format_string<_Args...> __fmt, _Args&&... __args) {
375 std::println(stdout, __fmt, std::forward<_Args>(__args)...);
376}
377
378# if _LIBCPP_HAS_UNICODE
379template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
380_LIBCPP_HIDE_FROM_ABI inline void vprint_unicode(FILE* __stream, string_view __fmt, format_args __args) {
381 __print::__vprint_unicode(__stream, __fmt, __args, write_nl: false);
382}
383
384template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
385_LIBCPP_HIDE_FROM_ABI inline void vprint_unicode(string_view __fmt, format_args __args) {
386 std::vprint_unicode(stdout, __fmt, __args);
387}
388
389# endif // _LIBCPP_HAS_UNICODE
390
391template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
392_LIBCPP_HIDE_FROM_ABI inline void vprint_nonunicode(FILE* __stream, string_view __fmt, format_args __args) {
393 __print::__vprint_nonunicode(__stream, __fmt, __args, write_nl: false);
394}
395
396template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
397_LIBCPP_HIDE_FROM_ABI inline void vprint_nonunicode(string_view __fmt, format_args __args) {
398 std::vprint_nonunicode(stdout, __fmt, __args);
399}
400
401# endif // _LIBCPP_STD_VER >= 23
402
403_LIBCPP_END_NAMESPACE_STD
404
405#endif // __cplusplus < 201103L && defined(_LIBCPP_USE_FROZEN_CXX03_HEADERS)
406
407#endif // _LIBCPP_PRINT
408