1=========================================
2Libc++ 15.0.0 (In-Progress) Release Notes
3=========================================
4
5.. contents::
6   :local:
7   :depth: 2
8
9Written by the `Libc++ Team <https://libcxx.llvm.org>`_
10
11.. warning::
12
13   These are in-progress notes for the upcoming libc++ 15 release.
14   Release notes for previous releases can be found on
15   `the Download Page <https://releases.llvm.org/download.html>`_.
16
17Introduction
18============
19
20This document contains the release notes for the libc++ C++ Standard Library,
21part of the LLVM Compiler Infrastructure, release 15.0.0. Here we describe the
22status of libc++ in some detail, including major improvements from the previous
23release and new feature work. For the general LLVM release notes, see `the LLVM
24documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
25be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.
26
27For more information about libc++, please see the `Libc++ Web Site
28<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
29
30Note that if you are reading this file from a Git checkout or the
31main Libc++ web page, this document applies to the *next* release, not
32the current one. To see the release notes for a specific release, please
33see the `releases page <https://llvm.org/releases/>`_.
34
35What's New in Libc++ 15.0.0?
36============================
37
38The main focus of the libc++ team has been to implement new C++20 and C++23
39features.
40
41The C++20 ``format`` library is feature complete, but not all Standard LWG
42issues have been addressed. Since it is expected that at least one of these
43issues will cause an ABI break the ``format`` library is considered
44experimental.
45
46The C++20 ``ranges`` library has progressed a lot since the last release and is
47almost complete. The ``ranges`` library is considered experimental.
48
49
50Implemented Papers
51------------------
52
53- P1004R2 - Making ``std::vector`` constexpr
54- P0627R6 - Function to mark unreachable code
55- P1165R1 - Make stateful allocator propagation more consistent for ``operator+(basic_string)``
56- P0674R1 - Support arrays in ``make_shared`` and ``allocate_shared``
57- P0980R1 - Making ``std::string`` constexpr
58- P2216R3 - ``std::format`` improvements
59- P0174R2 - Deprecating Vestigial Library Parts in C++17
60- N4190 - Removing ``auto_ptr``, ``random_shuffle()``, And Old ``<functional>`` Stuff
61- P0154R1 - Hardware inference size
62- P0618R0 - Deprecating ``<codecvt>``
63- P2418R2 - Add support for ``std::generator``-like types to ``std::format``
64- LWG3659 - Consider ``ATOMIC_FLAG_INIT`` undeprecation
65- P1423R3 - ``char8_t`` backward compatibility remediation
66- P2508R1 - Exposing ``std::basic-format-string``
67
68- Marked the following papers as "Complete" (note that some of those might have
69  been implemented in a previous release but not marked as such):
70
71    - P1207R4 - Movability of Single-pass Iterators
72    - P1474R1 - Helpful pointers for ``ContiguousIterator``
73    - P1522R1 - Iterator Difference Type and Integer Overflow
74    - P1523R1 - Views and Size Types
75    - P1456R1 - Move-only views
76    - P1870R1 - ``forwarding-range`` is too subtle
77    - P1878R1 - Constraining Readable Types
78    - P1970R2 - Consistency for ``size()`` functions: Add ``ranges::ssize``
79    - P1983R0 - Wording for GB301, US296, US292, US291, and US283
80
81Improvements and New Features
82-----------------------------
83
84- ``std::pop_heap`` now uses an algorithm known as "bottom-up heapsort" or
85  "heapsort with bounce" to reduce the number of comparisons, and rearranges
86  elements using move-assignment instead of ``std::swap``.
87
88- Libc++ now supports a variety of assertions that can be turned on to help catch
89  undefined behavior in user code. This new support is now separate from the old
90  (and incomplete) Debug Mode. Vendors can select whether the library they ship
91  should include assertions or not by default. For details, see
92  :ref:`the documentation <assertions-mode>` about this new feature.
93
94- Clang now implements the ``-fexperimental-library`` flag. This flag can be used to
95  enable experimental library features such as TSes and other in-progress work like
96  ``<ranges>`` and ``<format>``. Using this flag makes it unnecessary to manually link
97  against ``libc++experimental.a`` -- just use ``-fexperimental-library`` and the
98  compiler will do what's needed to make experimental features work. However, be
99  aware that experimental features are not stable!
100
101- The implementation of the function ``std::to_chars`` for integral types using
102  base 10 has moved from the dylib to the header. This means the function no
103  longer has a minimum deployment target.
104
105- The performance for ``std::to_chars``, for integral types using base 2, 8,
106  10, or 16 has been improved.
107
108- The functions ``std::from_chars`` and ``std::to_chars`` now have 128-bit integral
109  support.
110
111- The format functions (``std::format``, ``std::format_to``, ``std::format_to_n``, and
112  ``std::formatted_size``) now validate the format string at compile time.
113  When the format string is invalid this will make the code ill-formed instead
114  of throwing an exception at run-time.  (This does not affect the ``v``
115  functions.)
116
117- All format functions in ``<format>`` allow the usage of non-copyable types as
118  argument for the formatting functions. This change causes bit fields to become
119  invalid arguments for the formatting functions.
120
121- The ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_VOID_SPECIALIZATION`` macro has been added to allow
122  re-enabling the ``allocator<void>`` specialization. When used in conjunction with
123  ``_LIBCPP_ENABLE_CXX20_REMOVED_ALLOCATOR_MEMBERS``, this ensures that the members of
124  ``allocator<void>`` removed in C++20 can be accessed.
125
126- ``boyer_moore_searcher`` and ``boyer_moore_horspool_searcher`` have been implemented.
127
128- ``vector<bool>::const_reference``, ``vector<bool>::const_iterator::reference``
129  and ``bitset::const_reference`` are now aliases for `bool` in the unstable ABI,
130  which improves libc++'s conformance to the Standard.
131
132Deprecations and Removals
133-------------------------
134
135- The header ``<experimental/filesystem>`` has been removed. Instead, use
136  ``<filesystem>`` header. The associated macro
137  ``_LIBCPP_DEPRECATED_EXPERIMENTAL_FILESYSTEM`` has been removed too.
138
139- The C++14 function ``std::quoted(const char*)`` is no longer supported in
140  C++03 or C++11 modes.
141
142- Setting a custom debug handler with ``std::__libcpp_debug_function`` is not
143  supported anymore. Please migrate to using the new support for
144  :ref:`assertions <assertions-mode>` instead.
145
146- ``std::function`` has been removed in C++03. If you are using it, please remove usages
147  or upgrade to C++11 or later. It is possible to re-enable ``std::function`` in C++03 by defining
148  ``_LIBCPP_ENABLE_CXX03_FUNCTION``. This option will be removed in LLVM 16.
149
150- ``unary_function`` and ``binary_function`` are no longer available in C++17 and C++20.
151  They can be re-enabled by defining ``_LIBCPP_ENABLE_CXX17_REMOVED_UNARY_BINARY_FUNCTION``.
152  They are also marked as ``[[deprecated]]`` in C++11 and later. To disable deprecation warnings
153  you have to define ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS``. Note that this disables
154  all deprecation warnings.
155
156- The contents of ``<codecvt>``, ``wstring_convert`` and ``wbuffer_convert`` have been marked as deprecated.
157  To disable deprecation warnings you have to define ``_LIBCPP_DISABLE_DEPRECATION_WARNINGS``. Note that this
158  disables all deprecation warnings.
159
160- The ``_LIBCPP_DISABLE_EXTERN_TEMPLATE`` macro is not honored anymore when defined by
161  users of libc++. Instead, users not wishing to take a dependency on libc++ should link
162  against the static version of libc++, which will result in no dependency being
163  taken against the shared library.
164
165- The ``_LIBCPP_ABI_UNSTABLE`` macro has been removed in favour of setting
166  ``_LIBCPP_ABI_VERSION=2``. This should not have any impact on users because
167  they were not supposed to set ``_LIBCPP_ABI_UNSTABLE`` manually, however we
168  still feel that it is worth mentioning in the release notes in case some users
169  had been doing it.
170
171- The integer distributions ``binomial_distribution``, ``discrete_distribution``,
172  ``geometric_distribution``, ``negative_binomial_distribution``, ``poisson_distribution``,
173  and ``uniform_int_distribution`` now conform to the Standard by rejecting
174  template parameter types other than ``short``, ``int``, ``long``, ``long long``,
175  and the unsigned versions thereof. As an extension, ``int8_t``, ``__int128_t`` and
176  their unsigned versions are supported too. In particular, instantiating these
177  distributions with non-integer types like ``bool`` and ``char`` will not compile
178  anymore.
179
180Upcoming Deprecations and Removals
181----------------------------------
182
183- The ``_LIBCPP_DEBUG`` macro is not supported anymore. It will be honoured until
184  LLVM 16, and then it will be an error to define that macro. To enable basic
185  assertions (previously ``_LIBCPP_DEBUG=0``), please use ``_LIBCPP_ENABLE_ASSERTIONS=1``.
186  To enable the debug mode (previously ``_LIBCPP_DEBUG=1|2``), please ensure that
187  the library has been built with support for the debug mode, and it will be
188  enabled automatically (no need to define ``_LIBCPP_DEBUG``).
189
190- The experimental versions of ``boyer_moore_searcher`` and ``boyer_moore_horspool_searcher``
191  will be removed in LLVM 17. You can disable the deprecation warnings by defining
192  ``_LIBCPP_NO_EXPERIMENTAL_DEPRECATION_WARNING_SEARCHERS``.
193
194- The implementation of the Coroutines TS in ``std::experimental`` will be removed in LLVM 16.
195
196- Libc++ is getting ready to remove unnecessary transitive inclusions. This may
197  break your code in the future. To future-proof your code to these removals,
198  please compile your code with ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES`` defined
199  and fix any compilation error resulting from missing includes.
200
201ABI Affecting Changes
202---------------------
203
204- The ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` macro controlling whether we use an
205  emulation for ``std::nullptr_t`` in C++03 mode has been removed. After this change,
206  ``_LIBCPP_ABI_USE_CXX03_NULLPTR_EMULATION`` will not be honoured anymore and there
207  will be no way to opt back into the C++03 emulation of ``std::nullptr_t``.
208
209- On FreeBSD, NetBSD, DragonFlyBSD and Solaris, ``std::random_device`` is now implemented on
210  top of ``arc4random()`` instead of reading from ``/dev/urandom``. Any implementation-defined
211  token used when constructing a ``std::random_device`` will now be ignored instead of
212  interpreted as a file to read entropy from.
213
214- ``std::valarray``'s unary operators ``!``, ``+``, ``~`` and ``-`` now return an expression
215  object instead of a ``valarray``. This was done to fix an issue where any expression involving
216  other ``valarray`` operators and one of these unary operators would end up with a dangling
217  reference. This is a potential ABI break for code that exposes ``std::valarray`` on an ABI
218  boundary, specifically if the return type of an ABI-boundary function is ``auto``-deduced
219  from an expression involving unary operators on ``valarray``. If you are concerned by this,
220  you can audit whether your executable or library exports any function that returns a
221  ``valarray``, and if so ensure that any such function uses ``std::valarray`` directly
222  as a return type instead of relying on the type of ``valarray``-expressions, which is
223  not guaranteed by the Standard anyway.
224
225- By default, the legacy debug mode symbols are not provided with the library anymore. If
226  you are a vendor and need to re-enable them, please use the ``LIBCXX_ENABLE_BACKWARDS_COMPATIBILITY_DEBUG_MODE_SYMBOLS``
227  CMake flag, and contact the libc++ developers as this will be removed in LLVM 16.
228  Furthermore, please note that ``LIBCXX_ENABLE_DEBUG_MODE_SUPPORT`` is not honored anymore.
229
230Build System Changes
231--------------------
232
233- Support for standalone builds have been entirely removed from libc++, libc++abi and
234  libunwind. Please use :ref:`these instructions <build instructions>` for building
235  libc++, libc++abi and/or libunwind.
236
237- The ``{LIBCXX,LIBCXXABI,LIBUNWIND}_TARGET_TRIPLE``, ``{LIBCXX,LIBCXXABI,LIBUNWIND}_SYSROOT`` and
238  ``{LIBCXX,LIBCXXABI,LIBUNWIND}_GCC_TOOLCHAIN`` CMake variables have been removed. Instead, please
239  use the ``CMAKE_CXX_COMPILER_TARGET``, ``CMAKE_SYSROOT`` and ``CMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN``
240  variables provided by CMake.
241
242- Previously, the C++ ABI library headers would be installed inside ``<prefix>/include/c++/v1``
243  alongside the libc++ headers as part of building libc++. This is not the case anymore -- the
244  ABI library is expected to install its headers where it wants them as part of its own build.
245  Note that no action is required for most users, who build libc++ against libc++abi, since
246  libc++abi already installs its headers in the right location. However, vendors building
247  libc++ against alternate ABI libraries should make sure that their ABI library installs
248  its own headers.
249
250- The legacy testing configuration is now deprecated and will be removed in LLVM 16. For
251  most users, this should not have any impact. However, if you are testing libc++, libc++abi, or
252  libunwind in a configuration or on a platform that used to be supported by the legacy testing
253  configuration and isn't supported by one of the configurations in ``libcxx/test/configs``,
254  ``libcxxabi/test/configs``, or ``libunwind/test/configs``, please move to one of those
255  configurations or define your own.
256
257- MinGW DLL builds of libc++ no longer use dllimport in their headers, which
258  means that the same set of installed headers works for both DLL and static
259  linkage. This means that distributors finally can build both library
260  versions with a single CMake invocation.
261
262- The ``LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT`` configuration option has been removed. Indeed,
263  the risk of ODR violations from mixing different versions of libc++ in the same program has
264  been mitigated with a different technique that is simpler and does not have the drawbacks of
265  using internal linkage.
266