libcxx/docs/ReleaseNotes/17.rst

   1 ============================
   2 Libc++ 17.0.0  Release Notes
   3 ============================
   4
   5 .. contents::
   6    :local:
   7    :depth: 2
   8
   9 Written by the `Libc++ Team <https://libcxx.llvm.org>`_
  10
  11 Introduction
  12 ============
  13
  14 This document contains the release notes for the libc++ C++ Standard Library,
  15 part of the LLVM Compiler Infrastructure, release 17.0.0. Here we describe the
  16 status of libc++ in some detail, including major improvements from the previous
  17 release and new feature work. For the general LLVM release notes, see `the LLVM
  18 documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
  19 be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.
  20
  21 For more information about libc++, please see the `Libc++ Web Site
  22 <https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
  23
  24 Note that if you are reading this file from a Git checkout or the
  25 main Libc++ web page, this document applies to the *next* release, not
  26 the current one. To see the release notes for a specific release, please
  27 see the `releases page <https://llvm.org/releases/>`_.
  28
  29 What's New in Libc++ 17.0.0?
  30 ============================
  31
  32 The main focus of the libc++ team has been to implement new C++20 and C++23
  33 features. Work on the next C++ version, C++26, has started.
  34
  35 The C++20 ``format`` library is marked as stable. The library is not complete since
  36 the C++20 ``chrono`` library lacks supports for time zones and some clocks.
  37
  38 The C++20 spaceship operator is almost complete. It misses ``long double`` and
  39 time zone support.
  40
  41 There is an experimental implementation of the C++23 ``std`` module. See
  42 :ref:`ModulesInLibcxx` for more information.
  43
  44 An experimental implementation of the C++20 ``stop_token`` is available.
  45
  46 Work has started on the C++17 Parallel STL. This feature is experimental, see
  47 :ref:`pstl-status` for the current status.
  48
  49
  50 Implemented Papers
  51 ------------------
  52 - P1206R7 - ``ranges::to``: A function to convert any range to a container
  53 - P2520R0 - ``move_iterator<T*>`` should be a random access iterator
  54 - P1328R1 - ``constexpr type_info::operator==()``
  55 - P2693R1 - Formatting ``thread::id`` (the ``stacktrace`` is not done yet)
  56 - P2675R1 - ``format``'s width estimation is too approximate and not forward compatible
  57 - P2505R5 - Monadic operations for ``std::expected``
  58 - P2711R1 - Making Multi-Param Constructors Of views explicit (``join_with_view`` is not done yet)
  59 - P2572R1 - ``std::format`` fill character allowances
  60 - P2510R3 - Formatting pointers
  61 - P2136R3 - ``invoke_r``
  62 - P2494R2 - Relaxing range adaptors to allow for move only types
  63 - P2585R0 - Improving default container formatting
  64 - P0408R7 - Efficient Access to ``basic_stringbuf``'s Buffer
  65 - P2474R2 - ``views::repeat``
  66 - P0009R18 - ``mdspan`` (``layout_stride`` is not done yet)
  67 - P2093R14 - Formatted output (the ``ostream`` overload is not done yet)
  68 - P2539R4 - Should the output of ``std::print`` to a terminal be synchronized
  69   with the underlying stream? (the ``ostream`` overload is not done yet)
  70
  71 With the ``format`` library  being marked as stable, the
  72 following papers are now available by default without using
  73 ``-fexperimental-library``:
  74
  75 - P0645 - Text Formatting
  76 - P1652 - Printf corner cases in std::format
  77 - P1892 - Extended locale-specific presentation specifiers for std::format
  78 - P1868 - width: clarifying units of width and precision in std::format
  79 - P2216 - std::format improvements
  80 - P2418 - Add support for std::generator-like types to std::format
  81 - P2286R8 - Formatting Ranges
  82 - P2508R1 - Exposing std::basic-format-string
  83
  84 Improvements and New Features
  85 -----------------------------
  86 - ``std::equal``, ``std::ranges::equal``, ``std::find``, and
  87   ``std::ranges::find``  are now forwarding to ``std::memcmp`` for trivially
  88   equality comparable types, which can lead up to 40x performance improvements.
  89
  90 - The performance of ``dynamic_cast`` on its hot paths is greatly improved and is as efficient as the
  91   ``libsupc++`` implementation. Note that the performance improvements are shipped in ``libcxxabi``.
  92
  93 - `D122780 <https://reviews.llvm.org/D122780>`_ Improved the performance of ``std::sort`` and ``std::ranges::sort``
  94   by up to 50% for arithmetic types and by approximately 10% for other types.
  95
  96 - The ``<format>`` header is no longer considered experimental. Some
  97   ``std::formatter`` specializations are not yet available since the class used
  98   in the specialization has not been implemented in libc++. This prevents the
  99   feature-test macro to be set.
 100
 101 - Platforms that don't have support for a filesystem can now still take advantage of some parts of ``<filesystem>``.
 102   Anything that does not rely on having an actual filesystem available will now work, such as ``std::filesystem::path``,
 103   ``std::filesystem::perms`` and similar classes.
 104
 105 - ASan container annotations have been extended to cover all allocators in ``std::vector``.
 106
 107 - ASan annotations have been added to the ``std::deque`` container, to detect container overflows.
 108
 109 - On Windows, ``std::wcout``, ``wcin``, and ``wcerr`` now work correctly when the underlying
 110   stream has been configured in wide mode.
 111
 112 Deprecations and Removals
 113 -------------------------
 114
 115 - The legacy debug mode has been removed in this release. The ``LIBCXX_ENABLE_DEBUG_MODE`` CMake variable has been
 116   removed. For additional context, refer to the `Discourse post
 117   <https://discourse.llvm.org/t/rfc-removing-the-legacy-debug-mode-from-libc/71026>`_.
 118
 119 - The ``<experimental/coroutine>`` header has been removed in this release. The ``<coroutine>`` header
 120   has been shipping since LLVM 14, so the Coroutines TS implementation is being removed per our policy
 121   for removing TSes.
 122
 123 - Several incidental transitive includes have been removed from libc++. Those
 124   includes are removed based on the language version used. Incidental transitive
 125   inclusions of the following headers have been removed:
 126
 127   - C++23: ``atomic``, ``bit``, ``cstdint``, ``cstdlib``, ``cstring``, ``initializer_list``, ``limits``, ``new``,
 128            ``stdexcept``, ``system_error``, ``type_traits``, ``typeinfo``
 129
 130   - ``<algorithm>`` no longer includes ``<chrono>`` in any C++ version (it was previously included in C++17 and earlier).
 131
 132   - ``<string>`` no longer includes ``<vector>`` in any C++ version (it was previously included in C++20 and earlier).
 133
 134   - ``<string>``, ``<string_view>``, and ``<mutex>`` no longer include ``<functional>``
 135     in any C++ version (it was previously included in C++20 and earlier).
 136
 137 - ``<atomic>``, ``<barrier>``, ``<latch>``, ``<numeric>``, ``<semaphore>`` and ``<shared_mutex>`` no longer include ``<iosfwd>``
 138   (it was previously included in all Standard versions).
 139
 140 - ``<format>``, ``<chrono>`` and ``<thread>`` no longer transitively include ``<cstdlib>``.
 141
 142 - The headers ``<experimental/algorithm>`` and ``<experimental/functional>`` have been removed, since all the contents
 143   have been implemented in namespace ``std`` for at least two releases.
 144
 145 - The ``std`` clang module has been broken up into separate top level modules per public header.
 146
 147 - The formatter specialization ``template<size_t N> struct formatter<const charT[N], charT>``
 148   has been removed. Since libc++'s format library was marked experimental there
 149   is no backwards compatibility option. This specialization has been removed
 150   from the Standard since it was never used, the proper specialization to use
 151   instead is ``template<size_t N> struct formatter<charT[N], charT>``.
 152
 153 - Libc++ used to provide some C++11 tag type global variables in C++03 as an extension, which are removed in
 154   this release. Those variables were ``std::allocator_arg``, ``std::defer_lock``, ``std::try_to_lock``,
 155   ``std::adopt_lock``, and ``std::piecewise_construct``. Note that the types associated to those variables are
 156   still provided in C++03 as an extension (e.g. ``std::piecewise_construct_t``). Providing those variables in
 157   C++03 mode made it impossible to define them properly -- C++11 mandated that they be ``constexpr`` variables,
 158   which is impossible in C++03 mode. Furthermore, C++17 mandated that they be ``inline constexpr`` variables,
 159   which led to ODR violations when mixed with the C++03 definition. Cleaning this up is required for libc++ to
 160   make progress on support for C++20 modules.
 161
 162 - The ``_LIBCPP_ABI_OLD_LOGNORMAL_DISTRIBUTION`` macro has been removed.
 163
 164 - The classes ``strstreambuf`` , ``istrstream``, ``ostrstream``, and ``strstream`` have been deprecated.
 165   They have been deprecated in the Standard since C++98, but were never marked as deprecated in libc++.
 166
 167 - LWG3631 ``basic_format_arg(T&&) should use remove_cvref_t<T> throughout`` removed
 168   support for ``volatile`` qualified formatters.
 169
 170 - The unmaintained Solaris support has been removed.
 171
 172 Upcoming Deprecations and Removals
 173 ----------------------------------
 174
 175 LLVM 18
 176 ~~~~~~~
 177
 178 - The base template for ``std::char_traits`` has been marked as deprecated and
 179   will be removed in LLVM 18. If you are using ``std::char_traits`` with types
 180   other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``, ``char32_t`` or
 181   a custom character type for which you specialized ``std::char_traits``, your code
 182   will stop working when we remove the base template. The Standard does not
 183   mandate that a base template is provided, and such a base template is bound
 184   to be incorrect for some types, which could currently cause unexpected
 185   behavior while going undetected.
 186
 187 - The ``_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED`` macro will not be honored anymore in LLVM 18.
 188   Please see the updated documentation about the safe libc++ mode and in particular the ``_LIBCPP_VERBOSE_ABORT``
 189   macro for details.
 190
 191 - The headers ``<experimental/deque>``, ``<experimental/forward_list>``, ``<experimental/list>``,
 192   ``<experimental/map>``, ``<experimental/memory_resource>``, ``<experimental/regex>``, ``<experimental/set>``,
 193   ``<experimental/string>``, ``<experimental/unordered_map>``, ``<experimental/unordered_set>``,
 194   and ``<experimental/vector>`` will be removed in LLVM 18, as all their contents will have been implemented in
 195   namespace ``std`` for at least two releases.
 196
 197 API Changes
 198 -----------
 199 - Added ``__asan_annotate_container_with_allocator``, which is a
 200   customization point to allow users to disable Address Sanitizer container annotations
 201   for specific allocators. See :ref:`turning-off-asan` for more
 202   information.
 203
 204 ABI Affecting Changes
 205 ---------------------
 206
 207 - Symbols for ``std::allocator_arg``, ``std::defer_lock``, ``std::try_to_lock``, ``std::adopt_lock``, and
 208   ``std::piecewise_construct`` have been removed from the built library. Under most circumstances, user code
 209   should not have been relying on those symbols anyway since those are empty classes and the compiler does
 210   not generate an undefined reference unless the address of the object is taken. However, this is an ABI break
 211   if the address of one of these objects has been taken in code compiled as C++03, since in those cases the
 212   objects were marked as defined in the shared library. In other Standard modes, this should never be a problem
 213   since those objects were defined in the headers as ``constexpr``.
 214
 215 Build System Changes
 216 --------------------
 217
 218 - Building libc++ and libc++abi for Apple platforms now requires targeting macOS 10.13 and later.
 219   This is relevant for vendors building the libc++ shared library and for folks statically linking
 220   libc++ into an application that has back-deployment requirements on Apple platforms.
 221
 222 - ``LIBCXX_ENABLE_FILESYSTEM`` now represents whether a filesystem is supported on the platform instead
 223   of representing merely whether ``<filesystem>`` should be provided. This means that vendors building
 224   with ``LIBCXX_ENABLE_FILESYSTEM=OFF`` will now also get ``<fstream>`` excluded from their configuration
 225   of the library.
 226
 227 - ``LIBCXX_ENABLE_FSTREAM`` is not supported anymore, please use ``LIBCXX_ENABLE_FILESYSTEM=OFF`` if your
 228   platform does not have support for a filesystem.
 229
 230 - The lit test parameter ``enable_modules`` changed from a Boolean to an enum. The changes are
 231
 232   - ``False`` became ``none``. This option does not test with modules enabled.
 233   - ``True`` became ``clang``. This option tests using Clang modules.
 234   - ``std`` is a new optional and tests with the experimental C++23 ``std`` module.