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

 ===========================================
 Libc++ 19.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++ 19.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 19.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++ 19.0.0?
 ==============================

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

 - P2637R3 - Member ``visit``
 - P2652R2 - Disallow User Specialization of ``allocator_traits``
 - P2819R2 - Add ``tuple`` protocol to ``complex``
 - P2495R3 - Interfacing ``stringstream``\s with ``string_view``
 - P2867R2 - Remove Deprecated ``strstream``\s From C++26
 - P2872R3 - Remove ``wstring_convert`` From C++26
 - P3142R0 - Printing Blank Lines with ``println`` (as DR against C++23)
 - P2944R3 - Comparisons for ``reference_wrapper`` (comparison operators for ``reference_wrapper`` only)
 - P2302R4 - ``std::ranges::contains``
 - P1659R3 - ``std::ranges::starts_with`` and ``std::ranges::ends_with``
 - P3029R1 - Better ``mdspan``'s CTAD
 - P2387R3 - Pipe support for user-defined range adaptors
 - P2713R1 - Escaping improvements in ``std::format``
 - P2231R1 - Missing ``constexpr`` in ``std::optional`` and ``std::variant``
 - P0019R8 - ``std::atomic_ref``

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

 - The performance of growing ``std::vector`` has been improved for trivially relocatable types.
 - A lot of types are considered trivially relocatable now, including ``vector`` and ``string``.
 - The performance of ``ranges::fill`` and ``ranges::fill_n`` has been improved for ``vector<bool>::iterator``\s,
   resulting in a performance increase of up to 1400x.
 - The ``std::mismatch`` algorithm has been optimized for integral types, which can lead up to 40x performance
   improvements.

 - The ``std::ranges::minmax`` algorithm has been optimized for integral types, resulting in a performance increase of
   up to 100x.

 - The ``_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM`` macro has been added to make the declarations in ``<strstream>`` available.

 - The ``_LIBCPP_ENABLE_CXX26_REMOVED_WSTRING_CONVERT`` macro has been added to make the declarations in ``<locale>``
   available.

 - The formatting library is updated to Unicode 15.1.0.

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

 - The C++20 synchronization library (``<barrier>``, ``<latch>``, ``atomic::wait``, etc.) has been deprecated
   in language modes prior to C++20. If you are using these features prior to C++20, please update to ``-std=c++20``.
   In LLVM 20, the C++20 synchronization library will be removed entirely in language modes prior to C++20.

 - ``_LIBCPP_DISABLE_NODISCARD_EXT`` has been removed. ``[[nodiscard]]`` applications are now unconditional.
   This decision is based on LEWGs discussion on `P3122 <https://wg21.link/P3122>` and `P3162 <https://wg21.link/P3162>`
   to not use ``[[nodiscard]]`` in the standard.

 - TODO: The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable that was used to enable the safe mode has been deprecated and setting
   it triggers an error; use the ``LIBCXX_HARDENING_MODE`` CMake variable with the value ``extensive`` instead. Similarly,
   the ``_LIBCPP_ENABLE_ASSERTIONS`` macro has been deprecated (setting it to ``1`` still enables the extensive mode in
   the LLVM 19 release while also issuing a deprecation warning). See :ref:`the hardening documentation
   <using-hardening-modes>` for more details.

 - The base template for ``std::char_traits`` has been removed in LLVM 19. If you are using ``std::char_traits`` with
   types other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``, ``char32_t`` or a custom character type for which you
   specialized ``std::char_traits``, your code will stop working. The Standard does not mandate that a base template is
   provided, and such a base template is bound to be incorrect for some types, which could currently cause unexpected behavior
   while going undetected.

 - The ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT`` macro that changed the behavior for narrowing conversions
   in ``std::variant`` has been removed in LLVM 19.

 - The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS`` and ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_VOID_SPECIALIZATION``
   macros have been removed in LLVM 19.

 - The ``_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES`` and ``_LIBCPP_ENABLE_CXX20_REMOVED_FEATURES`` macros have
   been removed in LLVM 19. C++17 and C++20 removed features can still be re-enabled individually.

 - The ``_LIBCPP_INLINE_VISIBILITY`` and ``_VSTD`` macros have been removed in LLVM 19.

 - The ``_LIBCPP_ATOMIC_ONLY_USE_BUILTINS`` configuration option has been removed in LLVM 19. This should not affect
   many users, except perhaps users using the library with ``-ffreestanding`` with a toolchain where compiler-rt or
   libatomic is not available. If you are one such user, please reach out to the libc++ developers so we can collaborate
   on a path for supporting atomics properly on freestanding platforms.

 - LWG3430 disallow implicit conversion of the source arguments to ``std::filesystem::path`` when
   constructing ``std::basic_*fstream``. This effectively removes the possibility to directly construct
   a ``std::basic_*fstream`` from a ``std::basic_string_view``, a input-iterator or a C-string, instead
   you can construct a temporary ``std::basic_string``. This change has been applied to C++17 and later.

 - The ``_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS`` macro has been removed and is not honored anymore. Additional
   warnings provided by libc++ as a matter of QoI will now be provided unconditionally.

 - libc++ no longer supports ``std::allocator<const T>`` and containers of ``const``-qualified element type, such
   as ``std::vector<const T>`` and ``std::list<const T>``. This used to be supported as an undocumented extension.
   If you were using ``std::vector<const T>``, replace it with ``std::vector<T>`` instead. The
   ``_LIBCPP_ENABLE_REMOVED_ALLOCATOR_CONST`` macro can be defined to temporarily re-enable this extension as
   folks transition their code. This macro will be honored for one released and ignored starting in LLVM 20.
   To assist with the clean-up process, consider running your code through Clang Tidy, with
   `std-allocator-const <https://clang.llvm.org/extra/clang-tidy/checks/portability/std-allocator-const.html>`
   enabled.


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

 LLVM 20
 ~~~~~~~

 - The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable and the ``_LIBCPP_ENABLE_ASSERTIONS`` macro that were used to enable
   the safe mode will be removed in LLVM 20.

 LLVM 21
 ~~~~~~~
 TODO


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

 - The optional POSIX macro ``ENODATA`` has been deprecated in C++ and POSIX 2017. The
   ``random_device`` could throw a ``system_error`` with this value. It now
   throws ``ENOMSG``.


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

 - The ``LIBCXX_EXECUTOR`` and ``LIBCXXABI_EXECUTOR`` CMake variables have been removed. Please
   set ``LIBCXX_TEST_PARAMS`` to ``executor=<...>`` instead.

 - The Cmake variable ``LIBCXX_ENABLE_CLANG_TIDY`` has been removed. The build system has been changed
   to automatically detect the presence of ``clang-tidy`` and the required ``Clang`` libraries.

 - The CMake options ``LIBCXX_INSTALL_MODULES`` now defaults to ``ON``.
	===========================================
	Libc++ 19.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++ 19.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 19.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++ 19.0.0?
	==============================

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

	- P2637R3 - Member ``visit``
	- P2652R2 - Disallow User Specialization of ``allocator_traits``
	- P2819R2 - Add ``tuple`` protocol to ``complex``
	- P2495R3 - Interfacing ``stringstream``\s with ``string_view``
	- P2867R2 - Remove Deprecated ``strstream``\s From C++26
	- P2872R3 - Remove ``wstring_convert`` From C++26
	- P3142R0 - Printing Blank Lines with ``println`` (as DR against C++23)
	- P2944R3 - Comparisons for ``reference_wrapper`` (comparison operators for ``reference_wrapper`` only)
	- P2302R4 - ``std::ranges::contains``
	- P1659R3 - ``std::ranges::starts_with`` and ``std::ranges::ends_with``
	- P3029R1 - Better ``mdspan``'s CTAD
	- P2387R3 - Pipe support for user-defined range adaptors
	- P2713R1 - Escaping improvements in ``std::format``
	- P2231R1 - Missing ``constexpr`` in ``std::optional`` and ``std::variant``
	- P0019R8 - ``std::atomic_ref``

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

	- The performance of growing ``std::vector`` has been improved for trivially relocatable types.
	- A lot of types are considered trivially relocatable now, including ``vector`` and ``string``.
	- The performance of ``ranges::fill`` and ``ranges::fill_n`` has been improved for ``vector<bool>::iterator``\s,
	resulting in a performance increase of up to 1400x.
	- The ``std::mismatch`` algorithm has been optimized for integral types, which can lead up to 40x performance
	improvements.

	- The ``std::ranges::minmax`` algorithm has been optimized for integral types, resulting in a performance increase of
	up to 100x.

	- The ``_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM`` macro has been added to make the declarations in ``<strstream>`` available.

	- The ``_LIBCPP_ENABLE_CXX26_REMOVED_WSTRING_CONVERT`` macro has been added to make the declarations in ``<locale>``
	available.

	- The formatting library is updated to Unicode 15.1.0.

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

	- The C++20 synchronization library (``<barrier>``, ``<latch>``, ``atomic::wait``, etc.) has been deprecated
	in language modes prior to C++20. If you are using these features prior to C++20, please update to ``-std=c++20``.
	In LLVM 20, the C++20 synchronization library will be removed entirely in language modes prior to C++20.

	- ``_LIBCPP_DISABLE_NODISCARD_EXT`` has been removed. ``[[nodiscard]]`` applications are now unconditional.
	This decision is based on LEWGs discussion on `P3122 <https://wg21.link/P3122>` and `P3162 <https://wg21.link/P3162>`
	to not use ``[[nodiscard]]`` in the standard.

	- TODO: The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable that was used to enable the safe mode has been deprecated and setting
	it triggers an error; use the ``LIBCXX_HARDENING_MODE`` CMake variable with the value ``extensive`` instead. Similarly,
	the ``_LIBCPP_ENABLE_ASSERTIONS`` macro has been deprecated (setting it to ``1`` still enables the extensive mode in
	the LLVM 19 release while also issuing a deprecation warning). See :ref:`the hardening documentation
	<using-hardening-modes>` for more details.

	- The base template for ``std::char_traits`` has been removed in LLVM 19. If you are using ``std::char_traits`` with
	types other than ``char``, ``wchar_t``, ``char8_t``, ``char16_t``, ``char32_t`` or a custom character type for which you
	specialized ``std::char_traits``, your code will stop working. The Standard does not mandate that a base template is
	provided, and such a base template is bound to be incorrect for some types, which could currently cause unexpected behavior
	while going undetected.

	- The ``_LIBCPP_ENABLE_NARROWING_CONVERSIONS_IN_VARIANT`` macro that changed the behavior for narrowing conversions
	in ``std::variant`` has been removed in LLVM 19.

	- The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS`` and ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_VOID_SPECIALIZATION``
	macros have been removed in LLVM 19.

	- The ``_LIBCPP_ENABLE_CXX17_REMOVED_FEATURES`` and ``_LIBCPP_ENABLE_CXX20_REMOVED_FEATURES`` macros have
	been removed in LLVM 19. C++17 and C++20 removed features can still be re-enabled individually.

	- The ``_LIBCPP_INLINE_VISIBILITY`` and ``_VSTD`` macros have been removed in LLVM 19.

	- The ``_LIBCPP_ATOMIC_ONLY_USE_BUILTINS`` configuration option has been removed in LLVM 19. This should not affect
	many users, except perhaps users using the library with ``-ffreestanding`` with a toolchain where compiler-rt or
	libatomic is not available. If you are one such user, please reach out to the libc++ developers so we can collaborate
	on a path for supporting atomics properly on freestanding platforms.

	- LWG3430 disallow implicit conversion of the source arguments to ``std::filesystem::path`` when
	constructing ``std::basic_*fstream``. This effectively removes the possibility to directly construct
	a ``std::basic_*fstream`` from a ``std::basic_string_view``, a input-iterator or a C-string, instead
	you can construct a temporary ``std::basic_string``. This change has been applied to C++17 and later.

	- The ``_LIBCPP_DISABLE_ADDITIONAL_DIAGNOSTICS`` macro has been removed and is not honored anymore. Additional
	warnings provided by libc++ as a matter of QoI will now be provided unconditionally.

	- libc++ no longer supports ``std::allocator<const T>`` and containers of ``const``-qualified element type, such
	as ``std::vector<const T>`` and ``std::list<const T>``. This used to be supported as an undocumented extension.
	If you were using ``std::vector<const T>``, replace it with ``std::vector<T>`` instead. The
	``_LIBCPP_ENABLE_REMOVED_ALLOCATOR_CONST`` macro can be defined to temporarily re-enable this extension as
	folks transition their code. This macro will be honored for one released and ignored starting in LLVM 20.
	To assist with the clean-up process, consider running your code through Clang Tidy, with
	`std-allocator-const <https://clang.llvm.org/extra/clang-tidy/checks/portability/std-allocator-const.html>`
	enabled.


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

	LLVM 20
	~~~~~~~

	- The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable and the ``_LIBCPP_ENABLE_ASSERTIONS`` macro that were used to enable
	the safe mode will be removed in LLVM 20.

	LLVM 21
	~~~~~~~
	TODO


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

	- The optional POSIX macro ``ENODATA`` has been deprecated in C++ and POSIX 2017. The
	``random_device`` could throw a ``system_error`` with this value. It now
	throws ``ENOMSG``.


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

	- The ``LIBCXX_EXECUTOR`` and ``LIBCXXABI_EXECUTOR`` CMake variables have been removed. Please
	set ``LIBCXX_TEST_PARAMS`` to ``executor=<...>`` instead.

	- The Cmake variable ``LIBCXX_ENABLE_CLANG_TIDY`` has been removed. The build system has been changed
	to automatically detect the presence of ``clang-tidy`` and the required ``Clang`` libraries.

	- The CMake options ``LIBCXX_INSTALL_MODULES`` now defaults to ``ON``.