libcxx/docs/ReleaseNotes/21.rst - llvm-project - Git at Google

 ===========================================
 Libc++ 21.0.0 (In-Progress) Release Notes
 ===========================================

 .. contents::
    :local:
    :depth: 2

 Written by the `Libc++ Team <https://libcxx.llvm.org>`_

 .. warning::

    These are in-progress notes for the upcoming libc++ 21.0.0 release.
    Release notes for previous releases can be found on
    `the Download Page <https://releases.llvm.org/download.html>`_.

 Introduction
 ============

 This document contains the release notes for the libc++ C++ Standard Library,
 part of the LLVM Compiler Infrastructure, release 21.0.0. Here we describe the
 status of libc++ in some detail, including major improvements from the previous
 release and new feature work. For the general LLVM release notes, see `the LLVM
 documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
 be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.

 For more information about libc++, please see the `Libc++ Web Site
 <https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.

 Note that if you are reading this file from a Git checkout or the
 main Libc++ web page, this document applies to the *next* release, not
 the current one. To see the release notes for a specific release, please
 see the `releases page <https://llvm.org/releases/>`_.

 What's New in Libc++ 21.0.0?
 ==============================

 Implemented Papers
 ------------------

 - N4258: Cleaning-up noexcept in the Library (`Github <https://github.com/llvm/llvm-project/issues/99937>`__)
 - P0767R1: Deprecate POD (`Github <https://github.com/llvm/llvm-project/issues/104013>`__)
 - P1361R2: Integration of chrono with text formatting (`Github <https://github.com/llvm/llvm-project/issues/100014>`__)
 - P2255R2: A type trait to detect reference binding to temporary (implemented the type traits only) (`Github <https://github.com/llvm/llvm-project/issues/105180>`__)
 - P2372R3: Fixing locale handling in chrono formatters (`Github <https://github.com/llvm/llvm-project/issues/100043>`__)
 - P2562R1: ``constexpr`` Stable Sorting (`Github <https://github.com/llvm/llvm-project/issues/105360>`__)
 - P0472R3: Put std::monostate in <utility> (`Github <https://github.com/llvm/llvm-project/issues/127874>`__)
 - P1222R4: A Standard ``flat_set`` (`Github <https://github.com/llvm/llvm-project/issues/105193>`__)
 - P2897R7: ``aligned_accessor``: An mdspan accessor expressing pointer over-alignment (`Github <https://github.com/llvm/llvm-project/issues/118372>`__)
 - P3247R2: Deprecate the notion of trivial types (`Github <https://github.com/llvm/llvm-project/issues/118387>`__)
 - P3372R3: ``constexpr`` containers and adaptors (`Github <https://github.com/llvm/llvm-project/issues/127876>`__) (``forward_list``, ``list``, ``priority_queue``, ``flat_map``, and ``flat_set`` are implemented)
 - P2441R2: ``views::join_with`` (`Github <https://github.com/llvm/llvm-project/issues/105185>`__)
 - P2711R1: Making multi-param constructors of ``views`` ``explicit`` (`Github <https://github.com/llvm/llvm-project/issues/105252>`__)
 - P2770R0: Stashing stashing ``iterators`` for proper flattening (`Github <https://github.com/llvm/llvm-project/issues/105250>`__)
 - P2655R3: ``common_reference_t`` of ``reference_wrapper`` Should Be a Reference Type (`Github <https://github.com/llvm/llvm-project/issues/105260>`__)
 - P2944R3: Comparisons for ``reference_wrapper`` (`Github <https://github.com/llvm/llvm-project/issues/105424>`__)
 - P3379R0: Constrain ``std::expected equality`` operators (`Github <https://github.com/llvm/llvm-project/issues/118135>`__)

 Improvements and New Features
 -----------------------------

 - The ``std::ranges::{copy, copy_n, copy_backward, move, move_backward, rotate}`` algorithms have been optimized for
   ``std::vector<bool>::iterator``, resulting in a performance improvement of up to 2000x.

 - The ``std::ranges::equal`` algorithm has been optimized for ``std::vector<bool>::iterator``, resulting in a performance
   improvement of up to 188x.

 - The ``std::ranges::swap_ranges`` algorithm has been optimized for ``std::vector<bool>::iterator``, resulting in a
   performance improvement of up to 611x.

 - Updated formatting library to Unicode 16.0.0.

 - The ``num_put::do_put`` integral overloads have been optimized, resulting in a performance improvement of up to 2.4x.

 - The ``std::stable_sort`` algorithm uses radix sort for floating-point types now, which can improve the performance
   up to 10x, depending on type of sorted elements and the initial state of the sorted array.

 - The segmented iterator optimization for ``std::for_each`` has been backported to C++11. Previously it was only available
   in C++23 and later.

 - The ``std::for_each_n``, ``std::ranges::for_each`` and ``std::ranges::for_each_n`` algorithms have been optimized for
   segmented iterators, resulting in a performance improvement of up to 17.7x for ``std::deque<short>`` iterators, and up
   to 13.9x for ``std::join_view<vector<vector<short>>>`` iterators.

 - The ``bitset::to_string`` function has been optimized, resulting in a performance improvement of up to 8.3x for bitsets
   with uniformly distributed zeros and ones, and up to 13.5x and 16.1x for sparse and dense bitsets, respectively.

 - The ``flat_map::insert`` and ``flat_set::insert_range`` have been optimized, resulting in a performance improvement of up
   to 10x for inserting elements into a ``flat_map`` when the input range is a ``flat_map`` or a ``zip_view``.

 - ``ctype::tolower`` and ``ctype::toupper`` have been optimized, resulting in a 2x performance improvement.

 - As an experimental feature, Hardening now supports assertion semantics that allow customizing how a hardening
   assertion failure is handled. The four available semantics, modeled on C++26 Contracts, are ``ignore``, ``observe``,
   ``quick-enforce`` and ``enforce``. The ``observe`` semantic is intended to make it easier to adopt Hardening in
   production but should not be used outside of this scenario. Please refer to the :ref:`Hardening documentation
   <hardening>` for details.

 Deprecations and Removals
 -------------------------

 - ``std::is_pod`` and ``std::is_pod_v`` are deprecated in C++20 and later.

 - ``std::is_trivial`` and ``std::is_trivial_v`` are deprecated in C++26 and later.

 - The ``_LIBCPP_VERBOSE_ABORT_NOT_NOEXCEPT`` has been removed, making ``std::__libcpp_verbose_abort``
   unconditionally ``noexcept``.

 - libc++ no longer adds ``constexpr`` to ``std::hash<std::vector<bool, A>>::operator()``, as the ``constexpr`` addition
   since C++20 was an unintended extension.

 - The non-conforming extension ``packaged_task::result_type`` has been removed in LLVM 21.

 Potentially breaking changes
 ----------------------------

 - The implementation of ``num_put::do_put`` has been replaced to improve the performance, which can lead to different
   output when printing pointers.

 - User-defined specializations of ``std::common_reference`` are diagnosed now. To customize the common reference type, ``std::basic_common_reference`` should be specialized instead.

 - ``std::function`` used to have allocator support, which was removed from the Standard by `http://wg21.link/p0302r1`
   due to issues with its design and inconsistent support from implementations. Previously, libc++ would provide
   allocator-aware APIs in ``std::function`` in C++11 and C++14, but ignores the allocator argument in all places but
   one. Starting in this release, the allocator argument is always ignored.

 Announcements About Future Releases
 -----------------------------------

 LLVM 22
 ~~~~~~~

 - The status of the C++03 implementation will be frozen after the LLVM 21 release. This means that starting in LLVM 22,
   non-critical bug fixes may not be back-ported to C++03, including LWG issues. C++03 is a legacy platform, where most
   projects are no longer actively maintained. To reduce the amount of fixes required to keep such legacy projects
   compiling with up-to-date toolchains, libc++ will aim to freeze the status of the headers in C++03 mode to avoid
   unintended breaking changes. See https://discourse.llvm.org/t/rfc-freezing-c-03-headers-in-libc for more details.

   If you are using C++03 in your project, you should consider moving to a newer version of the Standard to get the most
   out of libc++.


 ABI Affecting Changes
 ---------------------

 - When using GCC, the ``std`` namespace is now annotated with ``[[gnu::visibility("default")]]``. This may cause more
   symbols to be exported from shared libraries when building with ``-fvisibility=hidden``. This also fixes RTTI
   comparison between shared libraries, since all RTTI has the correct visibility now. There is no behaviour change on
   Clang.


 Build System Changes
 --------------------

 - TODO
	===========================================
	Libc++ 21.0.0 (In-Progress) Release Notes
	===========================================

	.. contents::
	:local:
	:depth: 2

	Written by the `Libc++ Team <https://libcxx.llvm.org>`_

	.. warning::

	These are in-progress notes for the upcoming libc++ 21.0.0 release.
	Release notes for previous releases can be found on
	`the Download Page <https://releases.llvm.org/download.html>`_.

	Introduction
	============

	This document contains the release notes for the libc++ C++ Standard Library,
	part of the LLVM Compiler Infrastructure, release 21.0.0. Here we describe the
	status of libc++ in some detail, including major improvements from the previous
	release and new feature work. For the general LLVM release notes, see `the LLVM
	documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
	be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.

	For more information about libc++, please see the `Libc++ Web Site
	<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.

	Note that if you are reading this file from a Git checkout or the
	main Libc++ web page, this document applies to the next release, not
	the current one. To see the release notes for a specific release, please
	see the `releases page <https://llvm.org/releases/>`_.

	What's New in Libc++ 21.0.0?
	==============================

	Implemented Papers
	------------------

	- N4258: Cleaning-up noexcept in the Library (`Github <https://github.com/llvm/llvm-project/issues/99937>`__)
	- P0767R1: Deprecate POD (`Github <https://github.com/llvm/llvm-project/issues/104013>`__)
	- P1361R2: Integration of chrono with text formatting (`Github <https://github.com/llvm/llvm-project/issues/100014>`__)
	- P2255R2: A type trait to detect reference binding to temporary (implemented the type traits only) (`Github <https://github.com/llvm/llvm-project/issues/105180>`__)
	- P2372R3: Fixing locale handling in chrono formatters (`Github <https://github.com/llvm/llvm-project/issues/100043>`__)
	- P2562R1: ``constexpr`` Stable Sorting (`Github <https://github.com/llvm/llvm-project/issues/105360>`__)
	- P0472R3: Put std::monostate in <utility> (`Github <https://github.com/llvm/llvm-project/issues/127874>`__)
	- P1222R4: A Standard ``flat_set`` (`Github <https://github.com/llvm/llvm-project/issues/105193>`__)
	- P2897R7: ``aligned_accessor``: An mdspan accessor expressing pointer over-alignment (`Github <https://github.com/llvm/llvm-project/issues/118372>`__)
	- P3247R2: Deprecate the notion of trivial types (`Github <https://github.com/llvm/llvm-project/issues/118387>`__)
	- P3372R3: ``constexpr`` containers and adaptors (`Github <https://github.com/llvm/llvm-project/issues/127876>`__) (``forward_list``, ``list``, ``priority_queue``, ``flat_map``, and ``flat_set`` are implemented)
	- P2441R2: ``views::join_with`` (`Github <https://github.com/llvm/llvm-project/issues/105185>`__)
	- P2711R1: Making multi-param constructors of ``views`` ``explicit`` (`Github <https://github.com/llvm/llvm-project/issues/105252>`__)
	- P2770R0: Stashing stashing ``iterators`` for proper flattening (`Github <https://github.com/llvm/llvm-project/issues/105250>`__)
	- P2655R3: ``common_reference_t`` of ``reference_wrapper`` Should Be a Reference Type (`Github <https://github.com/llvm/llvm-project/issues/105260>`__)
	- P2944R3: Comparisons for ``reference_wrapper`` (`Github <https://github.com/llvm/llvm-project/issues/105424>`__)
	- P3379R0: Constrain ``std::expected equality`` operators (`Github <https://github.com/llvm/llvm-project/issues/118135>`__)

	Improvements and New Features
	-----------------------------

	- The ``std::ranges::{copy, copy_n, copy_backward, move, move_backward, rotate}`` algorithms have been optimized for
	``std::vector<bool>::iterator``, resulting in a performance improvement of up to 2000x.

	- The ``std::ranges::equal`` algorithm has been optimized for ``std::vector<bool>::iterator``, resulting in a performance
	improvement of up to 188x.

	- The ``std::ranges::swap_ranges`` algorithm has been optimized for ``std::vector<bool>::iterator``, resulting in a
	performance improvement of up to 611x.

	- Updated formatting library to Unicode 16.0.0.

	- The ``num_put::do_put`` integral overloads have been optimized, resulting in a performance improvement of up to 2.4x.

	- The ``std::stable_sort`` algorithm uses radix sort for floating-point types now, which can improve the performance
	up to 10x, depending on type of sorted elements and the initial state of the sorted array.

	- The segmented iterator optimization for ``std::for_each`` has been backported to C++11. Previously it was only available
	in C++23 and later.

	- The ``std::for_each_n``, ``std::ranges::for_each`` and ``std::ranges::for_each_n`` algorithms have been optimized for
	segmented iterators, resulting in a performance improvement of up to 17.7x for ``std::deque<short>`` iterators, and up
	to 13.9x for ``std::join_view<vector<vector<short>>>`` iterators.

	- The ``bitset::to_string`` function has been optimized, resulting in a performance improvement of up to 8.3x for bitsets
	with uniformly distributed zeros and ones, and up to 13.5x and 16.1x for sparse and dense bitsets, respectively.

	- The ``flat_map::insert`` and ``flat_set::insert_range`` have been optimized, resulting in a performance improvement of up
	to 10x for inserting elements into a ``flat_map`` when the input range is a ``flat_map`` or a ``zip_view``.

	- ``ctype::tolower`` and ``ctype::toupper`` have been optimized, resulting in a 2x performance improvement.

	- As an experimental feature, Hardening now supports assertion semantics that allow customizing how a hardening
	assertion failure is handled. The four available semantics, modeled on C++26 Contracts, are ``ignore``, ``observe``,
	``quick-enforce`` and ``enforce``. The ``observe`` semantic is intended to make it easier to adopt Hardening in
	production but should not be used outside of this scenario. Please refer to the :ref:`Hardening documentation
	<hardening>` for details.

	Deprecations and Removals
	-------------------------

	- ``std::is_pod`` and ``std::is_pod_v`` are deprecated in C++20 and later.

	- ``std::is_trivial`` and ``std::is_trivial_v`` are deprecated in C++26 and later.

	- The ``_LIBCPP_VERBOSE_ABORT_NOT_NOEXCEPT`` has been removed, making ``std::__libcpp_verbose_abort``
	unconditionally ``noexcept``.

	- libc++ no longer adds ``constexpr`` to ``std::hash<std::vector<bool, A>>::operator()``, as the ``constexpr`` addition
	since C++20 was an unintended extension.

	- The non-conforming extension ``packaged_task::result_type`` has been removed in LLVM 21.

	Potentially breaking changes
	----------------------------

	- The implementation of ``num_put::do_put`` has been replaced to improve the performance, which can lead to different
	output when printing pointers.

	- User-defined specializations of ``std::common_reference`` are diagnosed now. To customize the common reference type, ``std::basic_common_reference`` should be specialized instead.

	- ``std::function`` used to have allocator support, which was removed from the Standard by `http://wg21.link/p0302r1`
	due to issues with its design and inconsistent support from implementations. Previously, libc++ would provide
	allocator-aware APIs in ``std::function`` in C++11 and C++14, but ignores the allocator argument in all places but
	one. Starting in this release, the allocator argument is always ignored.

	Announcements About Future Releases
	-----------------------------------

	LLVM 22
	~~~~~~~

	- The status of the C++03 implementation will be frozen after the LLVM 21 release. This means that starting in LLVM 22,
	non-critical bug fixes may not be back-ported to C++03, including LWG issues. C++03 is a legacy platform, where most
	projects are no longer actively maintained. To reduce the amount of fixes required to keep such legacy projects
	compiling with up-to-date toolchains, libc++ will aim to freeze the status of the headers in C++03 mode to avoid
	unintended breaking changes. See https://discourse.llvm.org/t/rfc-freezing-c-03-headers-in-libc for more details.

	If you are using C++03 in your project, you should consider moving to a newer version of the Standard to get the most
	out of libc++.


	ABI Affecting Changes
	---------------------

	- When using GCC, the ``std`` namespace is now annotated with ``[[gnu::visibility("default")]]``. This may cause more
	symbols to be exported from shared libraries when building with ``-fvisibility=hidden``. This also fixes RTTI
	comparison between shared libraries, since all RTTI has the correct visibility now. There is no behaviour change on
	Clang.


	Build System Changes
	--------------------

	- TODO