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