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