[libcxx-commits] [libcxx] [libc++][docs] Rewrite libc++ docs to md [2/2] (PR #234088)
Sachin 🗲 via libcxx-commits
libcxx-commits at lists.llvm.org
Tue Oct 20 22:54:09 PDT 2026
https://github.com/s4chinjha created https://github.com/llvm/llvm-project/pull/234088
Tracking issue: [#201242](https://github.com/llvm/llvm-project/issues/201242)
See the [migration guide](https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines) for more information.
this is the second part of migrating the remaining libc++ release notes docs from rst to md
the content conversion is provided by this pr, following the rename in the previous pr
This was prepared with rnk's fork of rst2myst and LLM-assisted cleanup.
I manually verified that the documentation renders as expected.
Depends on [#233994](https://github.com/llvm/llvm-project/pull/233994)
the first commit is from the base pr (rename), the second commit contains the content conversion, the third one fixes a link that the conversion turned into code
>From 376e8ea011d402fc559f8a3609b85f80a9f01b4a Mon Sep 17 00:00:00 2001
From: s4chinjha <s4chinjha at gmail.com>
Date: Wed, 21 Oct 2026 01:15:39 +0530
Subject: [PATCH 1/3] [libc++][docs] Rename remaining rst docs to md
---
libcxx/docs/Contributing/ReleaseProcedure.md | 4 ++--
.../{ReleaseNotesTemplate.rst => ReleaseNotesTemplate.md} | 0
libcxx/docs/{ReleaseNotes.rst => ReleaseNotes.md} | 0
libcxx/docs/ReleaseNotes/{20.rst => 20.md} | 0
libcxx/docs/ReleaseNotes/{21.rst => 21.md} | 0
libcxx/docs/ReleaseNotes/{22.rst => 22.md} | 0
libcxx/docs/ReleaseNotes/{23.rst => 23.md} | 0
libcxx/docs/ReleaseNotes/{24.rst => 24.md} | 0
8 files changed, 2 insertions(+), 2 deletions(-)
rename libcxx/docs/Helpers/{ReleaseNotesTemplate.rst => ReleaseNotesTemplate.md} (100%)
rename libcxx/docs/{ReleaseNotes.rst => ReleaseNotes.md} (100%)
rename libcxx/docs/ReleaseNotes/{20.rst => 20.md} (100%)
rename libcxx/docs/ReleaseNotes/{21.rst => 21.md} (100%)
rename libcxx/docs/ReleaseNotes/{22.rst => 22.md} (100%)
rename libcxx/docs/ReleaseNotes/{23.rst => 23.md} (100%)
rename libcxx/docs/ReleaseNotes/{24.rst => 24.md} (100%)
diff --git a/libcxx/docs/Contributing/ReleaseProcedure.md b/libcxx/docs/Contributing/ReleaseProcedure.md
index c284fe407cabcb..df0023d52cd73e 100644
--- a/libcxx/docs/Contributing/ReleaseProcedure.md
+++ b/libcxx/docs/Contributing/ReleaseProcedure.md
@@ -11,7 +11,7 @@ This page describes the libc++ procedure for that release.
It should be finished before the Release managers start branching the new
release:
-- Make sure `libcxx/docs/ReleaseNotes/<VERSION>.rst` is up to date. Typically
+- Make sure `libcxx/docs/ReleaseNotes/<VERSION>.md` is up to date. Typically
this file is updated when contributing patches. Still there might be some
information added regarding the general improvements of larger projects.
@@ -41,7 +41,7 @@ After branching for an LLVM release:
3. Update `_LIBCPPABI_VERSION` in `libcxxabi/include/cxxabi.h`
4. Update `_LIBUNWIND_VERSION` in `libunwind/include/__libunwind_config.h`
5. Create a release notes file for the next release from the previous ones and point to it from
- `libcxx/docs/ReleaseNotes.rst`. Remove entries that do not apply anymore, but keep in mind
+ `libcxx/docs/ReleaseNotes.md`. Remove entries that do not apply anymore, but keep in mind
that some entries (such as upcoming deprecations) may still apply, may need rewording and may
also require follow up PRs to implement.
6. Update the set of runners targeted by the CI on the release branch to `llvm-premerge-libcxx-release-runners`, and
diff --git a/libcxx/docs/Helpers/ReleaseNotesTemplate.rst b/libcxx/docs/Helpers/ReleaseNotesTemplate.md
similarity index 100%
rename from libcxx/docs/Helpers/ReleaseNotesTemplate.rst
rename to libcxx/docs/Helpers/ReleaseNotesTemplate.md
diff --git a/libcxx/docs/ReleaseNotes.rst b/libcxx/docs/ReleaseNotes.md
similarity index 100%
rename from libcxx/docs/ReleaseNotes.rst
rename to libcxx/docs/ReleaseNotes.md
diff --git a/libcxx/docs/ReleaseNotes/20.rst b/libcxx/docs/ReleaseNotes/20.md
similarity index 100%
rename from libcxx/docs/ReleaseNotes/20.rst
rename to libcxx/docs/ReleaseNotes/20.md
diff --git a/libcxx/docs/ReleaseNotes/21.rst b/libcxx/docs/ReleaseNotes/21.md
similarity index 100%
rename from libcxx/docs/ReleaseNotes/21.rst
rename to libcxx/docs/ReleaseNotes/21.md
diff --git a/libcxx/docs/ReleaseNotes/22.rst b/libcxx/docs/ReleaseNotes/22.md
similarity index 100%
rename from libcxx/docs/ReleaseNotes/22.rst
rename to libcxx/docs/ReleaseNotes/22.md
diff --git a/libcxx/docs/ReleaseNotes/23.rst b/libcxx/docs/ReleaseNotes/23.md
similarity index 100%
rename from libcxx/docs/ReleaseNotes/23.rst
rename to libcxx/docs/ReleaseNotes/23.md
diff --git a/libcxx/docs/ReleaseNotes/24.rst b/libcxx/docs/ReleaseNotes/24.md
similarity index 100%
rename from libcxx/docs/ReleaseNotes/24.rst
rename to libcxx/docs/ReleaseNotes/24.md
>From 68c91f56917229d5b6ea26e5317b392a46b45608 Mon Sep 17 00:00:00 2001
From: s4chinjha <s4chinjha at gmail.com>
Date: Wed, 21 Oct 2026 01:22:33 +0530
Subject: [PATCH 2/3] [libc++][docs] Rewrite remaining docs to md
---
libcxx/docs/Helpers/ReleaseNotesTemplate.md | 65 +++---
libcxx/docs/ReleaseNotes.md | 23 +-
libcxx/docs/ReleaseNotes/20.md | 233 +++++++++-----------
libcxx/docs/ReleaseNotes/21.md | 201 ++++++++---------
libcxx/docs/ReleaseNotes/22.md | 203 ++++++++---------
libcxx/docs/ReleaseNotes/23.md | 176 +++++++--------
libcxx/docs/ReleaseNotes/24.md | 139 ++++++------
7 files changed, 468 insertions(+), 572 deletions(-)
diff --git a/libcxx/docs/Helpers/ReleaseNotesTemplate.md b/libcxx/docs/Helpers/ReleaseNotesTemplate.md
index cc4468cf3cc4f3..8e08dd967d2c9b 100644
--- a/libcxx/docs/Helpers/ReleaseNotesTemplate.md
+++ b/libcxx/docs/Helpers/ReleaseNotesTemplate.md
@@ -1,62 +1,47 @@
-===========================================
-Libc++ XX.YY.ZZ (In-Progress) Release Notes
-===========================================
+# Libc++ XX.YY.ZZ (In-Progress) Release Notes
-.. contents::
- :local:
- :depth: 2
+```{contents}
+:depth: 2
+:local: true
+```
-Written by the :doc:`Libc++ Team </index>`
+Written by the {doc}`Libc++ Team </index>`
-.. warning::
+:::{warning}
+These are in-progress notes for the upcoming libc++ XX.YY.ZZ release.
+Release notes for previous releases can be found on
+[the Download Page](https://releases.llvm.org/download.html).
+:::
- These are in-progress notes for the upcoming libc++ XX.YY.ZZ release.
- Release notes for previous releases can be found on
- `the Download Page <https://releases.llvm.org/download.html>`_.
-
-Introduction
-============
+## Introduction
This document contains the release notes for the libc++ C++ Standard Library,
part of the LLVM Compiler Infrastructure, release XX.YY.ZZ. 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/>`_.
+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 :doc:`Libc++ Web Site
-</index>` or the `LLVM Web Site <https://llvm.org>`_.
+For more information about libc++, please see the {doc}`Libc++ Web Site
+</index>` 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++ XX.YY.ZZ?
-==============================
-
-
-Implemented Papers
-------------------
+see the [releases page](https://llvm.org/releases/).
+## What's New in Libc++ XX.YY.ZZ?
-Improvements and New Features
------------------------------
+### Implemented Papers
+### Improvements and New Features
-Deprecations and Removals
--------------------------
+### Deprecations and Removals
-
-Upcoming Deprecations and Removals
-----------------------------------
+### Upcoming Deprecations and Removals
NOTE: THIS SHOULD BE POPULATED FROM THE PREVIOUS RELEASE'S UPCOMING DEPRECATIONS AND REMOVALS FOR THE NEXT-NEXT RELEASE (IF ANY)
-ABI Affecting Changes
----------------------
-
-
-Build System Changes
---------------------
+### ABI Affecting Changes
+### Build System Changes
diff --git a/libcxx/docs/ReleaseNotes.md b/libcxx/docs/ReleaseNotes.md
index 37078d83139aba..679f6eab7e2443 100644
--- a/libcxx/docs/ReleaseNotes.md
+++ b/libcxx/docs/ReleaseNotes.md
@@ -1,13 +1,16 @@
-.. include:: ReleaseNotes/24.rst
+```{include} ReleaseNotes/24.md
+```
-.. Make sure to reference the non-live release notes in a toctree to avoid Sphinx errors.
-.. toctree::
- :hidden:
+% Make sure to reference the non-live release notes in a toctree to avoid Sphinx errors.
- ReleaseNotes/20
- ReleaseNotes/21
- ReleaseNotes/22
- ReleaseNotes/23
+```{toctree}
+:hidden:
-.. The release notes are in versioned files, but we make sure to keep publishing
-.. them in an unversioned ReleaseNotes.html page for external sites to reference.
+ReleaseNotes/20
+ReleaseNotes/21
+ReleaseNotes/22
+ReleaseNotes/23
+```
+
+% The release notes are in versioned files, but we make sure to keep publishing
+% them in an unversioned ReleaseNotes.html page for external sites to reference.
diff --git a/libcxx/docs/ReleaseNotes/20.md b/libcxx/docs/ReleaseNotes/20.md
index 541d8048b1cd26..16a349fdd2c889 100644
--- a/libcxx/docs/ReleaseNotes/20.md
+++ b/libcxx/docs/ReleaseNotes/20.md
@@ -1,206 +1,187 @@
-===========================================
-Libc++ 20.0.0 (In-Progress) Release Notes
-===========================================
+# Libc++ 20.0.0 (In-Progress) Release Notes
-.. contents::
- :local:
- :depth: 2
+```{contents}
+:depth: 2
+:local: true
+```
-Written by the :doc:`Libc++ Team </index>`
+Written by the {doc}`Libc++ Team </index>`
-.. warning::
+:::{warning}
+These are in-progress notes for the upcoming libc++ 20.0.0 release.
+Release notes for previous releases can be found on
+[the Download Page](https://releases.llvm.org/download.html).
+:::
- These are in-progress notes for the upcoming libc++ 20.0.0 release.
- Release notes for previous releases can be found on
- `the Download Page <https://releases.llvm.org/download.html>`_.
-
-Introduction
-============
+## Introduction
This document contains the release notes for the libc++ C++ Standard Library,
part of the LLVM Compiler Infrastructure, release 20.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/>`_.
+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 :doc:`Libc++ Web Site
-</index>` or the `LLVM Web Site <https://llvm.org>`_.
+For more information about libc++, please see the {doc}`Libc++ Web Site
+</index>` 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/>`_.
+see the [releases page](https://llvm.org/releases/).
-What's New in Libc++ 20.0.0?
-==============================
+## What's New in Libc++ 20.0.0?
The main focus of the libc++ team has been to implement new C++20, C++23, and C++26 features.
-Implemented Papers
-------------------
+### Implemented Papers
-- P0619R4: Reviewing Deprecated Facilities of C++17 for C++20 (`Github <https://github.com/llvm/llvm-project/issues/99985>`__)
-- P2747R2: ``constexpr`` placement new (`Github <https://github.com/llvm/llvm-project/issues/105427>`__)
-- P2609R3: Relaxing Ranges Just A Smidge (`Github <https://github.com/llvm/llvm-project/issues/105253>`__)
-- P2985R0: A type trait for detecting virtual base classes (`Github <https://github.com/llvm/llvm-project/issues/105432>`__)
-- ``std::jthread`` and ``<stop_token>`` are not guarded behind ``-fexperimental-library`` anymore
-- P2674R1: A trait for implicit lifetime types (`Github <https://github.com/llvm/llvm-project/issues/105259>`__)
-- P0429R9: A Standard ``flat_map`` (`Github <https://github.com/llvm/llvm-project/issues/105190>`__)
+- P0619R4: Reviewing Deprecated Facilities of C++17 for C++20 ([Github](https://github.com/llvm/llvm-project/issues/99985))
+- P2747R2: `constexpr` placement new ([Github](https://github.com/llvm/llvm-project/issues/105427))
+- P2609R3: Relaxing Ranges Just A Smidge ([Github](https://github.com/llvm/llvm-project/issues/105253))
+- P2985R0: A type trait for detecting virtual base classes ([Github](https://github.com/llvm/llvm-project/issues/105432))
+- `std::jthread` and `<stop_token>` are not guarded behind `-fexperimental-library` anymore
+- P2674R1: A trait for implicit lifetime types ([Github](https://github.com/llvm/llvm-project/issues/105259))
+- P0429R9: A Standard `flat_map` ([Github](https://github.com/llvm/llvm-project/issues/105190))
-Improvements and New Features
------------------------------
+### Improvements and New Features
-- The ``lexicographical_compare`` and ``ranges::lexicographical_compare`` algorithms have been optimized for trivially
+- The `lexicographical_compare` and `ranges::lexicographical_compare` algorithms have been optimized for trivially
equality comparable types, resulting in a performance improvement of up to 40x.
-- The ``_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER`` macro has been added to make ``std::get_temporary_buffer`` and
- ``std::return_temporary_buffer`` available.
+- The `_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER` macro has been added to make `std::get_temporary_buffer` and
+ `std::return_temporary_buffer` available.
-- The ``std::uncaught_exception`` function was marked as deprecated since C++17 and removed since C++20. The
- ``_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION`` macro has been added to make ``std::uncaught_exception``
+- The `std::uncaught_exception` function was marked as deprecated since C++17 and removed since C++20. The
+ `_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION` macro has been added to make `std::uncaught_exception`
available in C++20 and later modes.
-- The internal structure ``__compressed_pair`` has been replaced with ``[[no_unique_address]]``, resulting in reduced
+- The internal structure `__compressed_pair` has been replaced with `[[no_unique_address]]`, resulting in reduced
compile times and smaller debug information as well as better code generation if optimizations are disabled.
The Chromium project measured a 5% reduction in object file and debug information size.
-- The ``_LIBCPP_ABI_BOUNDED_UNIQUE_PTR`` ABI configuration was added, which allows ``std::unique_ptr<T[]>`` to
- detect out-of-bounds accesses in certain circumstances. ``std::unique_ptr<T[]>`` can now also detect out-of-bounds
+- The `_LIBCPP_ABI_BOUNDED_UNIQUE_PTR` ABI configuration was added, which allows `std::unique_ptr<T[]>` to
+ detect out-of-bounds accesses in certain circumstances. `std::unique_ptr<T[]>` can now also detect out-of-bounds
accesses for a limited set of types (non-trivially destructible types) when the ABI configuration is disabled.
-- The ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY`` ABI configuration was added, which allows storing valid bounds
- in ``std::array::iterator`` and detecting OOB accesses when the appropriate hardening mode is enabled.
+- The `_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY` ABI configuration was added, which allows storing valid bounds
+ in `std::array::iterator` and detecting OOB accesses when the appropriate hardening mode is enabled.
-- The ``input_iterator``-pair overload of ``void assign(InputIt, InputIt)`` has been optimized for ``std::vector``,
- resulting in a performance improvement of up to 2x for trivial element types (e.g., ``std::vector<int>``), and up
- to 3.4x for non-trivial element types (e.g., ``std::vector<std::vector<int>>``).
+- The `input_iterator`-pair overload of `void assign(InputIt, InputIt)` has been optimized for `std::vector`,
+ resulting in a performance improvement of up to 2x for trivial element types (e.g., `std::vector<int>`), and up
+ to 3.4x for non-trivial element types (e.g., `std::vector<std::vector<int>>`).
-- The ``input_iterator``-pair overload of ``iterator insert(const_iterator, InputIt, InputIt)`` has been optimized
- for ``std::vector``, resulting in a performance improvement of up to 10x for ``std::vector<int>``, and up to 2.3x
- for ``std::vector<std::vector<int>>``.
+- The `input_iterator`-pair overload of `iterator insert(const_iterator, InputIt, InputIt)` has been optimized
+ for `std::vector`, resulting in a performance improvement of up to 10x for `std::vector<int>`, and up to 2.3x
+ for `std::vector<std::vector<int>>`.
-- On Windows, ``<system_error>``'s ``std::system_category`` is now distinct from ``std::generic_category``. The behavior
+- On Windows, `<system_error>`'s `std::system_category` is now distinct from `std::generic_category`. The behavior
on other operating systems is unchanged.
On Windows -- unlike on Unix systems -- the libc and system APIs use distinct error codes. The libc functions return
- ``errno.h`` error codes via the ``errno`` global, while Win32 API functions return ``winerror.h`` error codes via
- ``GetLastError()``.
+ `errno.h` error codes via the `errno` global, while Win32 API functions return `winerror.h` error codes via
+ `GetLastError()`.
- The C++ standard's ``std::error_code`` and ``std::error_category`` functionality was designed to support multiple
+ The C++ standard's `std::error_code` and `std::error_category` functionality was designed to support multiple
error domains, precisely in order to handle situations such as this. However, libc++ formerly treated
- ``generic_category()`` and ``system_category()`` as equivalent, even on Windows. It now implements the intended split,
- where ``system_category`` represents native ``winerror.h`` error codes, and ``generic_category`` represents libc error
- codes (and, equivalently, ``std::errc::*`` errors).
+ `generic_category()` and `system_category()` as equivalent, even on Windows. It now implements the intended split,
+ where `system_category` represents native `winerror.h` error codes, and `generic_category` represents libc error
+ codes (and, equivalently, `std::errc::*` errors).
- This change enables code like ``std::error_code(GetLastError(), std::system_category()) ==
- std::errc::invalid_argument`` to function as desired: constructing an ``error_code`` with the Windows error number in
- the "system" category, and then mapping it to a generic code with ``error_condition``, for comparison with the
- ``std::errc`` constant.
+ This change enables code like `std::error_code(GetLastError(), std::system_category()) ==
+ std::errc::invalid_argument` to function as desired: constructing an `error_code` with the Windows error number in
+ the "system" category, and then mapping it to a generic code with `error_condition`, for comparison with the
+ `std::errc` constant.
- This is an incompatible change: ``std::error_code(ENOSYS, std::system_category()) ==
- std::errc::function_not_supported`` would formerly have returned true, but now returns false on Windows. Code
- providing a number from the ``errno.h`` domain should be migrated to construct a ``generic_category`` error_code,
- instead. (E.g., use ``std::error_code(ENOSYS, std::generic_category())``). The new behavior matches MSVC.
+ This is an incompatible change: `std::error_code(ENOSYS, std::system_category()) ==
+ std::errc::function_not_supported` would formerly have returned true, but now returns false on Windows. Code
+ providing a number from the `errno.h` domain should be migrated to construct a `generic_category` error_code,
+ instead. (E.g., use `std::error_code(ENOSYS, std::generic_category())`). The new behavior matches MSVC.
-- On Windows, the ``std::filesystem`` library now returns the Win32 ``system_category`` error codes, where it's feasible
+- On Windows, the `std::filesystem` library now returns the Win32 `system_category` error codes, where it's feasible
to do so. This allows interrogation and reporting of the original error code, which is useful if multiple Windows
- errors map to a single generic error (such as with ``std::errc::no_such_file_or_directory``).
+ errors map to a single generic error (such as with `std::errc::no_such_file_or_directory`).
This is also a slightly-incompatible API change: code inspecting the raw integer value from the returned error_code
- expecting an integer from ``generic_category`` (e.g. ``err.value() == ENOTDIR``) will not work as desired. Instead,
- such code should use the comparison operators which implicitly handle eror mappings, ``err ==
- std::errc::not_a_directory``, or use ``err.default_error_condition()`` to map to an ``error_condition``, and then test
- its ``value()`` and ``category()``.
+ expecting an integer from `generic_category` (e.g. `err.value() == ENOTDIR`) will not work as desired. Instead,
+ such code should use the comparison operators which implicitly handle eror mappings, `err ==
+ std::errc::not_a_directory`, or use `err.default_error_condition()` to map to an `error_condition`, and then test
+ its `value()` and `category()`.
-- ``std::stable_sort`` uses radix sort for integral types now, which can improve the performance up to 10 times, depending
+- `std::stable_sort` uses radix sort for integral types now, which can improve the performance up to 10 times, depending
on type of sorted elements and the initial state of the sorted array.
- Reduced the amount of debug information generated for internal typedefs. This reduces the size of debug builds.
-- Added :ref:`hardening mode <hardening>` support for ``forward_list`` and ``bitset``.
+- Added {ref}`hardening mode <hardening>` support for `forward_list` and `bitset`.
-- The performance of ``std::getline`` has been improved, resulting in a performance uplift of up to 10x.
+- The performance of `std::getline` has been improved, resulting in a performance uplift of up to 10x.
-Deprecations and Removals
--------------------------
+### Deprecations and Removals
-- The ``LIBCXX_ENABLE_ASSERTIONS`` CMake variable and the ``_LIBCPP_ENABLE_ASSERTIONS`` macro that were used to
- enable the safe mode have been removed in LLVM 20. Please use :ref:`support for hardening <using-hardening-modes>`
+- The `LIBCXX_ENABLE_ASSERTIONS` CMake variable and the `_LIBCPP_ENABLE_ASSERTIONS` macro that were used to
+ enable the safe mode have been removed in LLVM 20. Please use {ref}`support for hardening <using-hardening-modes>`
instead.
-
-- Support for the C++20 synchronization library (``<barrier>``, ``<latch>``, ``atomic::wait``, etc.) has been
+- Support for the C++20 synchronization library (`<barrier>`, `<latch>`, `atomic::wait`, etc.) has been
removed in language modes prior to C++20. If you are using these features prior to C++20, you will need to
- update to ``-std=c++20``.
-
-- The relational operators for ``std::chrono::weekday`` has been removed entirely, and the
- ``_LIBCPP_ENABLE_REMOVED_WEEKDAY_RELATIONAL_OPERATORS`` macro is now ignored.
-
-- The ``_LIBCPP_ENABLE_REMOVED_ALLOCATOR_CONST`` macro no longer has any effect. ``std::allocator<const T>`` is not
- supported as an extension anymore, please migrate any code that uses e.g. ``std::vector<const T>`` to be
+ update to `-std=c++20`.
+- The relational operators for `std::chrono::weekday` has been removed entirely, and the
+ `_LIBCPP_ENABLE_REMOVED_WEEKDAY_RELATIONAL_OPERATORS` macro is now ignored.
+- The `_LIBCPP_ENABLE_REMOVED_ALLOCATOR_CONST` macro no longer has any effect. `std::allocator<const T>` is not
+ supported as an extension anymore, please migrate any code that uses e.g. `std::vector<const T>` to be
standards conforming.
-
-- Non-conforming member typedefs ``base``, ``iterator``, ``const_iterator``, ``size_type``, ``difference_type``, and
- ``const_reference`` of ``std::bitset``, and member typedef ``base`` of ``std::forward_list`` and ``std::list`` are
- removed. Previously, these member typedefs (except ``const_reference``) were private but could cause ambiguity in name
+- Non-conforming member typedefs `base`, `iterator`, `const_iterator`, `size_type`, `difference_type`, and
+ `const_reference` of `std::bitset`, and member typedef `base` of `std::forward_list` and `std::list` are
+ removed. Previously, these member typedefs (except `const_reference`) were private but could cause ambiguity in name
lookup. Code that expects such ambiguity will possibly not compile in LLVM 20.
-
-- The function ``__libcpp_verbose_abort()`` is now ``noexcept``, to match ``std::terminate()``. (The combination of
- ``noexcept`` and ``[[noreturn]]`` has special significance for function effects analysis.) For backwards compatibility,
- the ``_LIBCPP_VERBOSE_ABORT_NOT_NOEXCEPT`` macro can be defined to make the function non-``noexcept``. That macro
+- The function `__libcpp_verbose_abort()` is now `noexcept`, to match `std::terminate()`. (The combination of
+ `noexcept` and `[[noreturn]]` has special significance for function effects analysis.) For backwards compatibility,
+ the `_LIBCPP_VERBOSE_ABORT_NOT_NOEXCEPT` macro can be defined to make the function non-`noexcept`. That macro
will be removed in LLVM 21.
-
-- ``<ccomplex>``, ``<cstdalign>`` (previously missing), ``<cstdbool>``, and ``<ctgmath>`` are deprecated since C++17 as
- specified by the standard. They, together with ``<ciso646>``, are removed in C++20, but libc++ still provides these
- headers as an extension and only deprecates them. The ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS`` macro can be defined to
+- `<ccomplex>`, `<cstdalign>` (previously missing), `<cstdbool>`, and `<ctgmath>` are deprecated since C++17 as
+ specified by the standard. They, together with `<ciso646>`, are removed in C++20, but libc++ still provides these
+ headers as an extension and only deprecates them. The `_LIBCPP_DISABLE_DEPRECATION_WARNINGS` macro can be defined to
suppress deprecation for these headers.
-
-- The pointer safety functions ``declare_reachable``, ``declare_no_pointers``, ``undeclare_no_pointers`` and
- ``__undeclare_reachable`` have been removed from the library. These functions were never implemented in a non-trivial
+- The pointer safety functions `declare_reachable`, `declare_no_pointers`, `undeclare_no_pointers` and
+ `__undeclare_reachable` have been removed from the library. These functions were never implemented in a non-trivial
way, making it very unlikely that any binary depends on them.
-
-- Non-conforming extension ``packaged_task::result_type`` is deprecated. It will be removed in LLVM 21.
-
-- The changes for ``ranges::zip_view`` from `P2165R4 <https://wg21.link/P2165R4>`_ have been implemented. This can
- lead to code assuming that ``zip_view`` produces ``std::pair`` to stop compiling now that it produces ``std::tuple``.
- The cases are rare since ``tuple`` and ``pair`` are compatible for the most part, but this can lead to code that
+- Non-conforming extension `packaged_task::result_type` is deprecated. It will be removed in LLVM 21.
+- The changes for `ranges::zip_view` from [P2165R4](https://wg21.link/P2165R4) have been implemented. This can
+ lead to code assuming that `zip_view` produces `std::pair` to stop compiling now that it produces `std::tuple`.
+ The cases are rare since `tuple` and `pair` are compatible for the most part, but this can lead to code that
was previously accepted now being rejected. This is necessary for libc++ to be conforming, so we don't provide any
way to opt-out of that behavior.
-Upcoming Deprecations and Removals
-----------------------------------
+### Upcoming Deprecations and Removals
-LLVM 21
-~~~~~~~
+#### LLVM 21
- 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.
+ 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++.
-- The ``_LIBCPP_VERBOSE_ABORT_NOT_NOEXCEPT`` macro will be removed in LLVM 21, making ``std::__libcpp_verbose_abort``
- unconditionally ``noexcept``.
-
-- Non-conforming extension ``packaged_task::result_type`` will be removed in LLVM 21.
+- The `_LIBCPP_VERBOSE_ABORT_NOT_NOEXCEPT` macro will be removed in LLVM 21, making `std::__libcpp_verbose_abort`
+ unconditionally `noexcept`.
+- Non-conforming extension `packaged_task::result_type` will be removed in LLVM 21.
-ABI Affecting Changes
----------------------
+### ABI Affecting Changes
-- The ABI breaks for removing undefined behaviour in ``std::forward_list``, ``std::list``, ``std::map``, ``std::set``,
- ``std::multimap``, ``std::multiset``, ``std::unordered_map``, ``std::unordered_set``, ``std::unordered_multimap`` and
- ``std::unordered_multiset`` are now applied unconditionally. This only affects fancy pointers which have a different
+- The ABI breaks for removing undefined behaviour in `std::forward_list`, `std::list`, `std::map`, `std::set`,
+ `std::multimap`, `std::multiset`, `std::unordered_map`, `std::unordered_set`, `std::unordered_multimap` and
+ `std::unordered_multiset` are now applied unconditionally. This only affects fancy pointers which have a different
value representation when pointing at the base of an internal node type instead of the type itself. A size or
alignment difference is diagnosed, but more subtle ABI breaks may result in unexpected behaviour.
-- The internal structure ``__compressed_pair`` has been replaced with ``[[no_unique_address]]``. The ABI impact is:
+- The internal structure `__compressed_pair` has been replaced with `[[no_unique_address]]`. The ABI impact is:
- When using the Itanium ABI (most non-MSVC platforms), empty types are now placed at the beginning of the enclosing
- object instead of where the beginning of the ``__compressed_pair`` subobject was. This is only observable by
+ object instead of where the beginning of the `__compressed_pair` subobject was. This is only observable by
checking the address of the empty allocator, equality comparator or hasher.
- Additionally, using an overaligned empty type as an allocator, comparator or hasher in the associative containers
(and only those containers) may result in the container's object object size and data layout changing beyond only
@@ -211,7 +192,7 @@ ABI Affecting Changes
- The localization support base API has been reimplemented, leading to different functions being exported from the
libc++ built library on Windows and Windows-like platforms.
-- The changes for ``ranges::zip_view`` from `P2165R4 <https://wg21.link/P2165R4>`_ have been implemented. This changes
- the element type of ``zip_view`` from a ``std::pair`` to a ``std::tuple`` in some cases. This is technically an ABI
- break, however since ``zip_view`` is generally not an ABI sensitive type, we don't expect users to encounter any
+- The changes for `ranges::zip_view` from [P2165R4](https://wg21.link/P2165R4) have been implemented. This changes
+ the element type of `zip_view` from a `std::pair` to a `std::tuple` in some cases. This is technically an ABI
+ break, however since `zip_view` is generally not an ABI sensitive type, we don't expect users to encounter any
issues and we don't provide a way to change this behavior, which would make libc++ non-conforming.
diff --git a/libcxx/docs/ReleaseNotes/21.md b/libcxx/docs/ReleaseNotes/21.md
index 716971e546982b..07ff107b47ed0c 100644
--- a/libcxx/docs/ReleaseNotes/21.md
+++ b/libcxx/docs/ReleaseNotes/21.md
@@ -1,169 +1,140 @@
-===========================================
-Libc++ 21.0.0 (In-Progress) Release Notes
-===========================================
+# Libc++ 21.0.0 (In-Progress) Release Notes
-.. contents::
- :local:
- :depth: 2
+```{contents}
+:depth: 2
+:local: true
+```
-Written by the :doc:`Libc++ Team </index>`
+Written by the {doc}`Libc++ Team </index>`
-.. warning::
+:::{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).
+:::
- 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
-============
+## 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/>`_.
+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 :doc:`Libc++ Web Site
-</index>` or the `LLVM Web Site <https://llvm.org>`_.
+For more information about libc++, please see the {doc}`Libc++ Web Site
+</index>` 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>`__)
-- 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
+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))
+- 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
+- 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
+- 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
+- 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
+- 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.
-
+- 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
+ 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``.
+### Deprecations and Removals
-- libc++ no longer adds ``constexpr`` to ``std::hash<std::vector<bool, A>>::operator()``, as the ``constexpr`` addition
+- `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.
-- The non-conforming extension ``packaged_task::result_type`` has been removed in LLVM 21.
+### Potentially breaking changes
-Potentially breaking changes
-----------------------------
-
-- The implementation of ``num_put::do_put`` has been replaced to improve the performance, which can lead to different
+- 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`
+- 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
+ 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
------------------------------------
+### Announcements About Future Releases
-LLVM 22
-~~~~~~~
+#### 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.
+ 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
-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
+- 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.
-- LLVM 20 contained an ABI break that can result in the size of ``std::unordered_{map,set,multimap,multiset}`` and ``std::deque`` changing when used with an allocator type that is empty and contains a base class that is the same across rebound allocator instantiations (e.g. ``Allocator<int>`` and ``Allocator<char>`` are both empty and contain the same base class).
+- LLVM 20 contained an ABI break that can result in the size of `std::unordered_{map,set,multimap,multiset}` and `std::deque` changing when used with an allocator type that is empty and contains a base class that is the same across rebound allocator instantiations (e.g. `Allocator<int>` and `Allocator<char>` are both empty and contain the same base class).
In addition, the layout of a user-defined type that:
- - contains one of the following containers: ``std::unordered_{map,set,multimap,multiset}``, ``std::deque``, ``std::map``, ``std::set``, ``std::multimap``, ``std::multiset``, ``std::list`` or ``std::vector``, and
- - passes an empty allocator, comparator or hasher type to that container, and
- - has a member of that same empty allocator, comparator or hasher type inside the enclosing struct, and
- - that member is either marked with ``[[no_unique_address]]`` or optimized out via the EBO (empty base optimization) technique
+ > - contains one of the following containers: `std::unordered_{map,set,multimap,multiset}`, `std::deque`, `std::map`, `std::set`, `std::multimap`, `std::multiset`, `std::list` or `std::vector`, and
+ > - passes an empty allocator, comparator or hasher type to that container, and
+ > - has a member of that same empty allocator, comparator or hasher type inside the enclosing struct, and
+ > - that member is either marked with `[[no_unique_address]]` or optimized out via the EBO (empty base optimization) technique
- saw its size increase from LLVM 19 to LLVM 20. This was caused by the usage of ``[[no_unique_address]]`` within some of libc++'s containers in a way that allowed subtle interactions with enclosing objects. This is fixed in LLVM 21 when using the Clang compiler (returning to the LLVM 19 ABI), however that implies an ABI break from LLVM 20 to LLVM 21.
+ saw its size increase from LLVM 19 to LLVM 20. This was caused by the usage of `[[no_unique_address]]` within some of libc++'s containers in a way that allowed subtle interactions with enclosing objects. This is fixed in LLVM 21 when using the Clang compiler (returning to the LLVM 19 ABI), however that implies an ABI break from LLVM 20 to LLVM 21.
- Furthermore, fixing this causes a slight regression to constant evaluation support in ``std::unique_ptr``. Specifically, constant evaluation will now fail when the deleter relies on being value-initialized for constant-evaluation admissibility. If a default-initialized deleter can be used during constant evaluation, or if the default constructor is non-trivial, the ``unique_ptr`` is not affected by this regression. In particular, this regression does not impact any ``unique_ptr`` using the default deleter.
+ Furthermore, fixing this causes a slight regression to constant evaluation support in `std::unique_ptr`. Specifically, constant evaluation will now fail when the deleter relies on being value-initialized for constant-evaluation admissibility. If a default-initialized deleter can be used during constant evaluation, or if the default constructor is non-trivial, the `unique_ptr` is not affected by this regression. In particular, this regression does not impact any `unique_ptr` using the default deleter.
Note that there is currently no way to realistically fix this ABI break on GCC, therefore GCC will remain on the ABI introduced in LLVM 19. That also means that Clang and GCC will have a slightly different ABI for the small subset of types listed above until we are able to apply the same fix we did with Clang on GCC.
- For more details see https://llvm.org/PR154146.
+ For more details see <https://llvm.org/PR154146>.
-Build System Changes
---------------------
+### Build System Changes
- TODO
diff --git a/libcxx/docs/ReleaseNotes/22.md b/libcxx/docs/ReleaseNotes/22.md
index 9b1b91acca187d..17d1e104e97a9a 100644
--- a/libcxx/docs/ReleaseNotes/22.md
+++ b/libcxx/docs/ReleaseNotes/22.md
@@ -1,158 +1,145 @@
-===========================================
-Libc++ 22.0.0 (In-Progress) Release Notes
-===========================================
+# Libc++ 22.0.0 (In-Progress) Release Notes
-.. contents::
- :local:
- :depth: 2
+```{contents}
+:depth: 2
+:local: true
+```
-Written by the :doc:`Libc++ Team </index>`
+Written by the {doc}`Libc++ Team </index>`
-.. warning::
+:::{warning}
+These are in-progress notes for the upcoming libc++ 22.0.0 release.
+Release notes for previous releases can be found on
+[the Download Page](https://releases.llvm.org/download.html).
+:::
- These are in-progress notes for the upcoming libc++ 22.0.0 release.
- Release notes for previous releases can be found on
- `the Download Page <https://releases.llvm.org/download.html>`_.
-
-Introduction
-============
+## Introduction
This document contains the release notes for the libc++ C++ Standard Library,
part of the LLVM Compiler Infrastructure, release 22.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/>`_.
+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 :doc:`Libc++ Web Site
-</index>` or the `LLVM Web Site <https://llvm.org>`_.
+For more information about libc++, please see the {doc}`Libc++ Web Site
+</index>` 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++ 22.0.0?
-==============================
-
-Implemented Papers
-------------------
-
-- P2592R3: Hashing support for ``std::chrono`` value classes (`Github <https://llvm.org/PR105358>`__)
-- P2321R2: ``zip`` (`Github <https://llvm.org/PR105169>`__)
-- P2988R12: ``std::optional<T&>`` (`Github <https://llvm.org/PR148131>`__)
-- P3044R2: sub-``string_view`` from ``string`` (`Github <https://llvm.org/PR148140>`__)
-- P3223R2: Making ``std::istream::ignore`` less surprising (`Github <https://llvm.org/PR148178>`__)
-- P3060R3: Add ``std::views::indices(n)`` (`Github <https://llvm.org/PR148175>`__)
-- P2404R3: Move-only types for ``equality_comparable_with``, ``totally_ordered_with``, and ``three_way_comparable_with``
- (`Github <https://llvm.org/PR105210>`__)
-- P2641R4: Checking if a ``union`` alternative is active (``std::is_within_lifetime``)
- (`Github <https://llvm.org/PR105381>`__)
-- P2835R7: Expose ``std::atomic_ref``'s object address (`Github <https://llvm.org/PR118377>`__)
-- P2944R3: Comparisons for ``reference_wrapper`` (`Github <https://llvm.org/PR105424>`__)
-- P3168R2: Give ``std::optional`` Range Support
- (guarded by ``-fexperimental-library``, `Github <https://llvm.org/PR105430>`__)
-- P3567R2: ``flat_meow`` Fixes (`Github <https://llvm.org/PR162022>`__)
-- P3836R2: Make ``optional<T&>`` trivially copyable (`Github <https://llvm.org/PR171275>`__)
-- P1789R3: Library Support for Expansion Statements (`Github <https://llvm.org/PR167184>`__)
-
-Improvements and New Features
------------------------------
+see the [releases page](https://llvm.org/releases/).
+
+## What's New in Libc++ 22.0.0?
+
+### Implemented Papers
+
+- P2592R3: Hashing support for `std::chrono` value classes ([Github](https://llvm.org/PR105358))
+- P2321R2: `zip` ([Github](https://llvm.org/PR105169))
+- P2988R12: `std::optional<T&>` ([Github](https://llvm.org/PR148131))
+- P3044R2: sub-`string_view` from `string` ([Github](https://llvm.org/PR148140))
+- P3223R2: Making `std::istream::ignore` less surprising ([Github](https://llvm.org/PR148178))
+- P3060R3: Add `std::views::indices(n)` ([Github](https://llvm.org/PR148175))
+- P2404R3: Move-only types for `equality_comparable_with`, `totally_ordered_with`, and `three_way_comparable_with`
+ ([Github](https://llvm.org/PR105210))
+- P2641R4: Checking if a `union` alternative is active (`std::is_within_lifetime`)
+ ([Github](https://llvm.org/PR105381))
+- P2835R7: Expose `std::atomic_ref`'s object address ([Github](https://llvm.org/PR118377))
+- P2944R3: Comparisons for `reference_wrapper` ([Github](https://llvm.org/PR105424))
+- P3168R2: Give `std::optional` Range Support
+ (guarded by `-fexperimental-library`, [Github](https://llvm.org/PR105430))
+- P3567R2: `flat_meow` Fixes ([Github](https://llvm.org/PR162022))
+- P3836R2: Make `optional<T&>` trivially copyable ([Github](https://llvm.org/PR171275))
+- P1789R3: Library Support for Expansion Statements ([Github](https://llvm.org/PR167184))
+
+### Improvements and New Features
- The performance of associative and unordered containers has been significantly improved. This is an overview of the
different functions and by up to how much they have been improved:
- - ``map::map(const map&)``: 2.3x
- - ``map::operator=(const map&)``: 11x
- - ``unordered_set::unordered_set(const unordered_set&)``: 3.3x
- - ``unordered_set::operator=(const unordered_set&)``: 5x
- - ``erase`` of ``map`` and ``set``: 2x
- - ``find(key)`` of ``map``, ``set``, ``multimap`` and ``multiset``: 2.3x
- - ``(iterator, iterator)`` constructors of ``map``, ``set``, ``multimap`` and ``multiset``: 3x
- - ``insert(iterator, iterator)`` of ``map``, ``set``, ``multimap`` and ``multiset``: 2.5x
- - ``erase(iterator, iterator)`` of the unordered containers: 1.9x
- - ``map::insert_or_assign``: 2x
+ - `map::map(const map&)`: 2.3x
+ - `map::operator=(const map&)`: 11x
+ - `unordered_set::unordered_set(const unordered_set&)`: 3.3x
+ - `unordered_set::operator=(const unordered_set&)`: 5x
+ - `erase` of `map` and `set`: 2x
+ - `find(key)` of `map`, `set`, `multimap` and `multiset`: 2.3x
+ - `(iterator, iterator)` constructors of `map`, `set`, `multimap` and `multiset`: 3x
+ - `insert(iterator, iterator)` of `map`, `set`, `multimap` and `multiset`: 2.5x
+ - `erase(iterator, iterator)` of the unordered containers: 1.9x
+ - `map::insert_or_assign`: 2x
- The performance of many algorithms has been improved. This is an overview of the different functions and by up to how
much they have been improved:
- - ``std::find`` for integral types: 2x
- - ``std::for_each`` and ``ranges::for_each`` over the associative containers: 2x
- - ``std::rotate``: 3x
+ - `std::find` for integral types: 2x
+
+ - `std::for_each` and `ranges::for_each` over the associative containers: 2x
+
+ - `std::rotate`: 3x
+
- Some have been specifically optimized for segmented iterators:
- - ``std::distance`` and ``std::ranges::distance`` on non-random-access iterators: 1600x
- - ``{std,ranges}::{fill, fill_n}``: 10x
- - ``std::{generate, generate_n}`` and ``std::ranges::generate_n``: 1.8x
+ - `std::distance` and `std::ranges::distance` on non-random-access iterators: 1600x
+ - `{std,ranges}::{fill, fill_n}`: 10x
+ - `std::{generate, generate_n}` and `std::ranges::generate_n`: 1.8x
- - ``std::search_n`` for random access iterators now tries to skip elements.
+ - `std::search_n` for random access iterators now tries to skip elements.
In contrived cases improvements of 70,000x have been observed.
- There have also been performance improvements in other library facilities:
- - ``vector<bool>::reserve()``: 2x
- - ``deque::append_range``: 3.4x
- - ``num_get::do_get`` integral overloads: 2.8x
- - Some reallocations are now avoided in ``std::filesystem::path::lexically_relative``: 1.7x
- - ``ofstream::write`` passes large strings to system calls directly instead of copying them in chunks into a buffer
- - ``std::align`` is now an inline function, which allows the compiler to better optimize calls to it
+ - `vector<bool>::reserve()`: 2x
+ - `deque::append_range`: 3.4x
+ - `num_get::do_get` integral overloads: 2.8x
+ - Some reallocations are now avoided in `std::filesystem::path::lexically_relative`: 1.7x
+ - `ofstream::write` passes large strings to system calls directly instead of copying them in chunks into a buffer
+ - `std::align` is now an inline function, which allows the compiler to better optimize calls to it
-- ``std::atomic::wait`` has been refactored to accept more types to use platform native wait functions directly.
- This is guarded behind the ABI Macro ``_LIBCPP_ABI_ATOMIC_WAIT_NATIVE_BY_SIZE``.
+- `std::atomic::wait` has been refactored to accept more types to use platform native wait functions directly.
+ This is guarded behind the ABI Macro `_LIBCPP_ABI_ATOMIC_WAIT_NATIVE_BY_SIZE`.
-- Multiple internal types have been refactored to use ``[[no_unique_address]]``, resulting in faster compile times and
+- Multiple internal types have been refactored to use `[[no_unique_address]]`, resulting in faster compile times and
reduced debug information.
-Deprecations and Removals
--------------------------
+### Deprecations and Removals
- The minimally supported deployment target on macOS has been increased to 11.0.
-Potentially breaking changes
-----------------------------
+### Potentially breaking changes
-- The algorithm for ``multi{map,set}::find`` has been modified such that it doesn't necessarily return an iterator to
+- The algorithm for `multi{map,set}::find` has been modified such that it doesn't necessarily return an iterator to
the first equal element in the container. This was never guaranteed by the Standard, but libc++ previously happened to
always return the first equal element, like other implementations do. Starting with this release, code relying on the
- first element being returned from ``find`` will be broken, and ``lower_bound`` or ``equal_range`` should be used
+ first element being returned from `find` will be broken, and `lower_bound` or `equal_range` should be used
instead.
-
-- The algorithms for ``std::{map,set}`` ``lower_bound`` and ``upper_bound`` operations were modified such that their
+- The algorithms for `std::{map,set}` `lower_bound` and `upper_bound` operations were modified such that their
result changed for comparators that are not a strict weak order. Being a strict weak order was always a requirement
- of the Standard and still is, however in this release libc++ changed the behavior of ``std::{map,set}`` for such
+ of the Standard and still is, however in this release libc++ changed the behavior of `std::{map,set}` for such
comparators. Since this may be tricky to work around in some cases, an escape hatch is provided in this release:
- defining ``_LIBCPP_ENABLE_LEGACY_TREE_LOWER_UPPER_BOUND`` will revert to the historical implementation of
+ defining `_LIBCPP_ENABLE_LEGACY_TREE_LOWER_UPPER_BOUND` will revert to the historical implementation of
these operations. That escape hatch will be removed in LLVM 23.
+- The ABI flag `_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER` has been split off from
+ `_LIBCPP_ABI_NO_ITERATOR_BASES`. If you are using this flag and care about ABI stability, you should set
+ `_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER` as well.
-- The ABI flag ``_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER`` has been split off from
- ``_LIBCPP_ABI_NO_ITERATOR_BASES``. If you are using this flag and care about ABI stability, you should set
- ``_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER`` as well.
+### Announcements About Future Releases
-Announcements About Future Releases
------------------------------------
+### ABI Affecting Changes
-ABI Affecting Changes
----------------------
-
-- The ABI flag ``_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER`` has been split off from
- ``_LIBCPP_ABI_NO_ITERATOR_BASES``. If you are using this flag and care about ABI stability, you should set
- ``_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER`` as well.
-
-- The internal types ``__map_value_compare``, ``__unordered_map_hasher``, ``__unordered_map_equal``,
- ``__hash_map_hasher`` and ``__hash_map_equal`` have been refactored to use ``_LIBCPP_COMPRESSED_ELEMENT`` instead of
+- The ABI flag `_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER` has been split off from
+ `_LIBCPP_ABI_NO_ITERATOR_BASES`. If you are using this flag and care about ABI stability, you should set
+ `_LIBCPP_ABI_NO_REVERSE_ITERATOR_SECOND_MEMBER` as well.
+- The internal types `__map_value_compare`, `__unordered_map_hasher`, `__unordered_map_equal`,
+ `__hash_map_hasher` and `__hash_map_equal` have been refactored to use `_LIBCPP_COMPRESSED_ELEMENT` instead of
potentially inheriting from the types they wrap. At this point in time we are not aware of any ABI changes caused by
this.
-
-- ``ranges::iota_view`` is now aware of ``__int128``. This causes ``iota_view::difference_type`` to change from
- ``long long`` to ``__int128`` in some cases.
-
-- ``std::allocator`` is now trivially default constructible. The behaviour can be reverted by defining
- ``_LIBCPP_DEPRECATED_ABI_NON_TRIVIAL_ALLOCATOR``. Please inform the libc++ team if you need this flag, since it will
+- `ranges::iota_view` is now aware of `__int128`. This causes `iota_view::difference_type` to change from
+ `long long` to `__int128` in some cases.
+- `std::allocator` is now trivially default constructible. The behaviour can be reverted by defining
+ `_LIBCPP_DEPRECATED_ABI_NON_TRIVIAL_ALLOCATOR`. Please inform the libc++ team if you need this flag, since it will
be removed in LLVM 24 if there is no evidence that it's required.
-
-- ``bitset::operator[]`` now returns ``bool``, making libc++ conforming. The behaviour can be reverted by defining
- ``_LIBCPP_DEPRECATED_ABI_BITSET_CONST_SUBSCRIPT_RETURN_REF``. Please inform the libc++ team if you need this flag,
+- `bitset::operator[]` now returns `bool`, making libc++ conforming. The behaviour can be reverted by defining
+ `_LIBCPP_DEPRECATED_ABI_BITSET_CONST_SUBSCRIPT_RETURN_REF`. Please inform the libc++ team if you need this flag,
since it will be removed in LLVM 24 if there is no evidence that it's required.
-Build System Changes
---------------------
+### Build System Changes
diff --git a/libcxx/docs/ReleaseNotes/23.md b/libcxx/docs/ReleaseNotes/23.md
index f06cf7d4fd6e83..479a3ebf866ccf 100644
--- a/libcxx/docs/ReleaseNotes/23.md
+++ b/libcxx/docs/ReleaseNotes/23.md
@@ -1,135 +1,117 @@
-===========================================
-Libc++ 23.0.0 (In-Progress) Release Notes
-===========================================
+# Libc++ 23.0.0 (In-Progress) Release Notes
-.. contents::
- :local:
- :depth: 2
+```{contents}
+:depth: 2
+:local: true
+```
-Written by the :doc:`Libc++ Team </index>`
+Written by the {doc}`Libc++ Team </index>`
-.. warning::
+:::{warning}
+These are in-progress notes for the upcoming libc++ 23.0.0 release.
+Release notes for previous releases can be found on
+[the Download Page](https://releases.llvm.org/download.html).
+:::
- These are in-progress notes for the upcoming libc++ 23.0.0 release.
- Release notes for previous releases can be found on
- `the Download Page <https://releases.llvm.org/download.html>`_.
-
-Introduction
-============
+## Introduction
This document contains the release notes for the libc++ C++ Standard Library,
part of the LLVM Compiler Infrastructure, release 23.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/>`_.
+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 :doc:`Libc++ Web Site
-</index>` or the `LLVM Web Site <https://llvm.org>`_.
+For more information about libc++, please see the {doc}`Libc++ Web Site
+</index>` 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++ 23.0.0?
-==============================
-
-Implemented Papers
-------------------
-
-- P2440R1: ``ranges::iota``, ``ranges::shift_left`` and ``ranges::shift_right`` (`Github <https://llvm.org/PR105184>`__)
-- P1885R12: Naming Text Encodings to Demystify Them (`Github <https://llvm.org/PR105373>`__)
-- P1899R3: ``stride_view`` (`Github <https://llvm.org/PR105198>`__)
-- P2862R1: ``text_encoding::name()`` should never return null values (`Github <https://llvm.org/PR118371>`__)
-- P3936R1: Safer ``atomic_ref::address`` (`Github <https://llvm.org/PR189594>`__)
-- P3953R3: Rename ``std::runtime_format`` (`Github <https://llvm.org/PR189624>`__)
-- P4052R0: Renaming saturation arithmetic functions (`Github <https://llvm.org/PR189589>`__)
-- P2781R9: ``std::constant_wrapper`` (`Github <https://llvm.org/PR148179>`__)
-- P3978R3: ``constant_wrapper`` should unwrap on call and subscript (`Github <https://llvm.org/PR189605>`__)
-- P2164R9: ``views::enumerate`` (`Github <https://llvm.org/PR105251>`__)
-- P2322R6: ``ranges::fold`` (`Github <https://llvm.org/PR105208>`__)
-- P4144R1: Remove ``span``'s ``initializer_list`` constructor for C++26 (`Github <https://llvm.org/PR189612>`__)
-- P2542R8: ``views::concat`` (`Github <https://llvm.org/PR105419>`__)
-- P3383R3: ``mdspan.at()`` (`Github <https://llvm.org/PR175213>`__)
-- P3369R0: constexpr for ``uninitialized_default_construct`` (`Github <https://llvm.org/PR118380>`__)
-- P3508R0: Wording for "constexpr for specialized memory algorithms" (`Github <https://llvm.org/PR118379>`__)
-- P4206R0: Revert string support in ``std::constant_wrapper`` (`Github <https://llvm.org/PR203338>`__)
-
-Improvements and New Features
------------------------------
-
-- The ``std::ranges::fold_left_with_iter`` algorithm has been optimized for
+see the [releases page](https://llvm.org/releases/).
+
+## What's New in Libc++ 23.0.0?
+
+### Implemented Papers
+
+- P2440R1: `ranges::iota`, `ranges::shift_left` and `ranges::shift_right` ([Github](https://llvm.org/PR105184))
+- P1885R12: Naming Text Encodings to Demystify Them ([Github](https://llvm.org/PR105373))
+- P1899R3: `stride_view` ([Github](https://llvm.org/PR105198))
+- P2862R1: `text_encoding::name()` should never return null values ([Github](https://llvm.org/PR118371))
+- P3936R1: Safer `atomic_ref::address` ([Github](https://llvm.org/PR189594))
+- P3953R3: Rename `std::runtime_format` ([Github](https://llvm.org/PR189624))
+- P4052R0: Renaming saturation arithmetic functions ([Github](https://llvm.org/PR189589))
+- P2781R9: `std::constant_wrapper` ([Github](https://llvm.org/PR148179))
+- P3978R3: `constant_wrapper` should unwrap on call and subscript ([Github](https://llvm.org/PR189605))
+- P2164R9: `views::enumerate` ([Github](https://llvm.org/PR105251))
+- P2322R6: `ranges::fold` ([Github](https://llvm.org/PR105208))
+- P4144R1: Remove `span`'s `initializer_list` constructor for C++26 ([Github](https://llvm.org/PR189612))
+- P2542R8: `views::concat` ([Github](https://llvm.org/PR105419))
+- P3383R3: `mdspan.at()` ([Github](https://llvm.org/PR175213))
+- P3369R0: constexpr for `uninitialized_default_construct` ([Github](https://llvm.org/PR118380))
+- P3508R0: Wording for "constexpr for specialized memory algorithms" ([Github](https://llvm.org/PR118379))
+- P4206R0: Revert string support in `std::constant_wrapper` ([Github](https://llvm.org/PR203338))
+
+### Improvements and New Features
+
+- The `std::ranges::fold_left_with_iter` algorithm has been optimized for
segmented iterators, resulting in a performance improvement of up to 1.38x
- for ``std::deque<int>`` iterators.
-- ``std::copy(CharT*, CharT*, ostreambuf_iterator<CharT>)`` has been optimized, resulting in performance improvements
+ for `std::deque<int>` iterators.
+- `std::copy(CharT*, CharT*, ostreambuf_iterator<CharT>)` has been optimized, resulting in performance improvements
of up to 25x.
- A lot of transitive includes have been removed, resulting in significant compile time improvements.
-- ``std::bad_variant_access::what()`` now returns a message identifying the cause of the failure:
- ``"std::visit: variant is valueless"``, ``"std::get: variant is valueless"``, or
- ``"std::get: wrong alternative for variant"``. The standard only requires ``what()`` to return an
+- `std::bad_variant_access::what()` now returns a message identifying the cause of the failure:
+ `"std::visit: variant is valueless"`, `"std::get: variant is valueless"`, or
+ `"std::get: wrong alternative for variant"`. The standard only requires `what()` to return an
unspecified non-null string, so user code that does not match on the exact message remains correct.
-- ``ifstream::read`` has been optimized to pass through large reads to system calls directly instead of copying them in
+- `ifstream::read` has been optimized to pass through large reads to system calls directly instead of copying them in
chunks.
-- ``std::scoped_lock`` now carries Clang thread safety annotations when locking multiple mutexes, so
- ``-Wthread-safety`` no longer incorrectly reports the guarded data accessed inside the block as
+- `std::scoped_lock` now carries Clang thread safety annotations when locking multiple mutexes, so
+ `-Wthread-safety` no longer incorrectly reports the guarded data accessed inside the block as
unprotected. This requires Clang 21 or later.
-Deprecations and Removals
--------------------------
+### Deprecations and Removals
-- The ``std::launch::any`` enumerator that was accidentally provided as an extension is now deprecated.
+- The `std::launch::any` enumerator that was accidentally provided as an extension is now deprecated.
It will be removed in LLVM 25.
-
-- In ``__wrap_iter`` (iterator wrapper type for ``array``, ``span``, ``string``, ``string_view`` and ``vector``),
- the ``base()`` method and ``iterator_type`` member type have been removed as they are non-standard.
-
-- In ``__bit_reference`` (the proxy ``reference`` type of ``bitset`` and ``vector<bool>``), the overloaded ``operator&``
+- In `__wrap_iter` (iterator wrapper type for `array`, `span`, `string`, `string_view` and `vector`),
+ the `base()` method and `iterator_type` member type have been removed as they are non-standard.
+- In `__bit_reference` (the proxy `reference` type of `bitset` and `vector<bool>`), the overloaded `operator&`
is removed as it is non-standard and causes non-conforming behavior.
-Potentially breaking changes
-----------------------------
+### Potentially breaking changes
- libc++ has dropped a lot of transitive includes in all language modes. This improves compile time significantly, but
causes programs which rely on these includes to not compile anymore. Any errors caused by this should be fixable by
- including the correct header. To ease the transition ``_LIBCPP_KEEP_TRANSITIVE_INCLUDES_LLVM23`` can be defined, which
+ including the correct header. To ease the transition `_LIBCPP_KEEP_TRANSITIVE_INCLUDES_LLVM23` can be defined, which
includes the removed headers again. This macro will be removed in LLVM 24.
-
-- The output of ``ostream << std::thread::id`` and ``std::format("...", std::thread:id)`` changes on some platforms from
+- The output of `ostream << std::thread::id` and `std::format("...", std::thread:id)` changes on some platforms from
hexadecimal to decimal. This is done to have consistent formatting across all platforms libc++ supports.
-
-- ``std::exception_ptr`` on Windows no longer relies on STL and is now implemented entirely within libc++.
+- `std::exception_ptr` on Windows no longer relies on STL and is now implemented entirely within libc++.
The implementation was donated by Microsoft and has been refactored to follow libc++ standards and conventions.
-Announcements About Future Releases
------------------------------------
+### Announcements About Future Releases
-ABI Affecting Changes
----------------------
+### ABI Affecting Changes
-- ``std::allocator`` is trivially default constructible since LLVM 22. The behaviour can be reverted by defining
- ``_LIBCPP_DEPRECATED_ABI_NON_TRIVIAL_ALLOCATOR``. Please inform the libc++ team if you need this flag, since it will
+- `std::allocator` is trivially default constructible since LLVM 22. The behaviour can be reverted by defining
+ `_LIBCPP_DEPRECATED_ABI_NON_TRIVIAL_ALLOCATOR`. Please inform the libc++ team if you need this flag, since it will
be removed in LLVM 24 if there is no evidence that it's required.
-
-- ``bitset::operator[]`` returns ``bool`` since LLVM 22, making libc++ conforming. The behaviour can be reverted by
- defining ``_LIBCPP_DEPRECATED_ABI_BITSET_CONST_SUBSCRIPT_RETURN_REF``. Please inform the libc++ team if you need this
+- `bitset::operator[]` returns `bool` since LLVM 22, making libc++ conforming. The behaviour can be reverted by
+ defining `_LIBCPP_DEPRECATED_ABI_BITSET_CONST_SUBSCRIPT_RETURN_REF`. Please inform the libc++ team if you need this
flag, since it will be removed in LLVM 24 if there is no evidence that it's required.
-
-- ``vector::iterator`` and ``string::iterator`` no longer use ``__bounded_iter<__wrap_iter<Iter>>``, but instead
- ``__bounded_iter<Iter>`` directly if ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_VECTOR`` and
- ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STRING`` are defined.
-
-- The ``const_iterator`` member type of ``std::deque`` is now corrected to hold a (possibly fancy) pointer to the
+- `vector::iterator` and `string::iterator` no longer use `__bounded_iter<__wrap_iter<Iter>>`, but instead
+ `__bounded_iter<Iter>` directly if `_LIBCPP_ABI_BOUNDED_ITERATORS_IN_VECTOR` and
+ `_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STRING` are defined.
+- The `const_iterator` member type of `std::deque` is now corrected to hold a (possibly fancy) pointer to the
(possibly fancy) pointer allocated in the internal map. E.g. when the allocators use fancy pointers, the internal map
- stores ``FancyPtr<T>`` objects, and the previous strategy accessed these objects via ``const FancyPtr<const T>``
- lvalues, causing undefined behavior. Now ``const_iterator`` stores ``FancyPtr<const FancyPtr<T>>`` instead of
- ``FancyPtr<const FancyPtr<const T>>``, which is technically an ABI break when these two types have incompatible
- layouts. The ``iterator`` member type is also changed to store ``FancyPtr<const FancyPtr<T>>`` because the internal
- map is never modified via an ``iterator``. This is necessary for reducing undefined behavior and for adding
- ``constexpr`` support for ``deque`` in C++26, so we do not provide any way to opt-out of that behavior.
-
-- ``std::exception_ptr`` now uses the same layout in MSVC mode as on other platforms, changing the size from two to one
+ stores `FancyPtr<T>` objects, and the previous strategy accessed these objects via `const FancyPtr<const T>`
+ lvalues, causing undefined behavior. Now `const_iterator` stores `FancyPtr<const FancyPtr<T>>` instead of
+ `FancyPtr<const FancyPtr<const T>>`, which is technically an ABI break when these two types have incompatible
+ layouts. The `iterator` member type is also changed to store `FancyPtr<const FancyPtr<T>>` because the internal
+ map is never modified via an `iterator`. This is necessary for reducing undefined behavior and for adding
+ `constexpr` support for `deque` in C++26, so we do not provide any way to opt-out of that behavior.
+- `std::exception_ptr` now uses the same layout in MSVC mode as on other platforms, changing the size from two to one
pointer.
-Build System Changes
---------------------
+### Build System Changes
diff --git a/libcxx/docs/ReleaseNotes/24.md b/libcxx/docs/ReleaseNotes/24.md
index 04f02ab66a773c..399e9de09c117b 100644
--- a/libcxx/docs/ReleaseNotes/24.md
+++ b/libcxx/docs/ReleaseNotes/24.md
@@ -1,103 +1,90 @@
-===========================
-Libc++ 24.0.0 Release Notes
-===========================
+# Libc++ 24.0.0 Release Notes
-.. contents::
- :local:
- :depth: 2
+```{contents}
+:depth: 2
+:local: true
+```
-Written by the :doc:`Libc++ Team </index>`
+Written by the {doc}`Libc++ Team </index>`
-.. warning::
+:::{warning}
+These are in-progress notes for the upcoming libc++ 24.0.0 release.
+Release notes for previous releases can be found on
+[the Download Page](https://releases.llvm.org/download.html).
+:::
- These are in-progress notes for the upcoming libc++ 24.0.0 release.
- Release notes for previous releases can be found on
- `the Download Page <https://releases.llvm.org/download.html>`_.
-
-Introduction
-============
+## Introduction
This document contains the release notes for the libc++ C++ Standard Library,
part of the LLVM Compiler Infrastructure, release 24.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/>`_.
+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 :doc:`Libc++ Web Site
-</index>` or the `LLVM Web Site <https://llvm.org>`_.
+For more information about libc++, please see the {doc}`Libc++ Web Site
+</index>` 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++ 24.0.0?
-==============================
-
-Implemented Papers
-------------------
-
-- P2546R5: Debugging support (`Github <https://llvm.org/PR105392>`__)
-- P2810R4: ``is_debugger_present`` ``is_replaceable`` (`Github <https://llvm.org/PR105422>`__)
-- P3052R2: ``view_interface::at()`` (`Github <https://llvm.org/PR204395>`__)
-- P0493R5: Atomic minimum/maximum (`Github <https://llvm.org/PR105418>`__)
-- P3059R2: Making user-defined constructors of view iterators/sentinels private (`Github <https://github.com/llvm/llvm-project/issues/189599>`__)
-- P0792R14: ``function_ref`` : a type-erased callable reference (`Github <https://llvm.org/PR105376>`__)
-- P3016R6: Resolve inconsistencies in begin/end for ``valarray`` and braced initializer lists
- (`Github <https://llvm.org/PR171271>`__)
-- P3948R1: ``constant_wrapper`` is the only tool needed for passing constant expressions via function arguments (`Github <https://llvm.org/PR189604>`__)
-- P3961R1: Less double indirection in ``function_ref`` (RU-220) (`Github <https://llvm.org/PR189606>`__)
-- P1901R2: Enabling the Use of ``weak_ptr`` as Keys in Unordered Associative Containers (`Github <https://llvm.org/PR105372>`__)
-- P0528R3: The Curious Case of Padding Bits, Featuring Atomic Compare-and-Exchange (`Github <https://llvm.org/PR76180>`__)
-- P3798R1: The unexpected in ``std::expected`` (`Github <https://llvm.org/PR204394>`__)
-- P2830R10: Standardized Constexpr Type Ordering (`Github <https://llvm.org/PR216616>`__)
-- P3778R0: Fix for ``type_order`` template definition (`Github <https://llvm.org/PR216616>`__)
-- P4140R0: Proposed resolution for US70-126: allow incomplete types in type_order (`Github <https://llvm.org/PR216616>`__)
-- P3450R1: Extend ``std::is_within_lifetime`` (`Github <https://llvm.org/PR189610>`__)
-- P3793R2: Better shifting (`Github <https://llvm.org/PR219389>`__) (no ``std::simd`` overloads)
-- P0040R3: Extending memory management tools (`Github <https://github.com/llvm/llvm-project/issues/103640>`__)
-
-Improvements and New Features
------------------------------
-
-- ``basic_filebuf`` now supports files larger than 2GB on 32-bit AIX and 32-bit glibc targets.
-
-Deprecations and Removals
--------------------------
-
-- The ``std::launch::any`` enumerator that was accidentally provided as an extension is now deprecated.
+see the [releases page](https://llvm.org/releases/).
+
+## What's New in Libc++ 24.0.0?
+
+### Implemented Papers
+
+- P2546R5: Debugging support ([Github](https://llvm.org/PR105392))
+- P2810R4: `is_debugger_present` `is_replaceable` ([Github](https://llvm.org/PR105422))
+- P3052R2: `view_interface::at()` ([Github](https://llvm.org/PR204395))
+- P0493R5: Atomic minimum/maximum ([Github](https://llvm.org/PR105418))
+- P3059R2: Making user-defined constructors of view iterators/sentinels private ([Github](https://github.com/llvm/llvm-project/issues/189599))
+- P0792R14: `function_ref` : a type-erased callable reference ([Github](https://llvm.org/PR105376))
+- P3016R6: Resolve inconsistencies in begin/end for `valarray` and braced initializer lists
+ ([Github](https://llvm.org/PR171271))
+- P3948R1: `constant_wrapper` is the only tool needed for passing constant expressions via function arguments ([Github](https://llvm.org/PR189604))
+- P3961R1: Less double indirection in `function_ref` (RU-220) ([Github](https://llvm.org/PR189606))
+- P1901R2: Enabling the Use of `weak_ptr` as Keys in Unordered Associative Containers ([Github](https://llvm.org/PR105372))
+- P0528R3: The Curious Case of Padding Bits, Featuring Atomic Compare-and-Exchange ([Github](https://llvm.org/PR76180))
+- P3798R1: The unexpected in `std::expected` ([Github](https://llvm.org/PR204394))
+- P2830R10: Standardized Constexpr Type Ordering ([Github](https://llvm.org/PR216616))
+- P3778R0: Fix for `type_order` template definition ([Github](https://llvm.org/PR216616))
+- P4140R0: Proposed resolution for US70-126: allow incomplete types in type_order ([Github](https://llvm.org/PR216616))
+- P3450R1: Extend `std::is_within_lifetime` ([Github](https://llvm.org/PR189610))
+- P3793R2: Better shifting ([Github](https://llvm.org/PR219389)) (no `std::simd` overloads)
+- P0040R3: Extending memory management tools ([Github](https://github.com/llvm/llvm-project/issues/103640))
+
+### Improvements and New Features
+
+- `basic_filebuf` now supports files larger than 2GB on 32-bit AIX and 32-bit glibc targets.
+
+### Deprecations and Removals
+
+- The `std::launch::any` enumerator that was accidentally provided as an extension is now deprecated.
It will be removed in LLVM 25.
-Potentially breaking changes
-----------------------------
+### Potentially breaking changes
- In LLVM 23, libc++ dropped a lot of transitive includes in all language modes. This improves compile time significantly,
- but causes programs which rely on these includes to not compile anymore. The ``_LIBCPP_KEEP_TRANSITIVE_INCLUDES_LLVM23``
+ but causes programs which rely on these includes to not compile anymore. The `_LIBCPP_KEEP_TRANSITIVE_INCLUDES_LLVM23`
macro that was provided in LLVM 23 to ease the transition has been removed in this release.
-
-- Unused objects of containers are now diagnosed. To ease the transition ``_LIBCPP_DISABLE_UNUSED_STRUCT_WARNINGS`` can
+- Unused objects of containers are now diagnosed. To ease the transition `_LIBCPP_DISABLE_UNUSED_STRUCT_WARNINGS` can
be defined as an escape hatch. This escape hatch will be removed in LLVM 24.
-
- libc++ no longer depends on msvcprt/libcpmt in the MSVC mode.
-Announcements About Future Releases
------------------------------------
+### Announcements About Future Releases
-- ``std::allocator`` is trivially default constructible since LLVM 22. In LLVM 23 and LLVM 24, the
- ``_LIBCPP_DEPRECATED_ABI_NON_TRIVIAL_ALLOCATOR`` macro was provided as an escape hatch to revert that change.
+- `std::allocator` is trivially default constructible since LLVM 22. In LLVM 23 and LLVM 24, the
+ `_LIBCPP_DEPRECATED_ABI_NON_TRIVIAL_ALLOCATOR` macro was provided as an escape hatch to revert that change.
This escape hatch will be removed in LLVM 25 if there is no evidence of it being useful.
-
-- ``bitset::operator[]`` returns ``bool`` since LLVM 22, fixing a conformance bug. In LLVM 23 and LLVM 24, the
- ``_LIBCPP_DEPRECATED_ABI_BITSET_CONST_SUBSCRIPT_RETURN_REF`` macro was provided as an escape hatch to revert
+- `bitset::operator[]` returns `bool` since LLVM 22, fixing a conformance bug. In LLVM 23 and LLVM 24, the
+ `_LIBCPP_DEPRECATED_ABI_BITSET_CONST_SUBSCRIPT_RETURN_REF` macro was provided as an escape hatch to revert
that change. This escape hatch will be removed in LLVM 25 if there is no evidence of it being useful.
-ABI Affecting Changes
----------------------
+### ABI Affecting Changes
-- ``std::set_new_handler`` and ``std::get_new_handler`` are now implemented by libc++ on Windows using ``VCRuntime``
- directly instead of implicitly relying on ``msvcprt`` to implement them, therefore the global state of the handler
- is no longer shared with ``msvcprt`` since libc++ now maintains its own internal state of the handler.
+- `std::set_new_handler` and `std::get_new_handler` are now implemented by libc++ on Windows using `VCRuntime`
+ directly instead of implicitly relying on `msvcprt` to implement them, therefore the global state of the handler
+ is no longer shared with `msvcprt` since libc++ now maintains its own internal state of the handler.
-Build System Changes
---------------------
+### Build System Changes
>From dab2b7eb351dcc4ba6b7b3f1cc2181b2c61f61c7 Mon Sep 17 00:00:00 2001
From: s4chinjha <s4chinjha at gmail.com>
Date: Wed, 21 Oct 2026 03:27:57 +0530
Subject: [PATCH 3/3] [libc++][docs] Fix release notes link syntax
---
libcxx/docs/ReleaseNotes/21.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libcxx/docs/ReleaseNotes/21.md b/libcxx/docs/ReleaseNotes/21.md
index 07ff107b47ed0c..f17216f0110381 100644
--- a/libcxx/docs/ReleaseNotes/21.md
+++ b/libcxx/docs/ReleaseNotes/21.md
@@ -94,7 +94,7 @@ see the [releases page](https://llvm.org/releases/).
- 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`
+- `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.
More information about the libcxx-commits
mailing list