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