[libcxx-commits] [libcxx] 23e604d - [libc++][docs] Document `std::optional` hardening (#218173)

[via libcxx-commits]

Author: William Tran-Viet
Date: 2026-08-25T11:56:35-04:00
New Revision: 23e604d2616963f75d67dbcc59a3182f6980c15e

URL: https://github.com/llvm/llvm-project/commit/23e604d2616963f75d67dbcc59a3182f6980c15e
DIFF: https://github.com/llvm/llvm-project/commit/23e604d2616963f75d67dbcc59a3182f6980c15e.diff

LOG: [libc++][docs] Document `std::optional` hardening (#218173)

Resolves #218041

Added: 
    

Modified: 
    libcxx/docs/ABIGuarantees.rst
    libcxx/docs/Hardening.rst

Removed: 
    


################################################################################
diff  --git a/libcxx/docs/ABIGuarantees.rst b/libcxx/docs/ABIGuarantees.rst
index c5ebe9ad76be8..ee9d1296757c4 100644
--- a/libcxx/docs/ABIGuarantees.rst
+++ b/libcxx/docs/ABIGuarantees.rst
@@ -223,8 +223,8 @@ This changes the ``iterator`` and ``const_iterator`` of ``array`` and ``string_v
 ``__wrap_iter`` instead, which makes it less likely for users to depend on non-portable implementation details. This is
 especially useful because enabling bounded iterators hardening requires code not to make these assumptions.
 
-``_LIBCPP_ABI_BOUNDED_ITERATORS``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STRING``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_VECTOR``, and ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY``
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+``_LIBCPP_ABI_BOUNDED_ITERATORS``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STRING``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_VECTOR``, ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_STD_ARRAY`` and ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_OPTIONAL``
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 These flags change the ``iterator`` member of various classes to reference hardened iterators instead. See the
 :ref:`hardening documentation <hardening>` for more details.
 

diff  --git a/libcxx/docs/Hardening.rst b/libcxx/docs/Hardening.rst
index 1360518379aef..8178a25e82648 100644
--- a/libcxx/docs/Hardening.rst
+++ b/libcxx/docs/Hardening.rst
@@ -440,6 +440,12 @@ CMake configuration time. The available options are:
 
   ABI impact: changes the iterator type of ``std::array``, its size and its layout.
 
+- ``_LIBCPP_ABI_BOUNDED_ITERATORS_IN_OPTIONAL`` -- changes the iterator type of ``std::optional`` to a
+  bounded iterator that keeps track of whether it's within the bounds of its container and asserts it
+  on every dereference and when performing iterator arithmetic.
+
+  ABI impact: changes the iterator type of ``std::optional``.
+
 ABI tags
 --------
 
@@ -531,7 +537,7 @@ Hardened containers status
       - ❌
     * - ``optional``
       - ✅
-      - N/A
+      - ✅
     * - ``function``
       - ❌
       - N/A