===========================================
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>`__)
- P1899R3: ``stride_view`` (`Github <https://llvm.org/PR105198>`__)
- 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 (partial): ``ranges::fold_left_first``, ``ranges::fold_left_first_with_iter``, ``ranges::fold_right`` are
  supported (`Github <https://llvm.org/PR105208>`__)
- P4144R1: Remove ``span``'s ``initializer_list`` constructor for C++26 (`Github <https://llvm.org/PR189612>`__)

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.

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

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.

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