1========================================= 2Libc++ 17.0.0 (In-Progress) Release Notes 3========================================= 4 5.. contents:: 6 :local: 7 :depth: 2 8 9Written by the `Libc++ Team <https://libcxx.llvm.org>`_ 10 11.. warning:: 12 13 These are in-progress notes for the upcoming libc++ 17 release. 14 Release notes for previous releases can be found on 15 `the Download Page <https://releases.llvm.org/download.html>`_. 16 17Introduction 18============ 19 20This document contains the release notes for the libc++ C++ Standard Library, 21part of the LLVM Compiler Infrastructure, release 17.0.0. Here we describe the 22status of libc++ in some detail, including major improvements from the previous 23release and new feature work. For the general LLVM release notes, see `the LLVM 24documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may 25be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_. 26 27For more information about libc++, please see the `Libc++ Web Site 28<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_. 29 30Note that if you are reading this file from a Git checkout or the 31main Libc++ web page, this document applies to the *next* release, not 32the current one. To see the release notes for a specific release, please 33see the `releases page <https://llvm.org/releases/>`_. 34 35What's New in Libc++ 17.0.0? 36============================ 37 38There is an experimental implementation of the C++23 ``std`` module. See 39:ref:`ModulesInLibcxx` for more information. 40 41Implemented Papers 42------------------ 43- P2520R0 - ``move_iterator<T*>`` should be a random access iterator 44- P1328R1 - ``constexpr type_info::operator==()`` 45- P1413R3 - Formatting ``thread::id`` (the ``stacktrace`` is not done yet) 46- P2675R1 - ``format``'s width estimation is too approximate and not forward compatible 47- P2505R5 - Monadic operations for ``std::expected`` 48- P2711R1 - Making Multi-Param Constructors Of views explicit (``join_with_view`` is not done yet) 49- P2572R1 - ``std::format`` fill character allowances 50 51Improvements and New Features 52----------------------------- 53- ``std::equal`` and ``std::ranges::equal`` are now forwarding to ``std::memcmp`` for integral types and pointers, 54 which can lead up to 40x performance improvements. 55 56- ``std::string_view`` now provides iterators that check for out-of-bounds accesses when the safe 57 libc++ mode is enabled. 58 59- The performance of ``dynamic_cast`` on its hot paths is greatly improved and is as efficient as the 60 ``libsupc++`` implementation. Note that the performance improvements are shipped in ``libcxxabi``. 61 62- `D122780 <https://reviews.llvm.org/D122780>`_ Improved the performance of ``std::sort`` and ``std::ranges::sort`` 63 by up to 50% for arithmetic types and by approximately 10% for other types. 64 65- The ``<format>`` header is no longer considered experimental. Some 66 ``std::formatter`` specializations are not yet available since the class used 67 in the specialization has not been implemented in libc++. This prevents the 68 feature-test macro to be set. 69 70- Platforms that don't have support for a filesystem can now still take advantage of some parts of ``<filesystem>``. 71 Anything that does not rely on having an actual filesystem available will now work, such as ``std::filesystem::path``, 72 ``std::filesystem::perms`` and similar classes. 73 74Deprecations and Removals 75------------------------- 76 77- The ``<experimental/coroutine>`` header has been removed in this release. The ``<coroutine>`` header 78 has been shipping since LLVM 14, so the Coroutines TS implementation is being removed per our policy 79 for removing TSes. 80 81- Several incidental transitive includes have been removed from libc++. Those 82 includes are removed based on the language version used. Incidental transitive 83 inclusions of the following headers have been removed: 84 85 - C++23: ``atomic``, ``bit``, ``cstdint``, ``cstdlib``, ``cstring``, ``initializer_list``, ``limits``, ``new``, 86 ``stdexcept``, ``system_error``, ``type_traits``, ``typeinfo`` 87 88- ``<algorithm>`` no longer includes ``<chrono>`` in any C++ version (it was previously included in C++17 and earlier). 89 90- ``<limits>`` no longer includes ``<type_traits>`` in any C++ version (it was previously included in C++20 and earlier). 91 92- ``<new>`` no longer includes ``<exception>`` or ``<type_traits>`` in any C++ version (they were previously included in C++20 and earlier). 93 94- ``<string>`` no longer includes ``<vector>`` in any C++ version (it was previously included in C++20 and earlier). 95 96- ``<string>``, ``<string_view>``, and ``<mutex>`` no longer include ``<functional>`` 97 in any C++ version (it was previously included in C++20 and earlier). 98 99- The headers ``<experimental/algorithm>`` and ``<experimental/functional>`` have been removed, since all the contents 100 have been implemented in namespace ``std`` for at least two releases. 101 102- The formatter specialization ``template<size_t N> struct formatter<const charT[N], charT>`` 103 has been removed. Since libc++'s format library was marked experimental there 104 is no backwards compatibility option. This specialization has been removed 105 from the Standard since it was never used, the proper specialization to use 106 instead is ``template<size_t N> struct formatter<charT[N], charT>``. 107 108- Libc++ used to provide some C++11 tag type global variables in C++03 as an extension, which are removed in 109 this release. Those variables were ``std::allocator_arg``, ``std::defer_lock``, ``std::try_to_lock``, 110 ``std::adopt_lock``, and ``std::piecewise_construct``. Note that the types associated to those variables are 111 still provided in C++03 as an extension (e.g. ``std::piecewise_construct_t``). Providing those variables in 112 C++03 mode made it impossible to define them properly -- C++11 mandated that they be ``constexpr`` variables, 113 which is impossible in C++03 mode. Furthermore, C++17 mandated that they be ``inline constexpr`` variables, 114 which led to ODR violations when mixed with the C++03 definition. Cleaning this up is required for libc++ to 115 make progress on support for C++20 modules. 116 117- The ``_LIBCPP_ABI_OLD_LOGNORMAL_DISTRIBUTION`` macro has been removed. 118 119- The classes ``strstreambuf`` , ``istrstream``, ``ostrstream``, and ``strstream`` have been deprecated. 120 They have been deprecated in the Standard since C++98, but were never marked as deprecated in libc++. 121 122- LWG3631 ``basic_format_arg(T&&) should use remove_cvref_t<T> throughout`` removed 123 support for ``volatile`` qualified formatters. 124 125Upcoming Deprecations and Removals 126---------------------------------- 127 128LLVM 18 129~~~~~~~ 130 131- The base template for ``std::char_traits`` has been marked as deprecated and 132 will be removed in LLVM 18. If you are using ``std::char_traits`` with types 133 other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``, ``char32_t`` or 134 a custom character type for which you specialized ``std::char_traits``, your code 135 will stop working when we remove the base template. The Standard does not 136 mandate that a base template is provided, and such a base template is bound 137 to be incorrect for some types, which could currently cause unexpected 138 behavior while going undetected. 139 140- The ``_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED`` macro will not be honored anymore in LLVM 18. 141 Please see the updated documentation about the safe libc++ mode and in particular the ``_LIBCPP_VERBOSE_ABORT`` 142 macro for details. 143 144- The headers ``<experimental/deque>``, ``<experimental/forward_list>``, ``<experimental/list>``, 145 ``<experimental/map>``, ``<experimental/memory_resource>``, ``<experimental/regex>``, ``<experimental/set>``, 146 ``<experimental/string>``, ``<experimental/unordered_map>``, ``<experimental/unordered_set>``, 147 and ``<experimental/vector>`` will be removed in LLVM 18, as all their contents will have been implemented in 148 namespace ``std`` for at least two releases. 149 150API Changes 151----------- 152 153ABI Affecting Changes 154--------------------- 155 156- Symbols for ``std::allocator_arg``, ``std::defer_lock``, ``std::try_to_lock``, ``std::adopt_lock``, and 157 ``std::piecewise_construct`` have been removed from the built library. Under most circumstances, user code 158 should not have been relying on those symbols anyway since those are empty classes and the compiler does 159 not generate an undefined reference unless the address of the object is taken. However, this is an ABI break 160 if the address of one of these objects has been taken in code compiled as C++03, since in those cases the 161 objects were marked as defined in the shared library. In other Standard modes, this should never be a problem 162 since those objects were defined in the headers as ``constexpr``. 163 164Build System Changes 165-------------------- 166 167- Building libc++ and libc++abi for Apple platforms now requires targeting macOS 10.13 and later. 168 This is relevant for vendors building the libc++ shared library and for folks statically linking 169 libc++ into an application that has back-deployment requirements on Apple platforms. 170 171- ``LIBCXX_ENABLE_FILESYSTEM`` now represents whether a filesystem is supported on the platform instead 172 of representing merely whether ``<filesystem>`` should be provided. This means that vendors building 173 with ``LIBCXX_ENABLE_FILESYSTEM=OFF`` will now also get ``<fstream>`` excluded from their configuration 174 of the library. 175 176- ``LIBCXX_ENABLE_FSTREAM`` is not supported anymore, please use ``LIBCXX_ENABLE_FILESYSTEM=OFF`` if your 177 platform does not have support for a filesystem. 178 179- The lit test parameter ``enable_modules`` changed from a Boolean to an enum. The changes are 180 181 - ``False`` became ``none``. This option does not test with modules enabled. 182 - ``True`` became ``clang``. This option tests using Clang modules. 183 - ``std`` is a new optional and tests with the experimental C++23 ``std`` module. 184