1=========================================== 2Libc++ 18.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++ 18.0.0 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 18.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++ 18.0.0? 36============================== 37 38- A new debug mode has been added, replacing the legacy debug mode that was 39 removed in the LLVM 17 release. See ``libcxx/docs/Hardening.rst`` for more 40 details. 41 42Implemented Papers 43------------------ 44 45- P2497R0 - Testing for success or failure of ``<charconv>`` functions 46- P2697R1 - Interfacing ``bitset`` with ``string_view`` 47- P2443R1 - ``views::chunk_by`` 48- P2538R1 - ADL-proof ``std::projected`` 49- P2614R2 - Deprecate ``numeric_limits::has_denorm`` 50- P0053R7 - C++ Synchronized Buffered Ostream (in the experimental library) 51- P2467R1 - Support exclusive mode for fstreams 52- P0020R6 - Floating Point Atomic 53- P2918R2 - Runtime format strings II 54- P2871R3 - Remove Deprecated Unicode Conversion Facets from C++26 55- P2870R3 - Remove basic_string::reserve() 56- P2909R4 - Fix formatting of code units as integers (Dude, where’s my ``char``?) 57 58 59Improvements and New Features 60----------------------------- 61 62- ``std::ranges::count`` is now optimized for ``vector<bool>::iterator``, which 63 can lead up to 350x performance improvements. 64 65- ``std::for_each`` has been optimized for segmented iterators like ``std::deque::iterator`` in C++23 and 66 later, which can lead up to 40x performance improvements. 67 68- The library now provides several hardening modes under which common cases of library undefined behavior will be turned 69 into a reliable program termination. The ``fast`` hardening mode enables a set of security-critical checks with 70 minimal runtime overhead; the ``extensive`` hardening mode additionally enables relatively cheap checks that catch 71 common logic errors but aren't necessarily security-critical; and the ``debug`` hardening mode enables all available 72 checks, some of which might be very expensive. Vendors can configure which hardening mode is enabled by default with 73 the ``LIBCXX_HARDENING_MODE`` variable at CMake configuration time. Users can control which hardening mode is enabled 74 on a per translation unit basis using the ``_LIBCPP_HARDENING_MODE`` macro. See :ref:`the hardening documentation 75 <using-hardening-modes>` for more details. 76 77- The ``_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT`` macro has been added to make 78 the declarations in ``<codecvt>`` available. 79 80- The ``_LIBCPP_ENABLE_CXX26_REMOVED_STRING_RESERVE`` macro has been added to make 81 the function ``std::basic_string<...>::reserve()`` available. 82 83 84Deprecations and Removals 85------------------------- 86 87- Availability macros which will never trigger an error have been removed. This includes anything that has been 88 introduced before macOS 10.13, iOS 12, tvOS 12 and watchOS 4. This shouldn't affect anybody, since AppleClang 15 89 doesn't support any older OSes. If you are a vendor and make use of these macros, please inform the libc++ team so we 90 can re-introduce them and consider upstreaming support for your platform. 91 92- The non-conforming constructor ``std::future_error(std::error_code)`` has been removed. Please use the 93 ``std::future_error(std::future_errc)`` constructor provided in C++17 instead. 94 95- `P1957 <https://wg21.link/P1957>` has been implemented in Clang and libc++ removed a code path that led to 96 narrowing conversions in ``std::variant`` behaving in a non-standard way. This may change how some uses of 97 ``std::variant``'s constructor behave in user code. The ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT`` 98 macro is provided to restore the previous behavior, and it will be supported in the LLVM 18 release only. 99 In LLVM 19 and beyond, ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT`` will not be honored anymore. 100 101- The ``_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED`` macro is not honored anymore in LLVM 18. 102 Please see the updated documentation about the hardening modes in libc++ and in particular the 103 ``_LIBCPP_VERBOSE_ABORT`` macro for details. 104 105- The headers ``<experimental/deque>``, ``<experimental/forward_list>``, ``<experimental/list>``, 106 ``<experimental/map>``, ``<experimental/memory_resource>``, ``<experimental/regex>``, ``<experimental/set>``, 107 ``<experimental/string>``, ``<experimental/unordered_map>``, ``<experimental/unordered_set>``, 108 and ``<experimental/vector>`` have been removed in LLVM 18, as all their contents will have been 109 implemented in namespace ``std`` for at least two releases. 110 111Upcoming Deprecations and Removals 112---------------------------------- 113 114LLVM 19 115~~~~~~~ 116 117- The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable that was used to enable the safe mode will be deprecated and setting 118 it will trigger an error; use the ``LIBCXX_HARDENING_MODE`` variable with the value ``extensive`` instead. Similarly, 119 the ``_LIBCPP_ENABLE_ASSERTIONS`` macro will be deprecated (setting it to ``1`` still enables the extensive mode the 120 LLVM 19 release while also issuing a deprecation warning). See :ref:`the hardening documentation 121 <using-hardening-modes>` for more details. 122 123- The base template for ``std::char_traits`` has been marked as deprecated and will be removed in LLVM 19. If you 124 are using ``std::char_traits`` with types other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``, ``char32_t`` 125 or a custom character type for which you specialized ``std::char_traits``, your code will stop working when we 126 remove the base template. The Standard does not mandate that a base template is provided, and such a base template 127 is bound to be incorrect for some types, which could currently cause unexpected behavior while going undetected. 128 Note that the ``_LIBCPP_CHAR_TRAITS_REMOVE_BASE_SPECIALIZATION`` macro can be defined in LLVM 18 to eagerly remove 129 the specialization and prepare code bases for the unconditional removal in LLVM 19. 130 131- The ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT`` macro that changed the behavior for narrowing conversions 132 in ``std::variant`` will be removed in LLVM 19. 133 134LLVM 20 135~~~~~~~ 136 137- The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable and the ``_LIBCPP_ENABLE_ASSERTIONS`` macro that were used to enable 138 the safe mode will be removed. 139 140 141ABI Affecting Changes 142--------------------- 143 144- The symbol of a non-visible function part of ``std::system_error`` was removed. 145 This is not a breaking change as the private function ``__init`` was never referenced internally outside of the dylib. 146 147- This release of libc++ added missing visibility annotations on some types in the library. Users compiling with 148 ``-fvisbility=hidden`` may notice that additional type infos from libc++ are being exported from their ABI. This is 149 the correct behavior in almost all cases since exporting the RTTI is required for these types to work properly with 150 dynamic_cast, exceptions and other mechanisms across binaries. However, if you intend to use libc++ purely as an 151 internal implementation detail (i.e. you use libc++ as a static archive and never export libc++ symbols from your ABI) 152 and you notice changes to your exported symbols list, then this means that you were not properly preventing libc++ 153 symbols from being part of your ABI. 154 155- The name mangling for intantiations of ``std::projected`` has changed in order to implement P2538R1. This technically 156 results in an ABI break, however in practice we expect uses of ``std::projected`` in ABI-sensitive places to be 157 extremely rare. Any error resulting from this change should result in a link-time error. 158 159- Under the unstable ABI, the internal alignment requirements for heap allocations 160 inside ``std::string`` has decreased from 16 to 8. This saves memory since string requests fewer additional 161 bytes than it did previously. However, this also changes the return value of ``std::string::max_size`` 162 and can cause code compiled against older libc++ versions but linked at runtime to a new version 163 to throw a different exception when attempting allocations that are too large 164 (``std::bad_alloc`` vs ``std::length_error``). 165 166Build System Changes 167-------------------- 168 169- The ``LIBCXX_EXECUTOR`` CMake variable has been deprecated. If you are relying on this, the new replacement is 170 passing ``-Dexecutor=...`` to ``llvm-lit``. Alternatively, this flag can be made persistent in the generated test 171 configuration file by passing ``-DLIBCXX_TEST_PARAMS=executor=...``. This also applies to the ``LIBUWIND_EXECTOR`` 172 and ``LIBCXXABI_EXECUTOR`` CMake variables. LLVM 19 will completely remove support for the ``*_EXECUTOR`` variables. 173