contrib/llvm-project/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 _WIN32
  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 // _WIN32
  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 #  ifdef _WIN32
 202   return std::__is_windows_terminal(__stream);
 203 #  elif __has_include(<unistd.h>)
 204   return isatty(fileno(__stream));
 205 #  else
 206 #    error "Provide a way to determine whether a FILE* is a terminal"
 207 #  endif
 208 }
 209
 210 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 211 _LIBCPP_HIDE_FROM_ABI inline void
 212 __vprint_nonunicode(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl) {
 213   _LIBCPP_ASSERT_UNCATEGORIZED(__stream, "__stream is a valid pointer to an output C stream");
 214   string __str = std::vformat(__fmt, __args);
 215   if (__write_nl)
 216     __str.push_back('\n');
 217
 218   size_t __size = fwrite(__str.data(), 1, __str.size(), __stream);
 219   if (__size < __str.size()) {
 220     if (std::feof(__stream))
 221       std::__throw_system_error(EIO, "EOF while writing the formatted output");
 222     std::__throw_system_error(std::ferror(__stream), "failed to write formatted output");
 223   }
 224 }
 225
 226 #  ifndef _LIBCPP_HAS_NO_UNICODE
 227
 228 // Note these helper functions are mainly used to aid testing.
 229 // On POSIX systems and Windows the output is no longer considered a
 230 // terminal when the output is redirected. Typically during testing the
 231 // output is redirected to be able to capture it. This makes it hard to
 232 // test this code path.
 233 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 234 _LIBCPP_HIDE_FROM_ABI inline void
 235 __vprint_unicode_posix(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl, bool __is_terminal) {
 236   // TODO PRINT Should flush errors throw too?
 237   if (__is_terminal)
 238     std::fflush(__stream);
 239
 240   __print::__vprint_nonunicode(__stream, __fmt, __args, __write_nl);
 241 }
 242
 243 #    ifndef _LIBCPP_HAS_NO_WIDE_CHARACTERS
 244 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 245 _LIBCPP_HIDE_FROM_ABI inline void
 246 __vprint_unicode_windows(FILE* __stream, string_view __fmt, format_args __args, bool __write_nl, bool __is_terminal) {
 247   if (!__is_terminal)
 248     return __print::__vprint_nonunicode(__stream, __fmt, __args, __write_nl);
 249
 250   // TODO PRINT Should flush errors throw too?
 251   std::fflush(__stream);
 252
 253   string __str = std::vformat(__fmt, __args);
 254   // UTF-16 uses the same number or less code units than UTF-8.
 255   // However the size of the code unit is 16 bits instead of 8 bits.
 256   //
 257   // The buffer uses the worst-case estimate and should never resize.
 258   // However when the string is large this could lead to OOM. Using a
 259   // smaller size might work, but since the buffer uses a grow factor
 260   // the final size might be larger when the estimate is wrong.
 261   //
 262   // TODO PRINT profile and improve the speed of this code.
 263   __format::__retarget_buffer<wchar_t> __buffer{__str.size()};
 264   __unicode::__transcode(__str.begin(), __str.end(), __buffer.__make_output_iterator());
 265   if (__write_nl)
 266     __buffer.push_back(L'\n');
 267
 268   [[maybe_unused]] wstring_view __view = __buffer.__view();
 269
 270   // The macro _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION is used to change
 271   // the behavior in the test. This is not part of the public API.
 272 #      ifdef _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION
 273   _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION(__stream, __view);
 274 #      elif defined(_WIN32)
 275   std::__write_to_windows_console(__stream, __view);
 276 #      else
 277   std::__throw_runtime_error("No defintion of _LIBCPP_TESTING_PRINT_WRITE_TO_WINDOWS_CONSOLE_FUNCTION and "
 278                              "__write_to_windows_console is not available.");
 279 #      endif
 280 }
 281 #    endif // _LIBCPP_HAS_NO_WIDE_CHARACTERS
 282
 283 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 284 _LIBCPP_HIDE_FROM_ABI inline void
 285 __vprint_unicode([[maybe_unused]] FILE* __stream,
 286                  [[maybe_unused]] string_view __fmt,
 287                  [[maybe_unused]] format_args __args,
 288                  [[maybe_unused]] bool __write_nl) {
 289   _LIBCPP_ASSERT_UNCATEGORIZED(__stream, "__stream is a valid pointer to an output C stream");
 290
 291   // [print.fun]
 292   //   7 - Effects: If stream refers to a terminal capable of displaying
 293   //       Unicode, writes out to the terminal using the native Unicode
 294   //       API; if out contains invalid code units, the behavior is
 295   //       undefined and implementations are encouraged to diagnose it.
 296   //       Otherwise writes out to stream unchanged. If the native
 297   //       Unicode API is used, the function flushes stream before
 298   //       writing out.
 299   //   8 - Throws: Any exception thrown by the call to vformat
 300   //       ([format.err.report]). system_error if writing to the terminal
 301   //       or stream fails. May throw bad_alloc.
 302   //   9 - Recommended practice: If invoking the native Unicode API
 303   //       requires transcoding, implementations should substitute
 304   //       invalid code units with U+FFFD replacement character per the
 305   //       Unicode Standard, Chapter 3.9 U+FFFD Substitution in
 306   //       Conversion.
 307
 308   // On non-Windows platforms the Unicode API is the normal file I/O API
 309   // so there the call can be forwarded to the non_unicode API. On
 310   // Windows there is a different API. This API requires transcoding.
 311
 312 #    ifndef _WIN32
 313   __print::__vprint_unicode_posix(__stream, __fmt, __args, __write_nl, __print::__is_terminal(__stream));
 314 #    elif !defined(_LIBCPP_HAS_NO_WIDE_CHARACTERS)
 315   __print::__vprint_unicode_windows(__stream, __fmt, __args, __write_nl, __print::__is_terminal(__stream));
 316 #    else
 317 #      error "Windows builds with wchar_t disabled are not supported."
 318 #    endif
 319 }
 320
 321 #  endif // _LIBCPP_HAS_NO_UNICODE
 322
 323 } // namespace __print
 324
 325 template <class... _Args>
 326 _LIBCPP_HIDE_FROM_ABI void print(FILE* __stream, format_string<_Args...> __fmt, _Args&&... __args) {
 327 #  ifndef _LIBCPP_HAS_NO_UNICODE
 328   if constexpr (__print::__use_unicode)
 329     __print::__vprint_unicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
 330   else
 331     __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
 332 #  else  // _LIBCPP_HAS_NO_UNICODE
 333   __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), false);
 334 #  endif // _LIBCPP_HAS_NO_UNICODE
 335 }
 336
 337 template <class... _Args>
 338 _LIBCPP_HIDE_FROM_ABI void print(format_string<_Args...> __fmt, _Args&&... __args) {
 339   std::print(stdout, __fmt, std::forward<_Args>(__args)...);
 340 }
 341
 342 template <class... _Args>
 343 _LIBCPP_HIDE_FROM_ABI void println(FILE* __stream, format_string<_Args...> __fmt, _Args&&... __args) {
 344 #  ifndef _LIBCPP_HAS_NO_UNICODE
 345   // Note the wording in the Standard is inefficient. The output of
 346   // std::format is a std::string which is then copied. This solution
 347   // just appends a newline at the end of the output.
 348   if constexpr (__print::__use_unicode)
 349     __print::__vprint_unicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
 350   else
 351     __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
 352 #  else  // _LIBCPP_HAS_NO_UNICODE
 353   __print::__vprint_nonunicode(__stream, __fmt.get(), std::make_format_args(__args...), true);
 354 #  endif // _LIBCPP_HAS_NO_UNICODE
 355 }
 356
 357 template <class... _Args>
 358 _LIBCPP_HIDE_FROM_ABI void println(format_string<_Args...> __fmt, _Args&&... __args) {
 359   std::println(stdout, __fmt, std::forward<_Args>(__args)...);
 360 }
 361
 362 #  ifndef _LIBCPP_HAS_NO_UNICODE
 363 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 364 _LIBCPP_HIDE_FROM_ABI inline void vprint_unicode(FILE* __stream, string_view __fmt, format_args __args) {
 365   __print::__vprint_unicode(__stream, __fmt, __args, false);
 366 }
 367
 368 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 369 _LIBCPP_HIDE_FROM_ABI inline void vprint_unicode(string_view __fmt, format_args __args) {
 370   std::vprint_unicode(stdout, __fmt, __args);
 371 }
 372
 373 #  endif // _LIBCPP_HAS_NO_UNICODE
 374
 375 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 376 _LIBCPP_HIDE_FROM_ABI inline void vprint_nonunicode(FILE* __stream, string_view __fmt, format_args __args) {
 377   __print::__vprint_nonunicode(__stream, __fmt, __args, false);
 378 }
 379
 380 template <class = void> // TODO PRINT template or availability markup fires too eagerly (http://llvm.org/PR61563).
 381 _LIBCPP_HIDE_FROM_ABI inline void vprint_nonunicode(string_view __fmt, format_args __args) {
 382   std::vprint_nonunicode(stdout, __fmt, __args);
 383 }
 384
 385 #endif // _LIBCPP_STD_VER >= 23
 386
 387 _LIBCPP_END_NAMESPACE_STD
 388
 389 #endif // _LIBCPP_PRINT