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 <__concepts/same_as.h>
  36 #include <__config>
  37 #include <__format/buffer.h>
  38 #include <__format/format_arg_store.h>
  39 #include <__format/format_args.h>
  40 #include <__format/format_context.h>
  41 #include <__format/format_error.h>
  42 #include <__format/format_functions.h>
  43 #include <__format/unicode.h>
  44 #include <__system_error/system_error.h>
  45 #include <__utility/forward.h>
  46 #include <cerrno>
  47 #include <cstdio>
  48 #include <string>
  49 #include <string_view>
  50 #include <version>
  51
  52 #if __has_include(<unistd.h>)
  53 #  include <unistd.h>
  54 #endif
  55
  56 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
  57 #  pragma GCC system_header
  58 #endif
  59
  60 _LIBCPP_BEGIN_NAMESPACE_STD
  61
  62 #ifdef _LIBCPP_WIN32API
  63 _LIBCPP_EXPORTED_FROM_ABI bool __is_windows_terminal(FILE* __stream);
  64
  65 #  ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
  66 // A wrapper for WriteConsoleW which is used to write to the Windows
  67 // console. This function is in the dylib to avoid pulling in windows.h
  68 // in the library headers. The function itself uses some private parts
  69 // of the dylib too.
  70 //
  71 // The function does not depend on the language standard used. Guarding
  72 // it with C++23 would fail since the dylib is currently built using C++20.
  73 //
  74 // Note the function is only implemented on the Windows platform.
  75 _LIBCPP_EXPORTED_FROM_ABI void __write_to_windows_console(FILE* __stream, wstring_view __view);
  76 #  endif // _LIBCPP_HAS_NO_WIDE_CHARACTERS
  77
  78 #endif // _LIBCPP_WIN32API
  79
  80 #if _LIBCPP_STD_VER >= 23
  81
  82 #  ifndef _LIBCPP_HAS_NO_UNICODE
  83 // This is the code to transcode UTF-8 to UTF-16. This is used on
  84 // Windows for the native Unicode API. The code is modeled to make it
  85 // easier to extend to
  86 //
  87 //  P2728R0 Unicode in the Library, Part 1: UTF Transcoding
  88 //
  89 // This paper is still under heavy development so it makes no sense yet
  90 // to strictly follow the paper.
  91 namespace __unicode {
  92
  93 // The names of these concepts are modelled after P2728R0, but the
  94 // implementation is not. char16_t may contain 32-bits so depending on the
  95 // number of bits is an issue.
  96 #    ifdef _LIBCPP_SHORT_WCHAR
  97 template <class _Tp>
  98 concept __utf16_code_unit =
  99     same_as<_Tp, char16_t>
 100 #      ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 101     || same_as<_Tp, wchar_t>
 102 #      endif
 103     ;
 104 template <class _Tp>
 105 concept __utf32_code_unit = same_as<_Tp, char32_t>;
 106 #    else // _LIBCPP_SHORT_WCHAR
 107 template <class _Tp>
 108 concept __utf16_code_unit = same_as<_Tp, char16_t>;
 109 template <class _Tp>
 110 concept __utf32_code_unit =
 111     same_as<_Tp, char32_t>
 112 #      ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 113     || same_as<_Tp, wchar_t>
 114 #      endif
 115     ;
 116 #    endif // _LIBCPP_SHORT_WCHAR
 117
 118 // Pass by reference since an output_iterator may not be copyable.
 119 template <class _OutIt>
 120 _LIBCPP_HIDE_FROM_ABI constexpr void __encode(_OutIt&, char32_t) = delete;
 121
 122 template <class _OutIt>
 123   requires __utf16_code_unit<iter_value_t<_OutIt>>
 124 _LIBCPP_HIDE_FROM_ABI constexpr void __encode(_OutIt& __out_it, char32_t __value) {
 125   _LIBCPP_ASSERT_UNCATEGORIZED(__is_scalar_value(__value), "an invalid unicode scalar value results in invalid UTF-16");
 126
 127   if (__value < 0x10000) {
 128     *__out_it++ = __value;
 129     return;
 130   }
 131
 132   __value -= 0x10000;
 133   *__out_it++ = 0xd800 + (__value >> 10);
 134   *__out_it++ = 0xdc00 + (__value & 0x3FF);
 135 }
 136
 137 template <class _OutIt>
 138   requires __utf32_code_unit<iter_value_t<_OutIt>>
 139 _LIBCPP_HIDE_FROM_ABI constexpr void __encode(_OutIt& __out_it, char32_t __value) {
 140   _LIBCPP_ASSERT_UNCATEGORIZED(__is_scalar_value(__value), "an invalid unicode scalar value results in invalid UTF-32");
 141   *__out_it++ = __value;
 142 }
 143
 144 template <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_NO_UNICODE
 171
 172 namespace __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 #  ifdef _LIBCPP_HAS_NO_UNICODE
 191 inline constexpr bool __use_unicode = 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
 195 inline constexpr bool __use_unicode = _MSVC_EXECUTION_CHARACTER_SET == 65001;
 196 #  else
 197 inline constexpr bool __use_unicode = true;
 198 #  endif
 199
 200 _LIBCPP_HIDE_FROM_ABI inline bool __is_terminal(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 defined(_LIBCPP_WIN32API)
 206   return std::__is_windows_terminal(__stream);
 207 #  elif __has_include(<unistd.h>)
 208   return isatty(fileno(__stream));
 209 #  else
 210 #    error "Provide a way to determine whether a FILE* is a terminal"
 211 #  endif
 212 }
 213
 214 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 215 _LIBCPP_HIDE_FROM_ABI inline void
 216 __vprint_nonunicode(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl) {
 217   _LIBCPP_ASSERT_UNCATEGORIZED(__stream, "__stream is a valid pointer to an output C stream");
 218   string __str = std::vformat(__fmt, __args);
 219   if (__write_nl)
 220     __str.push_back('\n');
 221
 222   size_t __size = fwrite(__str.data(), 1, __str.size(), __stream);
 223   if (__size < __str.size()) {
 224     if (std::feof(__stream))
 225       std::__throw_system_error(EIO, "EOF while writing the formatted output");
 226     std::__throw_system_error(std::ferror(__stream), "failed to write formatted output");
 227   }
 228 }
 229
 230 #  ifndef _LIBCPP_HAS_NO_UNICODE
 231
 232 // Note these helper functions are mainly used to aid testing.
 233 // On POSIX systems and Windows the output is no longer considered a
 234 // terminal when the output is redirected. Typically during testing the
 235 // output is redirected to be able to capture it. This makes it hard to
 236 // test this code path.
 237 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 238 _LIBCPP_HIDE_FROM_ABI inline void
 239 __vprint_unicode_posix(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl, bool __is_terminal) {
 240   // TODO PRINT Should flush errors throw too?
 241   if (__is_terminal)
 242     std::fflush(__stream);
 243
 244   __print::__vprint_nonunicode(__stream, __fmt, __args, __write_nl);
 245 }
 246
 247 #    ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 248 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 249 _LIBCPP_HIDE_FROM_ABI inline void
 250 __vprint_unicode_windows(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl, bool __is_terminal) {
 251   if (!__is_terminal)
 252     return __print::__vprint_nonunicode(__stream, __fmt, __args, __write_nl);
 253
 254   // TODO PRINT Should flush errors throw too?
 255   std::fflush(__stream);
 256
 257   string __str = std::vformat(__fmt, __args);
 258   // UTF-16 uses the same number or less code units than UTF-8.
 259   // However the size of the code unit is 16 bits instead of 8 bits.
 260   //
 261   // The buffer uses the worst-case estimate and should never resize.
 262   // However when the string is large this could lead to OOM. Using a
 263   // smaller size might work, but since the buffer uses a grow factor
 264   // the final size might be larger when the estimate is wrong.
 265   //
 266   // TODO PRINT profile and improve the speed of this code.
 267   __format::__retarget_buffer<wchar_t> __buffer{__str.size()};
 268   __unicode::__transcode(__str.begin(), __str.end(), __buffer.__make_output_iterator());
 269   if (__write_nl)
 270     __buffer.push_back(L'\n');
 271
 272   [[maybe_unused]] wstring_view __view = __buffer.__view();
 273
 274   // The macro _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION is used to change
 275   // the behavior in the test. This is not part of the public API.
 276 #      ifdef _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION
 277   _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION(__stream, __view);
 278 #      elif defined(_LIBCPP_WIN32API)
 279   std::__write_to_windows_console(__stream, __view);
 280 #      else
 281   std::__throw_runtime_error("No defintion of _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION and "
 282                              "__write_to_windows_console is not available.");
 283 #      endif
 284 }
 285 #    endif // _LIBCPP_HAS_NO_WIDE_CHARACTERS
 286
 287 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 288 _LIBCPP_HIDE_FROM_ABI inline void
 289 __vprint_unicode([[maybe_unused]] FILE* __stream,
 290                  [[maybe_unused]] string_view __fmt,
 291                  [[maybe_unused]] format_args __args,
 292                  [[maybe_unused]] bool __write_nl) {
 293   _LIBCPP_ASSERT_UNCATEGORIZED(__stream, "__stream is a valid pointer to an output C stream");
 294
 295   // [print.fun]
 296   //   7 - Effects: If stream refers to a terminal capable of displaying
 297   //       Unicode, writes out to the terminal using the native Unicode
 298   //       API; if out contains invalid code units, the behavior is
 299   //       undefined and implementations are encouraged to diagnose it.
 300   //       Otherwise writes out to stream unchanged. If the native
 301   //       Unicode API is used, the function flushes stream before
 302   //       writing out.
 303   //   8 - Throws: Any exception thrown by the call to vformat
 304   //       ([format.err.report]). system_error if writing to the terminal
 305   //       or stream fails. May throw bad_alloc.
 306   //   9 - Recommended practice: If invoking the native Unicode API
 307   //       requires transcoding, implementations should substitute
 308   //       invalid code units with U+FFFD replacement character per the
 309   //       Unicode Standard, Chapter 3.9 U+FFFD Substitution in
 310   //       Conversion.
 311
 312   // On non-Windows platforms the Unicode API is the normal file I/O API
 313   // so there the call can be forwarded to the non_unicode API. On
 314   // Windows there is a different API. This API requires transcoding.
 315
 316 #    ifndef _LIBCPP_WIN32API
 317   __print::__vprint_unicode_posix(__stream, __fmt, __args, __write_nl, __print::__is_terminal(__stream));
 318 #    elif !defined(_LIBCPP_HAS_NO_WIDE_CHARACTERS)
 319   __print::__vprint_unicode_windows(__stream, __fmt, __args, __write_nl, __print::__is_terminal(__stream));
 320 #    else
 321 #      error "Windows builds with wchar_t disabled are not supported."
 322 #    endif
 323 }
 324
 325 #  endif // _LIBCPP_HAS_NO_UNICODE
 326
 327 } // namespace __print
 328
 329 template <class... _Args>
 330 _LIBCPP_HIDE_FROM_ABI void print(FILE* __stream, format_string<_Args...> __fmt, _Args&&... __args) {
 331 #  ifndef _LIBCPP_HAS_NO_UNICODE
 332   if constexpr (__print::__use_unicode)
 333     __print::__vprint_unicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
 334   else
 335     __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
 336 #  else  // _LIBCPP_HAS_NO_UNICODE
 337   __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
 338 #  endif // _LIBCPP_HAS_NO_UNICODE
 339 }
 340
 341 template <class... _Args>
 342 _LIBCPP_HIDE_FROM_ABI void print(format_string<_Args...> __fmt, _Args&&... __args) {
 343   std::print(stdout, __fmt, std::forward<_Args>(__args)...);
 344 }
 345
 346 template <class... _Args>
 347 _LIBCPP_HIDE_FROM_ABI void println(FILE* __stream, format_string<_Args...> __fmt, _Args&&... __args) {
 348 #  ifndef _LIBCPP_HAS_NO_UNICODE
 349   // Note the wording in the Standard is inefficient. The output of
 350   // std::format is a std::string which is then copied. This solution
 351   // just appends a newline at the end of the output.
 352   if constexpr (__print::__use_unicode)
 353     __print::__vprint_unicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
 354   else
 355     __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
 356 #  else  // _LIBCPP_HAS_NO_UNICODE
 357   __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
 358 #  endif // _LIBCPP_HAS_NO_UNICODE
 359 }
 360
 361 template <class... _Args>
 362 _LIBCPP_HIDE_FROM_ABI void println(format_string<_Args...> __fmt, _Args&&... __args) {
 363   std::println(stdout, __fmt, std::forward<_Args>(__args)...);
 364 }
 365
 366 #  ifndef _LIBCPP_HAS_NO_UNICODE
 367 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 368 _LIBCPP_HIDE_FROM_ABI inline void vprint_unicode(FILE* __stream, string_view __fmt, format_args __args) {
 369   __print::__vprint_unicode(__stream, __fmt, __args, false);
 370 }
 371
 372 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 373 _LIBCPP_HIDE_FROM_ABI inline void vprint_unicode(string_view __fmt, format_args __args) {
 374   std::vprint_unicode(stdout, __fmt, __args);
 375 }
 376
 377 #  endif // _LIBCPP_HAS_NO_UNICODE
 378
 379 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 380 _LIBCPP_HIDE_FROM_ABI inline void vprint_nonunicode(FILE* __stream, string_view __fmt, format_args __args) {
 381   __print::__vprint_nonunicode(__stream, __fmt, __args, false);
 382 }
 383
 384 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 385 _LIBCPP_HIDE_FROM_ABI inline void vprint_nonunicode(string_view __fmt, format_args __args) {
 386   std::vprint_nonunicode(stdout, __fmt, __args);
 387 }
 388
 389 #endif // _LIBCPP_STD_VER >= 23
 390
 391 _LIBCPP_END_NAMESPACE_STD
 392
 393 #endif // _LIBCPP_PRINT