libcxx/include/print

   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 /*
  14 namespace 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.
  83 namespace __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
  89 template <class _Tp>
  90 concept __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     ;
  96 template <class _Tp>
  97 concept __utf32_code_unit = same_as<_Tp, char32_t>;
  98 #    else // _LIBCPP_SHORT_WCHAR
  99 template <class _Tp>
 100 concept __utf16_code_unit = same_as<_Tp, char16_t>;
 101 template <class _Tp>
 102 concept __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.
 111 template <class _OutIt>
 112 _LIBCPP_HIDE_FROM_ABI constexpr void __encode(_OutIt&, char32_t) = delete;
 113
 114 template <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
 131 template <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
 140 template <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
 168 namespace __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
 187 inline 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
 191 inline constexpr bool __use_unicode_execution_charset = _MSVC_EXECUTION_CHARACTER_SET == 65001;
 192 #  else
 193 inline 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
 212 template <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.
 235 template <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
 246 template <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
 285 template <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
 327 template <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
 339 template <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
 344 template <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
 359 template <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
 365 template <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
 370 template <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
 377 template <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
 382 template <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