[libc++][format] Finish P0645 Text Formatting.

[Mordante]

Summary

This adjust the version macro and sets it as completed. All parts of the paper
have been implemented, except for the parts replaced by later papers and
LWG-issues.

Adjusted the synopsis to match the synopsis in the Standard. Not yet
implemented parts of P2216 and P2418 still use the P0645 wording.

Completes:

• P0645 Text Formatting

Depends on D115991

[vitaut]

All parts of the paper have been implemented

Is the floating-point formatting fully implemented? It relies on to_chars or equivalent functionality to be available.

[Mordante]

In D115999#3201842, @vitaut wrote:

All parts of the paper have been implemented

Is the floating-point formatting fully implemented? It relies on to_chars or equivalent functionality to be available.

It's fully implemented in D114001 using to_chars. The to_chars implementation has been provided by Microsoft and has one minor caveat; it casts a long double to a double so it doesn't format correctly. (On Windows both types have the same underlying type, so it works fine for Microsoft.) But I consider that an issue in to_chars and not in <format>. Improving to_chars's long double support is on my todo list.

[vitaut]

But I consider that an issue in to_chars and not in <format>.

Fair enough.

[• Quuxplusone]

libcxx/docs/ReleaseNotes.rst

43–45

Do we need to mention LIBCXX_ENABLE_INCOMPLETE_FEATURES here? I don't really know how it works.

libcxx/docs/Status/Cxx20.rst

44

[ldionne]

Upon second thought, I think it would be best to leave the feature-test macro undefined until we actually guarantee ABI/API stability. Otherwise, users will just start using it and it will be difficult for us to say "well it was not stable, you should have waited". FTMs are basically the only way to communicate with our users in that respect, so I think we should be careful about not-quite-accurate information.

[ldionne]

libcxx/docs/ReleaseNotes.rst

43–45

My understanding is that since the original format paper will effectively fully implemented, we would not use LIBCXX_ENABLE_INCOMPLETE_FEATURES here. Was that your intent @Mordante?

[Mordante]

libcxx/docs/ReleaseNotes.rst

43–45

I intend to keep it. We added that in LLVM 13 since std::format wasn't ABI stable, which it's still not. There are some ABI breaking LWG issues and papers retroactively accepted in C++20. At the moment there's even one ABI breaking LWG issue active https://cplusplus.github.io/LWG/issue3576. Having it not ABI stable also makes it easier to look at possible optimizations in the implementation. I expect to be able to finish all remaining work in the LLVM 15 timeframe.

We could montion the macro, it's not really a new feature, but might be a nice reminder. (We use the same feature flag for our ranges implementation.)

[Mordante]

Addresses review comments.

[h-vetinari]

Congratulations on landing this huge piece of work, and even more so in time for LLVM 14!

[ldionne]

In D115999#3267093, @h-vetinari wrote:

Congratulations on landing this huge piece of work, and even more so in time for LLVM 14!

Yes, absolutely, thanks a lot for your awesome work @Mordante. And thanks @vitaut for moving the reviews along.

[vitaut]

Great work, @Mordante! Can't wait to use more of std::format on gobolt.

[h-vetinari]

Just a nit/note before LLVM 14 branches: a few bullets in FormatPaper.csv should probably now be updated as well.

Confusingly, this CSV contains the actual chunks of the work, whereas FormatIssues.csv contains only the papers. Might be worth updating the names there, à la:

• FormatPaper.csv -> FormatTasks.csv (or FormatSections.csv)
• FormatIssues.csv -> FormatPapers.csv

[Mordante]

Thanks all!

A big thanks to @vitaut for reviewing. Your insights have helped to improve the implementation!
A big thanks to @ldionne to make sure I didn't overload some libc++ coding issues.

In D115999#3268066, @h-vetinari wrote:

Just a nit/note before LLVM 14 branches: a few bullets in FormatPaper.csv should probably now be updated as well.

Confusingly, this CSV contains the actual chunks of the work, whereas FormatIssues.csv contains only the papers. Might be worth updating the names there, à la:

• FormatPaper.csv -> FormatTasks.csv (or FormatSections.csv)
• FormatIssues.csv -> FormatPapers.csv

That was indeed on my todo list and I just updated them. I agree the naming of the files could be better. For now I keep them as is.

• The number of open C++20 papers is quite limited.
• For chrono and C++23 format/print related papers I hope/expect to use GitHub projects.

libcxx/docs/ReleaseNotes.rst

 see the `releases page <https://llvm.org/releases/>`_.
 
 What's New in Libc++ 14.0.0?
 ============================
 
 New Features
 ------------
 
-- There's initial support for the C++20 header ``<format>``. The implementation
-  is incomplete. Some functions are known to be inefficient; both in memory
-  usage and performance. The implementation is considered experimental and isn't
-  considered ABI stable.
+- There's support for the C++20 header ``<format>``. Some parts are still
+  missing, most notably the compile-time format string validation. Some
+  functions are known to be inefficient, both in memory usage and performance.
+  The implementation isn't API- or ABI-stable and therefore considered
+  experimental. (Some not-yet-implemented papers require an API-break.)
+  Vendors can still disable this header by turning the CMake option
+  `LIBCXX_ENABLE_INCOMPLETE_FEATURES` off.
 
 - There's a new CMake option ``LIBCXX_ENABLE_UNICODE`` to disable Unicode
   support in the ``<format>`` header. This only affects the estimation of the
   output width of the format functions.
 
 - Support for building libc++ on top of a C Standard Library that does not support ``wchar_t`` was
   added. This is useful for building libc++ in an embedded setting, and it adds itself to the various
   freestanding-friendly options provided by libc++.

libcxx/docs/Status/Cxx20.rst

 .. csv-table::
    :file: Cxx20Papers.csv
    :header-rows: 1
    :widths: auto
 
 .. note::
 
    .. [#note-P0600] P0600: The missing bits in P0600 are in |sect|\ [mem.res.class] and |sect|\ [mem.poly.allocator.class].
+   .. [#note-P0645] P0645: The paper is implemented but still marked as an incomplete feature. Not yet implemented LWG-issues will cause API and ABI breakage.
    .. [#note-P0966] P0966: It was previously erroneously marked as complete in version 8.0. See `bug 45368 <https://llvm.org/PR45368>`__.
    .. [#note-P0619] P0619: Only sections D.8, D.9, D.10 and D.13 are implemented. Sections D.4, D.7, D.11, D.12, and D.14 remain undone.
    .. [#note-P0883] P0883: shared_ptr and floating-point changes weren't applied as they themselves aren't implemented yet.
 
 
 .. _issues-status-cxx20:
 
 Library Working Group Issues Status
 ====================================
 
 .. csv-table::
    :file: Cxx20Issues.csv
    :header-rows: 1
    :widths: auto

libcxx/docs/Status/Cxx20Papers.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"
 "","","","","",""
 "`P0325R4 <https://wg21.link/P0325R4>`__","LWG","to_array from LFTS with updates","Cologne","|Complete|","10.0"
 "`P0408R7 <https://wg21.link/P0408R7>`__","LWG","Efficient Access to basic_stringbuf's Buffer","Cologne","",""
 "`P0466R5 <https://wg21.link/P0466R5>`__","LWG","Layout-compatibility and Pointer-interconvertibility Traits","Cologne","",""
 "`P0553R4 <https://wg21.link/P0553R4>`__","LWG","Bit operations","Cologne","|Complete|","9.0"
 "`P0631R8 <https://wg21.link/P0631R8>`__","LWG","Math Constants","Cologne","|Complete|","11.0"
-"`P0645R10 <https://wg21.link/P0645R10>`__","LWG","Text Formatting","Cologne","|In Progress|",""
+"`P0645R10 <https://wg21.link/P0645R10>`__","LWG","Text Formatting","Cologne","|Complete| [#note-P0645]_","14.0"
 "`P0660R10 <https://wg21.link/P0660R10>`__","LWG","Stop Token and Joining Thread, Rev 10","Cologne","",""
 "`P0784R7 <https://wg21.link/P0784R7>`__","CWG","More constexpr containers","Cologne","|Complete|","12.0"
 "`P0980R1 <https://wg21.link/P0980R1>`__","LWG","Making std::string constexpr","Cologne","",""
 "`P1004R2 <https://wg21.link/P1004R2>`__","LWG","Making std::vector constexpr","Cologne","",""
 "`P1035R7 <https://wg21.link/P1035R7>`__","LWG","Input Range Adaptors","Cologne","",""
 "`P1065R2 <https://wg21.link/P1065R2>`__","LWG","Constexpr INVOKE","Cologne","|Complete|","12.0"
 "`P1135R6 <https://wg21.link/P1135R6>`__","LWG","The C++20 Synchronization Library","Cologne","|Complete|","11.0"
 "`P1207R4 <https://wg21.link/P1207R4>`__","LWG","Movability of Single-pass Iterators","Cologne","",""

libcxx/docs/Status/FormatIssues.csv

 Number,Name,Assignee,Patch,Status,First released version
-`P0645 <https://wg21.link/P0645>`_,"Text Formatting",Mark de Wever,,|Partial|,
+`P0645 <https://wg21.link/P0645>`_,"Text Formatting",Mark de Wever,,|Complete|,Clang 14
 `P1652 <https://wg21.link/P1652>`_,"Printf corner cases in std::format",Mark de Wever,"`D103433 <https://reviews.llvm.org/D103433>`__, `D114001 <https://reviews.llvm.org/D114001>`__",|Review|,
 `P1892 <https://wg21.link/P1892>`_,"Extended locale-specific presentation specifiers for std::format",Mark de Wever,`D103368 <https://reviews.llvm.org/D103368>`__,|Complete|,Clang 14
 `P1868 <https://wg21.link/P1868>`_,"width: clarifying units of width and precision in std::format (Implements the unicode support.)",Mark de Wever,"`D103413 <https://reviews.llvm.org/D103413>`__ `D103425 <https://reviews.llvm.org/D103425>`__ `D103670 <https://reviews.llvm.org/D103670>`__",|Complete|,Clang 14
 `P2216 <https://wg21.link/P2216>`_,"std::format improvements",Mark de Wever,,|In Progress|,
 `P2418 <https://wg21.link/P2418>`__,"Add support for ``std::generator``-like types to ``std::format``",Mark de Wever,,|In Progress|,
 
 `P1361 <https://wg21.link/P1361>`_,"Integration of chrono with text formatting",,,|Not Started|,
 `P2372 <https://wg21.link/P2372>`__,"Fixing locale handling in chrono formatters",,,|Not Started|,

libcxx/include/format

 // -*- C++ -*-
 //===----------------------------------------------------------------------===//
 //
 // 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 {
-    basic_format_args<basic_format_context> args_;      // exposition only
-    Out out_;                                           // exposition only
-
-  public:
-    using iterator = Out;
-    using char_type = charT;
-    template<class T> using formatter_type = formatter<T, charT>;
-
-    basic_format_arg<basic_format_context> arg(size_t id) const;
-    std::locale locale();
-
-    iterator out();
-    void advance_to(iterator it);
-  };
+  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 {
-    size_t size_;                               // exposition only
-    const basic_format_arg<Context>* data_;     // exposition only
-
-  public:
-    basic_format_args() noexcept;
-
-    template<class... Args>
-      basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
-
-    basic_format_arg<Context> get(size_t i) const noexcept;
-  };
+  template<class Context> class basic_format_args;
   using format_args = basic_format_args<format_context>;
   using wformat_args = basic_format_args<wformat_context>;
 
-
   // [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>
namespace std {
   template<class Out>
     Out vformat_to(Out out, const locale& loc, wstring_view fmt,
                    wformat_args 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<> struct formatter<char, char>;
-  template<> struct formatter<char, wchar_t>;
-  template<> struct formatter<wchar_t, wchar_t>;
-
-  template<> struct formatter<charT*, charT>;
-  template<> struct formatter<const charT*, charT>;
-  template<size_t N> struct formatter<const charT[N], charT>;
-  template<class traits, class Allocator>
-    struct formatter<basic_string<charT, traits, Allocator>, charT>;
-  template<class traits>
-    struct formatter<basic_string_view<charT, traits>, charT>;
+  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 {
-  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);
-  };
+  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 {
-  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;
-  };
+  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
-    array<basic_format_arg<Context>, sizeof...(Args)> args;
-  };
+  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 : public runtime_error {
-  public:
-    explicit format_error(const string& what_arg);
-    explicit format_error(const char* what_arg);
-  };
-
-  // [format.parse.ctx], class template basic_format_parse_context
-  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);
-  };
-  using format_parse_context = basic_format_parse_context<char>;
-  using wformat_parse_context = basic_format_parse_context<wchar_t>;
+  class format_error;
 }
 
 */
 
 // Make sure all feature-test macros are available.
 #include <version>
 // Enable the contents of the header only when libc++ was built with LIBCXX_ENABLE_INCOMPLETE_FEATURES.
 #if !defined(_LIBCPP_HAS_NO_INCOMPLETE_FORMAT)