1========================================= 2Libc++ 16.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++ 16 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 16.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++ 16.0.0? 36============================ 37 38The main focus of the libc++ team has been to implement new C++20 and C++23 39features. 40 41The C++20 format library has improved but it not yet considered stable. The 42main improvements are additional formatters for the chrono calendar types. Work 43on formatting ranges has started. 44 45The C++20 ranges library has been completed and is no longer experimental (with 46the exception of `ranges::join_view` which is still marked as experimental 47because it is about to undergo an ABI-breaking change in the Standard due to 48`D2770 <https://isocpp.org/files/papers/D2770R0.html>`_). Work on C++23 ranges 49has started. 50 51The C++20 spaceship operator has been added to more types, the work is still 52ongoing. 53 54`D139235 <https://reviews.llvm.org/D139235>`_ made ``copy`` and ``move`` 55algorithms and their variations (``copy_backward``, etc.) apply optimizations 56for trivial types more often. This has the potential to expose bugs in code 57using these algorithms that currently relies on undefined behavior (this 58includes indirect usage -- for example, these algorithms are used in the 59implementation of some standard containers). This change also made the 60algorithms check the given iterator types for conformance more strictly. 61 62Implemented Papers 63------------------ 64- P2499R0 - ``string_view`` range constructor should be ``explicit`` 65- P2417R2 - A more constexpr bitset 66- P2445R1 - ``std::forward_like`` 67- P2273R3 - Making ``std::unique_ptr`` constexpr 68- P0591R4 - Utility functions to implement uses-allocator construction 69- P2291R3 - Add Constexpr Modifiers to Functions ``to_chars`` and 70 ``from_chars`` for Integral Types in ``<charconv>`` Header 71- P0220R1 - Adopt Library Fundamentals V1 TS Components for C++17 72- P0482R6 - char8_t: A type for UTF-8 characters and strings 73- P2438R2 - ``std::string::substr() &&`` 74- P0600R1 - ``nodiscard`` in the library 75- P0339R6 - ``polymorphic_allocator<>`` as a vocabulary type 76- P1169R4 - ``static operator()`` 77- P0415R1 - ``constexpr`` for ``std::complex`` 78- P1208R6 - ``std::source_location`` 79- P0323R12 - ``std::expected`` 80- P1035R7 - Input Range Adaptors 81- P2325R3 - Views should not be required to be default constructible 82- P2446R2 - ``views::as_rvalue`` 83- P1020R1 - Smart pointer creation with default initialization 84- P2210R2 - Superior String Splitting 85- P2286R8 - Formatting Ranges 86 87Improvements and New Features 88----------------------------- 89- Declarations of ``std::c8rtomb()`` and ``std::mbrtoc8()`` from P0482R6 are 90 now provided when implementations in the global namespace are provided by 91 the C library. 92- Implemented ``<memory_resource>`` header from C++17 93- The ``ranges`` versions of ``copy``, ``move``, ``copy_backward`` and ``move_backward`` are now also optimized for 94 ``std::deque<>::iterator``, which can lead to up to 20x performance improvements on certain algorithms. 95- The ``std`` and ``ranges`` versions of ``copy``, ``move``, ``copy_backward`` and ``move_backward`` are now also 96 optimized for ``join_view::iterator``, which can lead to up to 20x performance improvements on certain combinations of 97 iterators and algorithms. 98 99Deprecations and Removals 100------------------------- 101- ``unary_function`` and ``binary_function`` are no longer provided in C++17 and newer Standard modes. 102 They can be re-enabled with ``_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION``. 103 104- Several incidental transitive includes have been removed from libc++. Those 105 includes are removed based on the language version used. Incidental transitive 106 inclusions of the following headers have been removed: 107 108 - C++11, C++14, C++17, and C++20: ``chrono`` 109 - C++2b: ``algorithm``, ``array``, ``atomic``, ``bit``, ``chrono``, 110 ``climits``, ``cmath``, ``compare``, ``concepts``, ``cstdarg``, ``cstddef``, 111 ``cstdint``, ``cstdlib``, ``cstring``, ``ctime``, ``exception``, 112 ``functional``, ``initializer_list``, ``iosfwd``, ``iterator``, ``limits``, 113 ``memory``, ``new``, ``numeric``, ``optional``, ``ratio``, ``stdexcept``, 114 ``string``, ``tuple``, ``type_traits``, ``typeinfo``, ``unordered_map``, 115 ``utility``, ``variant``, ``vector``. 116 117 Users can also remove all incidental transitive includes by defining 118 ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES`` regardless of the language version 119 in use. Note that in the future, libc++ reserves the right to remove 120 incidental transitive includes more aggressively, in particular regardless 121 of the language version in use. 122 123- The legacy testing system for libc++, libc++abi, and libunwind has been removed. 124 All known clients have been migrated to the new configuration system, but please 125 reach out to the libc++ developers if you find something missing in the new 126 configuration system. 127 128- The functions ``to_chars`` and ``from_chars`` for integral types are 129 available starting with C++17. Libc++ offered these functions in C++11 and 130 C++14 as an undocumented extension. This extension makes it hard to implement 131 the C++23 paper that makes these functions ``constexpr``, therefore the 132 extension has been removed. 133 134- The ``_LIBCPP_ENABLE_CXX03_FUNCTION`` macro that allowed re-enabling the now-deprecated C++03 implementation of 135 ``std::function`` has been removed. Users who need to use ``std::function`` should switch to C++11 and above. 136 137- The contents of ``<experimental/memory_resource>`` are now deprecated since libc++ ships ``<memory_resource>`` now. 138 Please migrate to ``<memory_resource>`` instead. Per libc++'s TS deprecation policy, 139 ``<experimental/memory_resource>`` will be removed in LLVM 18. 140 141- The ``_LIBCPP_DEBUG`` macro is not honored anymore, and it is an error to try to use it. Please migrate to 142 ``_LIBCPP_ENABLE_DEBUG_MODE`` instead. 143 144Upcoming Deprecations and Removals 145---------------------------------- 146- The base template for ``std::char_traits`` has been marked as deprecated and will be removed in LLVM 18. If 147 you are using ``std::char_traits`` with types other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``, 148 ``char32_t`` or a custom character type for which you specialized ``std::char_traits``, your code will stop 149 working when we remove the base template. The Standard does not mandate that a base template is provided, 150 and such a base template is bound to be incorrect for some types, which could currently cause unexpected 151 behavior while going undetected. 152 153- The ``_LIBCPP_AVAILABILITY_CUSTOM_VERBOSE_ABORT_PROVIDED`` macro will not be honored anymore in LLVM 18. 154 Please see the updated documentation about the safe libc++ mode and in particular the ``_LIBCPP_VERBOSE_ABORT`` 155 macro for details. 156 157API Changes 158----------- 159- The comparison operators on ``thread::id`` are now defined as free-standing 160 functions instead of as hidden friends, in conformance with the C++ standard. 161 Also see `issue 56187 <https://github.com/llvm/llvm-project/issues/56187>`_. 162 163- ``_LIBCPP_ENABLE_NODISCARD`` and ``_LIBCPP_DISABLE_NODISCARD_AFTER_CXX17`` are no longer respected. 164 Any standards-required ``[[nodiscard]]`` applications in C++20 are now always enabled. Any extended applications 165 are now enabled by default and can be disabled by defining ``_LIBCPP_DISABLE_NODISCARD_EXT``. 166 167- ``_LIBCPP_VERSION`` was previously defined to e.g. ``15001`` to represent LLVM 15.0.01, but this value had been 168 left undocumented. Starting with LLVM 16, ``_LIBCPP_VERSION`` will contain the version of LLVM represented as 169 ``XXYYZZ``. In other words, ``_LIBCPP_VERSION`` is gaining a digit. This should not be an issue for existing 170 code, since using e.g. ``_LIBCPP_VERSION > 15000`` will still give the right answer now that ``_LIBCPP_VERSION`` 171 is defined as e.g. ``160000`` (with one more digit). 172 173ABI Affecting Changes 174--------------------- 175- In freestanding mode, ``atomic<small enum class>`` does not contain a lock byte anymore if the platform 176 can implement lockfree atomics for that size. More specifically, in LLVM <= 11.0.1, an ``atomic<small enum class>`` 177 would not contain a lock byte. This was broken in LLVM >= 12.0.0, where it started including a lock byte despite 178 the platform supporting lockfree atomics for that size. Starting in LLVM 15.0.1, the ABI for these types has been 179 restored to what it used to be (no lock byte), which is the most efficient implementation. 180 181 This ABI break only affects users that compile with ``-ffreestanding``, and only for ``atomic<T>`` where ``T`` 182 is a non-builtin type that could be lockfree on the platform. See https://llvm.org/D133377 for more details. 183 184- When building libc++ against newlib/picolibc, the type of ``regex_type_traits::char_class_type`` was changed to 185 ``uint16_t`` since all values of ``ctype_base::mask`` are taken. This is technically an ABI break, but including 186 ``<regex> `` has triggered a ``static_assert`` failure since libc++ 14, so it is unlikely that this causes 187 problems for existing users. 188 189Build System Changes 190-------------------- 191- Support for ``libcxx``, ``libcxxabi`` and ``libunwind`` in ``LLVM_ENABLE_PROJECTS`` has officially 192 been removed. Instead, please build according to :ref:`these instructions <build instructions>`. 193