libcxx/docs/ReleaseNotes/23.rst

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

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

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

.. warning::

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

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

This document contains the release notes for the libc++ C++ Standard Library,
part of the LLVM Compiler Infrastructure, release 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/>`_.

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

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

What's New in Libc++ 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
  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
  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
  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
  unprotected. This requires Clang 21 or later.

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.

- 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
----------------------------

- 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
  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
  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++.
  The implementation was donated by Microsoft and has been refactored to follow libc++ standards and conventions.

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

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
  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
  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
  (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
  pointer.

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