[libc++] Implement format_error.

[Mordante]

Summary

This is the first step at implementing <format>. It adds the <format> header
and implements the format_error. class.

Implemnts parts of:
-P0645 Text Formatting

[miscco]

libcxx/include/format

232

It pains me to see this in C++20 feature

[Mordante]

Thanks for the review!

It seems a build bot fails. I'll investigate this further.

libcxx/include/format

232

I agree.

[Mordante]

Properly guard the code in format.cpp to only be used in C++20 mode.
Update the x86_64 ABI list.
Note the Apple ABI list is still out of date.

[curdeius]

To fix Apple back-deployment build, you'll need to mark your test with sth like:

// This test requires the dylib support introduced in D92214.
// XFAIL: with_system_cxx_lib=macosx10.15
// XFAIL: with_system_cxx_lib=macosx10.14
// XFAIL: with_system_cxx_lib=macosx10.13
// XFAIL: with_system_cxx_lib=macosx10.12
// XFAIL: with_system_cxx_lib=macosx10.11
// XFAIL: with_system_cxx_lib=macosx10.10
// XFAIL: with_system_cxx_lib=macosx10.9

because this build uses a released dylibs for the given version of macOS (here 10.9) and does not use whatever changes you put in src/.
So, in your case, the dtor nor the vtable of format_error is just not in the libc++.dylib that the tests use.
Hence the error message: dyld: Symbol not found: __ZTVNSt3__112format_errorE.

[Mordante]

In D92214#2420187, @curdeius wrote:

To fix Apple back-deployment build, you'll need to mark your test with sth like:

Thanks for the hint!

[Mordante]

Disable the Apple unit tests as suggested by @curdeius.
Formatted the manually written code with the .clang-format settings as proposed in D92229.

[ldionne]

Looks okay except for the synopsis nitpick, however as you say the Apple ABI list needs to be updated. If you rebase on top of master and re-submit, the failing jobs should tell you what symbols you're missing (in the logs). You could add them to the Apple ABI lists (please make sure to sort :-), and the CI should pass.

libcxx/include/format

17

The synopsis should only contain the parts that we implement. Or at least it's always been my impression.

[Mordante]

Rebase to trigger CI to generate the Apple ABI list.

[Mordante]

Thanks for the review.

In D92214#2426796, @ldionne wrote:

Looks okay except for the synopsis nitpick, however as you say the Apple ABI list needs to be updated. If you rebase on top of master and re-submit, the failing jobs should tell you what symbols you're missing (in the logs). You could add them to the Apple ABI lists (please make sure to sort :-), and the CI should pass.

@curdeius already committed the Buildkite ABI list improvements. So I copied the Apple ABI list artifact of the failed build :-) A lot easier than looking in the logs ;-)

libcxx/include/format

17

I'll update it in the next version.

[Mordante]

Updated the Apple ABI list and synopsis.

[curdeius]

libcxx/test/libcxx/double_include.sh.cpp

78

I almost forgot. Please have a look at the updated notes. There are two more places to add a new header.
https://libcxx.llvm.org/docs/Contributing.html#id3

[Mordante]

libcxx/test/libcxx/double_include.sh.cpp

78

Thanks! I'll update them in the next release. I'll also properly move the format header to keep them sorted.

[Mordante]

Implement all new header tests as suggested by @curdeius.

[curdeius]

LGTM

[Mordante]

@ldionne Can you have a look?

[Mordante]

Rebased.

[ldionne]

libcxx/include/format

17

Ping on this. We should remove the part of the synopsis that we don't implement (and of course we should re-add it as we implement more parts of it).

libcxx/src/format.cpp

14

We muse always compile this into the library, so there should be no guard. The built library must be able to work with headers in any standard mode, which means it needs to contain the required definitions for all standard modes. Furthermore, this is always true anyway since we compile the library with C++20.

[Mordante]

libcxx/include/format

17

I thought I had done this, but apparently not :-( I've removed it now.

libcxx/src/format.cpp

14

Thanks for the explanation. I wasn't aware the library should always be compiled with the latest C++ version.

[Mordante]

• Addresses review comments:
  • Removed unimplemented part of the synopsis
  • Removed cpp version check in format.cpp
• Replace c++ version number 2a with 20 where appropriate. This reflects changes done in main by unrelated commits.
• Rebased to trigger CI again.

[Mordante]

Rebase to trigger CI. The last build failed, but so did main.

[ldionne]

Thanks! The CI has been a bit grumpy the last days, but hopefully it should be back to normal now.

[thakis]

Hello, this again breaks building with -std=c++17: the cpp file has the definition but not the declaration in that case. Should libc++ sources be built with -std=c++20? Or should the cpp file also check _LIBCPP_STD_VER?

[thakis]

To answer my question: Yes, C++20 should be used, see 3b625060fc915.

[thakis]

... but it looks like CXX_STANDARD_REQUIRED should now become YES after this change here, right?

[Mordante]

In D92214#2528690, @thakis wrote:

Hello, this again breaks building with -std=c++17: the cpp file has the definition but not the declaration in that case. Should libc++ sources be built with -std=c++20? Or should the cpp file also check _LIBCPP_STD_VER?

I had this in my original version, but I removed it after review this review comment
https://reviews.llvm.org/D92214#inline-887948

To answer my question: Yes, C++20 should be used, see 3b625060fc915.

That doesn't really answer the question since that made C++20 preferred but not mandatory. That was the intention.

@ldionne Can you clarify the status of libc++'s C++20 requirements. If optional should I re-add the version check macro's in the .cpp file?

[ldionne]

In D92214#2528876, @Mordante wrote:

In D92214#2528690, @thakis wrote:

Hello, this again breaks building with -std=c++17: the cpp file has the definition but not the declaration in that case. Should libc++ sources be built with -std=c++20? Or should the cpp file also check _LIBCPP_STD_VER?

I had this in my original version, but I removed it after review this review comment
https://reviews.llvm.org/D92214#inline-887948

To answer my question: Yes, C++20 should be used, see 3b625060fc915.

That doesn't really answer the question since that made C++20 preferred but not mandatory. That was the intention.

@ldionne Can you clarify the status of libc++'s C++20 requirements. If optional should I re-add the version check macro's in the .cpp file?

Ugh. That's tough.

First, we can't always build as C++17 because then the dylib can't provide the features it needs to support c++20 (unless we jump through some hoops to compile with C++17 but enable stuff like char8_t, which is a no-no).
Second, allowing the library to be built either as C++17 or C++20, but provide different features depending on that, is also a pretty bad idea because then someone could link against that library, try to use some C++20 feature from the headers, and they would get a linker error. That's bad too. That's the current state of things with char8_t support AFAICT (@curdeius can confirm or infirm).
Third, people are going to be grumpy if we bump the requirement of building libc++ to C++20. I personally think that's reasonable, but this is obviously causing some trouble since @thakis is here. @thakis, can you explain what's the issue with building libc++ with C++20? I assume Chrome is using an older compiler that doesn't support c++20 yet?

[curdeius]

In D92214#2529001, @ldionne wrote:

Second, allowing the library to be built either as C++17 or C++20, but provide different features depending on that, is also a pretty bad idea because then someone could link against that library, try to use some C++20 feature from the headers, and they would get a linker error. That's bad too. That's the current state of things with char8_t support AFAICT (@curdeius can confirm or infirm).

Indeed, not using C++20 to compile the library would prevent us from implementing any C++20 features, char8_t support is one example, format_error is another.

Just my 2 cents.
Personally, as a sort of transition before requiring C++20 to compile libc++, I'd go for allowing the build in both C++17 and C++20.
BTW, there's already some amount of #if _LIBCPP_STD_VER > 11 and #ifndef _LIBCPP_NO_HAS_CHAR8_T checks in src/.
So people already can shoot themselves in a foot compiling and linking in different modes.
I'd argue that compiling the library in C++17 and using it in C++20 (and using these C++20 features) is silly.
I imagine it would be to much of a pain to guarantee that it works the other way round (compiling in C++20, using in C++17), but it should work in most of the cases.

Anyway, guarding C++20 features in src/ so as to allow the build and use in C++17 would probably be the way to go for the moment.
I know it's a maintenance burden though.

[Mordante]

I agree it would be nice to allow C++17 and C++20 for a limited time. It would be a bit of a maintenance burden, but I feel it benefits our users. I think we can state users are allowed to use C++17, but it's not officially supported. We could make a Cmake switch to opt-in to this behavior, but I feel that would be overkill.

I think once C++20 becomes mandatory we should remove the #if _LIBCPP_STD_VER > 17 from the files in src. Then the extra burden is only there for a limited time.

I'll make a patch to remove the 2 occurrences of #if _LIBCPP_STD_VER > 11 from src.

[ldionne]

I'd argue that compiling the library in C++17 and using it in C++20 (and using these C++20 features) is silly.

Yes, I agree.

I imagine it would be to much of a pain to guarantee that it works the other way round (compiling in C++20, using in C++17), but it should work in most of the cases.

No, that's actually what we do all the time. We build the dylib in C++20, but users are free to use the headers in C++03, C++11, C++14, C++17 or C++20 mode.

@Mordante Feel free to add back the check. However, in the short/mid term, I want the default way to build libc++ to switch to the bootstrap build (i.e. the Runtimes build). Once that happens, we will be guaranteed that we always build the dylib with basically Clang trunk (or a recent compiler anyway). It won't make sense anymore to allow anything but the latest standard then. It is indeed a maintenance burden to support more than that, and a burden that (I claim) doesn't provide much benefit. If you're compiling the C++ Standard Library from scratch, I think you have the time and dedication to keep your compiler up to date.

[curdeius]

In D92214#2530748, @ldionne wrote:

I imagine it would be to much of a pain to guarantee that it works the other way round (compiling in C++20, using in C++17), but it should work in most of the cases.

No, that's actually what we do all the time. We build the dylib in C++20, but users are free to use the headers in C++03, C++11, C++14, C++17 or C++20 mode.

Yes, right. A brain fart from my side.

[Mordante]

In D92214#2530748, @ldionne wrote:

@Mordante Feel free to add back the check.

I'll commit a fix.

However, in the short/mid term, I want the default way to build libc++ to switch to the bootstrap build (i.e. the Runtimes build). Once that happens, we will be guaranteed that we always build the dylib with basically Clang trunk (or a recent compiler anyway). It won't make sense anymore to allow anything but the latest standard then. It is indeed a maintenance burden to support more than that, and a burden that (I claim) doesn't provide much benefit. If you're compiling the C++ Standard Library from scratch, I think you have the time and dedication to keep your compiler up to date.

Sounds good to me.

libcxx/docs/Cxx2aStatusPaperStatus.csv

 "`P1463R1 <https://wg21.link/P1463R1>`__","LWG","Mandating the Standard Library: Clause 21 - Containers library","Kona","",""
 "`P1464R1 <https://wg21.link/P1464R1>`__","LWG","Mandating the Standard Library: Clause 22 - Iterators library","Kona","|Complete|","9.0"
 "","","","","",""
 "`P0325 <https://wg21.link/P0325>`__","LWG","to_array from LFTS with updates","Cologne","|Complete|","10.0"
 "`P0408 <https://wg21.link/P0408>`__","LWG","Efficient Access to basic_stringbuf's Buffer","Cologne","",""
 "`P0466 <https://wg21.link/P0466>`__","LWG","Layout-compatibility and Pointer-interconvertibility Traits","Cologne","",""
 "`P0553 <https://wg21.link/P0553>`__","LWG","Bit operations","Cologne","|Complete|","9.0"
 "`P0631 <https://wg21.link/P0631>`__","LWG","Math Constants","Cologne","|Complete|","11.0"
-"`P0645 <https://wg21.link/P0645>`__","LWG","Text Formatting","Cologne","",""
+"`P0645 <https://wg21.link/P0645>`__","LWG","Text Formatting","Cologne","|In Progress|",""
 "`P0660 <https://wg21.link/P0660>`__","LWG","Stop Token and Joining Thread, Rev 10","Cologne","",""
 "`P0784 <https://wg21.link/P0784>`__","CWG","More constexpr containers","Cologne","|Complete|","12.0"
 "`P0980 <https://wg21.link/P0980>`__","LWG","Making std::string constexpr","Cologne","",""
 "`P1004 <https://wg21.link/P1004>`__","LWG","Making std::vector constexpr","Cologne","",""
 "`P1035 <https://wg21.link/P1035>`__","LWG","Input Range Adaptors","Cologne","",""
 "`P1065 <https://wg21.link/P1065>`__","LWG","Constexpr INVOKE","Cologne","",""
 "`P1135 <https://wg21.link/P1135>`__","LWG","The C++20 Synchronization Library","Cologne","|Complete|",""
 "`P1207 <https://wg21.link/P1207>`__","LWG","Movability of Single-pass Iterators","Cologne","",""

libcxx/docs/FeatureTestMacroTable.rst

.. table:: Current Status
     ``__cpp_lib_constexpr_utility``                   ``201811L``
     ------------------------------------------------- -----------------
     ``__cpp_lib_destroying_delete``                   ``201806L``
     ------------------------------------------------- -----------------
     ``__cpp_lib_endian``                              ``201907L``
     ------------------------------------------------- -----------------
     ``__cpp_lib_erase_if``                            ``202002L``
     ------------------------------------------------- -----------------
+    ``__cpp_lib_format``                              *unimplemented*
+    ------------------------------------------------- -----------------
     ``__cpp_lib_generic_unordered_lookup``            ``201811L``
     ------------------------------------------------- -----------------
     ``__cpp_lib_int_pow2``                            ``202002L``
     ------------------------------------------------- -----------------
     ``__cpp_lib_interpolate``                         ``201902L``
     ------------------------------------------------- -----------------
     ``__cpp_lib_is_constant_evaluated``               ``201811L``
     ------------------------------------------------- -----------------

libcxx/include/CMakeLists.txt

set(files
   experimental/utility
   experimental/vector
   ext/__hash
   ext/hash_map
   ext/hash_set
   fenv.h
   filesystem
   float.h
+  format
   forward_list
   fstream
   functional
   future
   initializer_list
   inttypes.h
   iomanip
   ios

libcxx/include/format

+// -*- C++ -*-
+//===--------------------------- format -----------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBCPP_FORMAT
+#define _LIBCPP_FORMAT
+
+/*
+
+namespace std {
+  // [format.context], class template basic_format_context
+  template<class Out, class charT> class basic_format_context;
+  using format_context = basic_format_context<unspecified, char>;
+  using wformat_context = basic_format_context<unspecified, wchar_t>;
+
+  // [format.args], class template basic_format_args
+  template<class Context> class basic_format_args;
+  using format_args = basic_format_args<format_context>;
+  using wformat_args = basic_format_args<wformat_context>;
+
+  template<class Out, class charT>
+    using format_args_t = basic_format_args<basic_format_context<Out, charT>>;
+
+  // [format.functions], formatting functions
+  template<class... Args>
+    string format(string_view fmt, const Args&... args);
+  template<class... Args>
+    wstring format(wstring_view fmt, const Args&... args);
+  template<class... Args>
+    string format(const locale& loc, string_view fmt, const Args&... args);
+  template<class... Args>
+    wstring format(const locale& loc, wstring_view fmt, const Args&... args);
+
+  string vformat(string_view fmt, format_args args);
+  wstring vformat(wstring_view fmt, wformat_args args);
+  string vformat(const locale& loc, string_view fmt, format_args args);
+  wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
+
+  template<class Out, class... Args>
+    Out format_to(Out out, string_view fmt, const Args&... args);
+  template<class Out, class... Args>
+    Out format_to(Out out, wstring_view fmt, const Args&... args);
+  template<class Out, class... Args>
+    Out format_to(Out out, const locale& loc, string_view fmt, const Args&... args);
+  template<class Out, class... Args>
+    Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);
+
+  template<class Out>
+    Out vformat_to(Out out, string_view fmt,
+                   format_args_t<type_identity_t<Out>, char> args);
+  template<class Out>
+    Out vformat_to(Out out, wstring_view fmt,
+                   format_args_t<type_identity_t<Out>, wchar_t> args);
+  template<class Out>
+    Out vformat_to(Out out, const locale& loc, string_view fmt,
+                   format_args_t<type_identity_t<Out>, char> args);
+  template<class Out>
+    Out vformat_to(Out out, const locale& loc, wstring_view fmt,
+                   format_args_t<type_identity_t<Out>, wchar_t> args);
+
+  template<class Out> struct format_to_n_result {
+    Out out;
+    iter_difference_t<Out> size;
+  };
+
+ template<class Out, class... Args>
+    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
+                                        string_view fmt, const Args&... args);
+  template<class Out, class... Args>
+    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
+                                        wstring_view fmt, const Args&... args);
+  template<class Out, class... Args>
+    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
+                                        const locale& loc, string_view fmt,
+                                        const Args&... args);
+  template<class Out, class... Args>
+    format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
+                                        const locale& loc, wstring_view fmt,
+                                        const Args&... args);
+
+  template<class... Args>
+    size_t formatted_size(string_view fmt, const Args&... args);
+  template<class... Args>
+    size_t formatted_size(wstring_view fmt, const Args&... args);
+  template<class... Args>
+    size_t formatted_size(const locale& loc, string_view fmt, const Args&... args);
+  template<class... Args>
+    size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
+
+  // [format.formatter], formatter
+  template<class T, class charT = char> struct formatter;
+
+  // [format.parse.ctx], class template basic_format_parse_context
+  template<class charT> class basic_format_parse_context;
+  using format_parse_context = basic_format_parse_context<char>;
+  using wformat_parse_context = basic_format_parse_context<wchar_t>;
+
+  // [format.arguments], arguments
+  // [format.arg], class template basic_format_arg
+  template<class Context> class basic_format_arg;
+
+  template<class Visitor, class Context>
+    see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
+
+  // [format.arg.store], class template format-arg-store
+  template<class Context, class... Args> struct format-arg-store;      // exposition only
+
+  template<class Context = format_context, class... Args>
+    format-arg-store<Context, Args...>
+      make_format_args(const Args&... args);
+  template<class... Args>
+    format-arg-store<wformat_context, Args...>
+      make_wformat_args(const Args&... args);
+
+  // [format.error], class format_error
+  class format_error;
+}
+
+namespace std {
+  template<class charT>
+  class basic_format_parse_context {
+  public:
+    using char_type = charT;
+    using const_iterator = typename basic_string_view<charT>::const_iterator;
+    using iterator = const_iterator;
+
+  private:
+    iterator begin_;                                    // exposition only
+    iterator end_;                                      // exposition only
+    enum indexing { unknown, manual, automatic };       // exposition only
+    indexing indexing_;                                 // exposition only
+    size_t next_arg_id_;                                // exposition only
+    size_t num_args_;                                   // exposition only
+
+  public:
+    constexpr explicit basic_format_parse_context(basic_string_view<charT> fmt,
+                                                  size_t num_args = 0) noexcept;
+    basic_format_parse_context(const basic_format_parse_context&) = delete;
+    basic_format_parse_context& operator=(const basic_format_parse_context&) = delete;
+
+    constexpr const_iterator begin() const noexcept;
+    constexpr const_iterator end() const noexcept;
+    constexpr void advance_to(const_iterator it);
+
+    constexpr size_t next_arg_id();
+    constexpr void check_arg_id(size_t id);
+  };
+}
+
+namespace std {
+  template<class Context>
+  class basic_format_arg {
+  public:
+    class handle;
+
+  private:
+    using char_type = typename Context::char_type;                              // exposition only
+
+    variant<monostate, bool, char_type,
+            int, unsigned int, long long int, unsigned long long int,
+            float, double, long double,
+            const char_type*, basic_string_view<char_type>,
+            const void*, handle> value;                                         // exposition only
+
+    template<class T> explicit basic_format_arg(const T& v) noexcept;           // exposition only
+    explicit basic_format_arg(float n) noexcept;                                // exposition only
+    explicit basic_format_arg(double n) noexcept;                               // exposition only
+    explicit basic_format_arg(long double n) noexcept;                          // exposition only
+    explicit basic_format_arg(const char_type* s);                              // exposition only
+
+    template<class traits>
+      explicit basic_format_arg(
+        basic_string_view<char_type, traits> s) noexcept;                       // exposition only
+
+    template<class traits, class Allocator>
+      explicit basic_format_arg(
+        const basic_string<char_type, traits, Allocator>& s) noexcept;          // exposition only
+
+    explicit basic_format_arg(nullptr_t) noexcept;                              // exposition only
+
+    template<class T>
+      explicit basic_format_arg(const T* p) noexcept;                           // exposition only
+
+  public:
+    basic_format_arg() noexcept;
+
+    explicit operator bool() const noexcept;
+  };
+}
+
+namespace std {
+  template<class Context, class... Args>
+  struct format-arg-store {      // exposition only
+    array<basic_format_arg<Context>, sizeof...(Args)> args;
+  };
+}
+
+namespace std {
+  class format_error : public runtime_error {
+  public:
+    explicit format_error(const string& what_arg);
+    explicit format_error(const char* what_arg);
+  };
+}
+*/
+
+#include <__config>
+#include <stdexcept>
+#include <version>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#pragma GCC system_header
+#endif
+
+_LIBCPP_PUSH_MACROS
+#include <__undef_macros>
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+#if _LIBCPP_STD_VER > 17
+
+class _LIBCPP_EXCEPTION_ABI format_error
+    : public runtime_error
+{
+public:
+  _LIBCPP_INLINE_VISIBILITY explicit format_error(const string& __s)
+      : runtime_error(__s) {}
+  _LIBCPP_INLINE_VISIBILITY explicit format_error(const char* __s)
+      : runtime_error(__s) {}
+  virtual ~format_error() noexcept;
+};
+
+#endif //_LIBCPP_STD_VER > 17
+
+_LIBCPP_END_NAMESPACE_STD
+
+_LIBCPP_POP_MACROS
+
+#endif // _LIBCPP_FORMAT

libcxx/include/module.modulemap

module std [system] {
   module execution {
     header "execution"
     export *
   }
   module filesystem {
     header "filesystem"
     export *
   }
+  module format {
+    header "format"
+    export *
+  }
   module forward_list {
     header "forward_list"
     export initializer_list
     export *
   }
   module fstream {
     header "fstream"
     export *

libcxx/include/version

 __cpp_lib_enable_shared_from_this                       201603L <memory>
 __cpp_lib_endian                                        201907L <bit>
 __cpp_lib_erase_if                                      202002L <string> <deque> <forward_list>
                                                                 <list> <vector> <map>
                                                                 <set> <unordered_map> <unordered_set>
 __cpp_lib_exchange_function                             201304L <utility>
 __cpp_lib_execution                                     201603L <execution>
 __cpp_lib_filesystem                                    201703L <filesystem>
+__cpp_lib_format                                        201907L <format>
 __cpp_lib_gcd_lcm                                       201606L <numeric>
 __cpp_lib_generic_associative_lookup                    201304L <map> <set>
 __cpp_lib_generic_unordered_lookup                      201811L <unordered_map> <unordered_set>
 __cpp_lib_hardware_interference_size                    201703L <new>
 __cpp_lib_has_unique_object_representations             201606L <type_traits>
 __cpp_lib_hypot                                         201603L <cmath>
 __cpp_lib_incomplete_container_elements                 201505L <forward_list> <list> <vector>
 __cpp_lib_int_pow2                                      202002L <bit>

 // # define __cpp_lib_constexpr_misc                       201811L
 // # define __cpp_lib_constexpr_swap_algorithms            201806L
 # define __cpp_lib_constexpr_utility                    201811L
 # if _LIBCPP_STD_VER > 17 && defined(__cpp_impl_destroying_delete) && __cpp_impl_destroying_delete >= 201806L
 #   define __cpp_lib_destroying_delete                  201806L
 # endif
 # define __cpp_lib_endian                               201907L
 # define __cpp_lib_erase_if                             202002L
+// # define __cpp_lib_format                               201907L
 # define __cpp_lib_generic_unordered_lookup             201811L
 # define __cpp_lib_int_pow2                             202002L
 # define __cpp_lib_interpolate                          201902L
 # if !defined(_LIBCPP_HAS_NO_BUILTIN_IS_CONSTANT_EVALUATED)
 #   define __cpp_lib_is_constant_evaluated              201811L
 # endif
 # define __cpp_lib_list_remove_return_type              201806L
 # if defined(__cpp_concepts) && __cpp_concepts >= 201811L

libcxx/lib/abi/x86_64-unknown-linux-gnu.v1.abilist

 {'is_defined': True, 'name': '_ZNSt3__112ctype_bynameIcED2Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112ctype_bynameIwEC1EPKcm', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112ctype_bynameIwEC1ERKNS_12basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEEEm', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112ctype_bynameIwEC2EPKcm', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112ctype_bynameIwEC2ERKNS_12basic_stringIcNS_11char_traitsIcEENS_9allocatorIcEEEEm', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112ctype_bynameIwED0Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112ctype_bynameIwED1Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112ctype_bynameIwED2Ev', 'type': 'FUNC'}
+{'is_defined': True, 'name': '_ZNSt3__112format_errorD0Ev', 'type': 'FUNC'}
+{'is_defined': True, 'name': '_ZNSt3__112format_errorD1Ev', 'type': 'FUNC'}
+{'is_defined': True, 'name': '_ZNSt3__112format_errorD2Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112future_errorC1ENS_10error_codeE', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112future_errorC2ENS_10error_codeE', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112future_errorD0Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112future_errorD1Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112future_errorD2Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZNSt3__112placeholders2_1E', 'size': 1, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZNSt3__112placeholders2_2E', 'size': 1, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZNSt3__112placeholders2_3E', 'size': 1, 'type': 'OBJECT'}

 {'is_defined': True, 'name': '_ZTINSt3__111__money_getIwEE', 'size': 16, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__111__money_putIcEE', 'size': 16, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__111__money_putIwEE', 'size': 16, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__111regex_errorE', 'size': 24, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__112bad_weak_ptrE', 'size': 24, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__112codecvt_baseE', 'size': 16, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__112ctype_bynameIcEE', 'size': 24, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__112ctype_bynameIwEE', 'size': 24, 'type': 'OBJECT'}
+{'is_defined': True, 'name': '_ZTINSt3__112format_errorE', 'size': 24, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__112future_errorE', 'size': 24, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__112strstreambufE', 'size': 24, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__112system_errorE', 'size': 24, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__113basic_filebufIcNS_11char_traitsIcEEEE', 'size': 24, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__113basic_istreamIcNS_11char_traitsIcEEEE', 'size': 40, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__113basic_istreamIwNS_11char_traitsIwEEEE', 'size': 40, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__113basic_ostreamIcNS_11char_traitsIcEEEE', 'size': 40, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTINSt3__113basic_ostreamIwNS_11char_traitsIwEEEE', 'size': 40, 'type': 'OBJECT'}

 {'is_defined': True, 'name': '_ZTSNSt3__111__money_getIwEE', 'size': 25, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__111__money_putIcEE', 'size': 25, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__111__money_putIwEE', 'size': 25, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__111regex_errorE', 'size': 22, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__112bad_weak_ptrE', 'size': 23, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__112codecvt_baseE', 'size': 23, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__112ctype_bynameIcEE', 'size': 26, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__112ctype_bynameIwEE', 'size': 26, 'type': 'OBJECT'}
+{'is_defined': True, 'name': '_ZTSNSt3__112format_errorE', 'size': 23, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__112future_errorE', 'size': 23, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__112strstreambufE', 'size': 23, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__112system_errorE', 'size': 23, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__113basic_filebufIcNS_11char_traitsIcEEEE', 'size': 47, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__113basic_istreamIcNS_11char_traitsIcEEEE', 'size': 47, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__113basic_istreamIwNS_11char_traitsIwEEEE', 'size': 47, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__113basic_ostreamIcNS_11char_traitsIcEEEE', 'size': 47, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTSNSt3__113basic_ostreamIwNS_11char_traitsIwEEEE', 'size': 47, 'type': 'OBJECT'}

 {'is_defined': True, 'name': '_ZTVNSt3__110moneypunctIcLb1EEE', 'size': 112, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__110moneypunctIwLb0EEE', 'size': 112, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__110moneypunctIwLb1EEE', 'size': 112, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__110ostrstreamE', 'size': 80, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__111regex_errorE', 'size': 40, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__112bad_weak_ptrE', 'size': 40, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__112ctype_bynameIcEE', 'size': 104, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__112ctype_bynameIwEE', 'size': 136, 'type': 'OBJECT'}
+{'is_defined': True, 'name': '_ZTVNSt3__112format_errorE', 'size': 40, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__112future_errorE', 'size': 40, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__112strstreambufE', 'size': 128, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__112system_errorE', 'size': 40, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__113basic_filebufIcNS_11char_traitsIcEEEE', 'size': 128, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__113basic_istreamIcNS_11char_traitsIcEEEE', 'size': 80, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__113basic_istreamIwNS_11char_traitsIwEEEE', 'size': 80, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__113basic_ostreamIcNS_11char_traitsIcEEEE', 'size': 80, 'type': 'OBJECT'}
 {'is_defined': True, 'name': '_ZTVNSt3__113basic_ostreamIwNS_11char_traitsIwEEEE', 'size': 80, 'type': 'OBJECT'}

 {'is_defined': True, 'name': '_ZTv0_n24_NSt3__113basic_ostreamIcNS_11char_traitsIcEEED0Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZTv0_n24_NSt3__113basic_ostreamIcNS_11char_traitsIcEEED1Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZTv0_n24_NSt3__113basic_ostreamIwNS_11char_traitsIwEEED0Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZTv0_n24_NSt3__113basic_ostreamIwNS_11char_traitsIwEEED1Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZTv0_n24_NSt3__114basic_iostreamIcNS_11char_traitsIcEEED0Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZTv0_n24_NSt3__114basic_iostreamIcNS_11char_traitsIcEEED1Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZTv0_n24_NSt3__19strstreamD0Ev', 'type': 'FUNC'}
 {'is_defined': True, 'name': '_ZTv0_n24_NSt3__19strstreamD1Ev', 'type': 'FUNC'}
 No newline at end of file

libcxx/src/CMakeLists.txt

 set(LIBCXX_LIB_CMAKEFILES_DIR "${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}"  PARENT_SCOPE)
 
 # Get sources
 set(LIBCXX_SOURCES
   algorithm.cpp
   any.cpp
   atomic.cpp
   barrier.cpp
   bind.cpp
   charconv.cpp
   chrono.cpp
   condition_variable.cpp
   condition_variable_destructor.cpp
   exception.cpp
+  format.cpp
   functional.cpp
   future.cpp
   hash.cpp
   include/apple_availability.h
   include/atomic_support.h
   include/config_elast.h
   include/refstring.h
   memory.cpp

libcxx/src/format.cpp

+//===------------------------- format.cpp ---------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "format"
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+#if _LIBCPP_STD_VER > 17
+
+format_error::~format_error() noexcept = default;
+
+#endif //_LIBCPP_STD_VER > 17
+
+_LIBCPP_END_NAMESPACE_STD

libcxx/test/libcxx/double_include.sh.cpp

 #include <deque>
 #include <errno.h>
 #include <exception>
 #include <execution>
 #include <fenv.h>
 #include <filesystem>
 #include <float.h>
 #include <forward_list>
+#include <format>
 #include <functional>
 #ifndef _LIBCPP_HAS_NO_THREADS
 #include <future>
 #endif
 #include <initializer_list>
 #include <inttypes.h>
 #include <iosfwd>
 #include <iterator>

libcxx/test/std/language.support/support.limits/support.limits.general/format.version.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// WARNING: This test was generated by generate_feature_test_macro_components.py
+// and should not be edited manually.
+
+// <format>
+
+// Test the feature test macros defined by <format>
+
+/*  Constant            Value
+    __cpp_lib_format    201907L [C++2a]
+*/
+
+#include <format>
+#include "test_macros.h"
+
+#if TEST_STD_VER < 14
+
+# ifdef __cpp_lib_format
+#   error "__cpp_lib_format should not be defined before c++2a"
+# endif
+
+#elif TEST_STD_VER == 14
+
+# ifdef __cpp_lib_format
+#   error "__cpp_lib_format should not be defined before c++2a"
+# endif
+
+#elif TEST_STD_VER == 17
+
+# ifdef __cpp_lib_format
+#   error "__cpp_lib_format should not be defined before c++2a"
+# endif
+
+#elif TEST_STD_VER > 17
+
+# if !defined(_LIBCPP_VERSION)
+#   ifndef __cpp_lib_format
+#     error "__cpp_lib_format should be defined in c++2a"
+#   endif
+#   if __cpp_lib_format != 201907L
+#     error "__cpp_lib_format should have the value 201907L in c++2a"
+#   endif
+# else // _LIBCPP_VERSION
+#   ifdef __cpp_lib_format
+#     error "__cpp_lib_format should not be defined because it is unimplemented in libc++!"
+#   endif
+# endif
+
+#endif // TEST_STD_VER > 17
+
+int main(int, char**) { return 0; }

libcxx/test/std/language.support/support.limits/support.limits.general/version.version.pass.cpp

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
 // WARNING: This test was generated by generate_feature_test_macro_components.py
/*  Constant                                       Value
     __cpp_lib_constexpr_utility                    201811L [C++2a]
     __cpp_lib_destroying_delete                    201806L [C++2a]
     __cpp_lib_enable_shared_from_this              201603L [C++17]
     __cpp_lib_endian                               201907L [C++2a]
     __cpp_lib_erase_if                             202002L [C++2a]
     __cpp_lib_exchange_function                    201304L [C++14]
     __cpp_lib_execution                            201603L [C++17]
     __cpp_lib_filesystem                           201703L [C++17]
+    __cpp_lib_format                               201907L [C++2a]
     __cpp_lib_gcd_lcm                              201606L [C++17]
     __cpp_lib_generic_associative_lookup           201304L [C++14]
     __cpp_lib_generic_unordered_lookup             201811L [C++2a]
     __cpp_lib_hardware_interference_size           201703L [C++17]
     __cpp_lib_has_unique_object_representations    201606L [C++17]
     __cpp_lib_hypot                                201603L [C++17]
     __cpp_lib_incomplete_container_elements        201505L [C++17]
     __cpp_lib_int_pow2                             202002L [C++2a]

 # ifdef __cpp_lib_execution
 #   error "__cpp_lib_execution should not be defined before c++17"
 # endif
 
 # ifdef __cpp_lib_filesystem
 #   error "__cpp_lib_filesystem should not be defined before c++17"
 # endif
 
+# ifdef __cpp_lib_format
+#   error "__cpp_lib_format should not be defined before c++2a"
+# endif
+
 # ifdef __cpp_lib_gcd_lcm
 #   error "__cpp_lib_gcd_lcm should not be defined before c++17"
 # endif
 
 # ifdef __cpp_lib_generic_associative_lookup
 #   error "__cpp_lib_generic_associative_lookup should not be defined before c++14"
 # endif
 

 # ifdef __cpp_lib_execution
 #   error "__cpp_lib_execution should not be defined before c++17"
 # endif
 
 # ifdef __cpp_lib_filesystem
 #   error "__cpp_lib_filesystem should not be defined before c++17"
 # endif
 
+# ifdef __cpp_lib_format
+#   error "__cpp_lib_format should not be defined before c++2a"
+# endif
+
 # ifdef __cpp_lib_gcd_lcm
 #   error "__cpp_lib_gcd_lcm should not be defined before c++17"
 # endif
 
 # ifndef __cpp_lib_generic_associative_lookup
 #   error "__cpp_lib_generic_associative_lookup should be defined in c++14"
 # endif
 # if __cpp_lib_generic_associative_lookup != 201304L

 
 # ifndef __cpp_lib_filesystem
 #   error "__cpp_lib_filesystem should be defined in c++17"
 # endif
 # if __cpp_lib_filesystem != 201703L
 #   error "__cpp_lib_filesystem should have the value 201703L in c++17"
 # endif
 
+# ifdef __cpp_lib_format
+#   error "__cpp_lib_format should not be defined before c++2a"
+# endif
+
 # ifndef __cpp_lib_gcd_lcm
 #   error "__cpp_lib_gcd_lcm should be defined in c++17"
 # endif
 # if __cpp_lib_gcd_lcm != 201606L
 #   error "__cpp_lib_gcd_lcm should have the value 201606L in c++17"
 # endif
 
 # ifndef __cpp_lib_generic_associative_lookup

 
 # ifndef __cpp_lib_filesystem
 #   error "__cpp_lib_filesystem should be defined in c++2a"
 # endif
 # if __cpp_lib_filesystem != 201703L
 #   error "__cpp_lib_filesystem should have the value 201703L in c++2a"
 # endif
 
+# if !defined(_LIBCPP_VERSION)
+#   ifndef __cpp_lib_format
+#     error "__cpp_lib_format should be defined in c++2a"
+#   endif
+#   if __cpp_lib_format != 201907L
+#     error "__cpp_lib_format should have the value 201907L in c++2a"
+#   endif
+# else // _LIBCPP_VERSION
+#   ifdef __cpp_lib_format
+#     error "__cpp_lib_format should not be defined because it is unimplemented in libc++!"
+#   endif
+# endif
+
 # ifndef __cpp_lib_gcd_lcm
 #   error "__cpp_lib_gcd_lcm should be defined in c++2a"
 # endif
 # if __cpp_lib_gcd_lcm != 201606L
 #   error "__cpp_lib_gcd_lcm should have the value 201606L in c++2a"
 # endif
 
 # ifndef __cpp_lib_generic_associative_lookup

libcxx/test/std/utilities/format/format.error/format.error.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17
+
+// <format>
+
+// class format_error;
+
+#include <format>
+#include <type_traits>
+#include <cstring>
+#include <string>
+#include <cassert>
+
+#include "test_macros.h"
+
+int main(int, char**)
+{
+    static_assert(std::is_base_of_v<std::runtime_error, std::format_error>);
+    static_assert(std::is_polymorphic_v<std::format_error>);
+
+    {
+    const char* msg = "format_error message c-string";
+    std::format_error e(msg);
+    assert(std::strcmp(e.what(), msg) == 0);
+    std::format_error e2(e);
+    assert(std::strcmp(e2.what(), msg) == 0);
+    e2 = e;
+    assert(std::strcmp(e2.what(), msg) == 0);
+    }
+    {
+    std::string msg("format_error message std::string");
+    std::format_error e(msg);
+    assert(e.what() == msg);
+    std::format_error e2(e);
+    assert(e2.what() == msg);
+    e2 = e;
+    assert(e2.what() == msg);
+    }
+
+    return 0;
+}

libcxx/test/std/utilities/format/version.compile.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// <format>
+
+#include <format>
+
+#include "test_macros.h"
+
+#ifndef _LIBCPP_VERSION
+#error _LIBCPP_VERSION not defined
+#endif
+
+// Required for MSVC internal test runner compatibility.
+int main(int, char**)
+{
+  return 0;
+}

libcxx/utils/generate_feature_test_macro_components.py

# C++2a
     "headers": ["atomic", "memory"],
     "unimplemented": True,
     "depends": "!defined(_LIBCPP_HAS_NO_THREADS)",
     "internal_depends": "!defined(_LIBCPP_HAS_NO_THREADS)",
    }, {
     "name": "__cpp_lib_constexpr_dynamic_alloc",
     "values": { "c++2a": int(201907) },
     "headers": ["memory"]
+   }, {
+    "name": "__cpp_lib_format",
+    "values": { "c++2a": int(201907) },
+    "headers": ["format"],
+    "unimplemented": True
    },
 ]], key=lambda tc: tc["name"])
 
 # Map from each header to the Lit annotations that should be used for
 # tests that include that header.
 #
 # For example, when threads are not supported, any feature-test-macro test
 # that includes <thread> should be marked as UNSUPPORTED, because including