1============================ 2Libc++ 17.0.0 Release Notes 3============================ 4 5.. contents:: 6 :local: 7 :depth: 2 8 9Written by the `Libc++ Team <https://libcxx.llvm.org>`_ 10 11Introduction 12============ 13 14This document contains the release notes for the libc++ C++ Standard Library, 15part of the LLVM Compiler Infrastructure, release 17.0.0. Here we describe the 16status of libc++ in some detail, including major improvements from the previous 17release and new feature work. For the general LLVM release notes, see `the LLVM 18documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may 19be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_. 20 21For more information about libc++, please see the `Libc++ Web Site 22<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_. 23 24Note that if you are reading this file from a Git checkout or the 25main Libc++ web page, this document applies to the *next* release, not 26the current one. To see the release notes for a specific release, please 27see the `releases page <https://llvm.org/releases/>`_. 28 29What's New in Libc++ 17.0.0? 30============================ 31 32The main focus of the libc++ team has been to implement new C++20 and C++23 33features. Work on the next C++ version, C++26, has started. 34 35The C++20 ``format`` library is marked as stable. The library is not complete since 36the C++20 ``chrono`` library lacks supports for time zones and some clocks. 37 38The C++20 spaceship operator is almost complete. It misses ``long double`` and 39time zone support. 40 41There is an experimental implementation of the C++23 ``std`` module. See 42:ref:`ModulesInLibcxx` for more information. 43 44An experimental implementation of the C++20 ``stop_token`` is available. 45 46Work has started on the C++17 Parallel STL. This feature is experimental, see 47:ref:`pstl-status` for the current status. 48 49 50Implemented 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 71With the ``format`` library being marked as stable, the 72following 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 84Improvements 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 112Deprecations 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 172Upcoming Deprecations and Removals 173---------------------------------- 174 175LLVM 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 197API 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 204ABI 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 215Build 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. 235