[libc++][format] Improves diagnostics.

When attempting to format a type that does not have a valid formatter
specialization the code is ill-formed and diagnostics are generated.

The patch now properly constrains the exposition-only basic_format_arg
constructor (LWG3246). This constructor is called by
- std::make_format_args. This function has the precondition
    The type typename Context::template
    formatter_type<remove_const_t<Ti>> meets the BasicFormatter
    requirements ([formatter.requirements]) for each Ti in Args.
- In libc++ `std::basic_format_string` constructor too. This is not
  specified by the standard, however the requirements for constructor
  allow this.

Since `basic_format_arg` exposition-only constructor's constraint can't
be observed by the user, they can use it to SFINAE their own code.
Currently libc++, libstdc++, and MSVC STL consider the code ill-formed.
This patch keeps that behaviour.

This patch improves the output of these diagnostics:
- Reduces the number of errors generated, which reduces the number of
  lines in the output.
- The error gives a more specific diagnotic in multiple cases. For
  example, the formatter's format function must be const qualified. The
  diagnostic now mentions this specific issue.

Summary of the error messages using the type
no_formatter_specialization, which as the name implies has no
specialization.

std::format (and friends)
Before
- 163 lines of output with 7 errors
- First two diagnostics:
  - error: static assertion failed due to requirement '__arg != __arg_t::__none': the supplied type is not formattable
  - note: in instantiation of function template specialization 'std::__format::__create_format_arg<std::format_context, no_formatter_specialization>' requested here

After
- 25 lines of output with 1 error
- First two diagnostics:
  - error: static assertion failed: The required formatter specialization has not been provided.
  - note: in instantiation of function template specialization 'std::__format::__diagnose_invalid_formatter<std::format_context, no_formatter_specialization>' requested here

std::make_format_args (used by users to call vformat and friends)
Before
- 70 lines of output with 3 errors
- First two diagnostics:
  - error: static assertion failed due to requirement '__arg != __arg_t::__none': the supplied type is not formattable
  - note: in instantiation of function template specialization 'std::__format::__create_format_arg<std::format_context, no_formatter_specialization>' requested here

After
- 25 lines of output with 1 error
- First two diagnostics:
  - error: static assertion failed: The required formatter specialization has not been provided.
  - note: in instantiation of function template specialization 'std::__format::__diagnose_invalid_formatter<std::format_context, no_formatter_specialization>' requested here

Fixes: #100263

Author: mordante

libcxx/include/__format/format_arg.h

@@ -219,7 +219,7 @@ class __basic_format_arg_value {
           __format_([](basic_format_parse_context<_CharT>& __parse_ctx, _Context& __ctx, const void* __ptr) {
             using _Dp = remove_const_t<_Tp>;
             using _Qp = conditional_t<__formattable_with<const _Dp, _Context>, const _Dp, _Dp>;
-            static_assert(__formattable_with<_Qp, _Context>, "Mandated by [format.arg]/10");
+            static_assert(__formattable_with<_Qp, _Context>, "Mandated by [format.arg]/12");
 
             typename _Context::template formatter_type<_Dp> __f;
             __parse_ctx.advance_to(__f.parse(__parse_ctx));
@@ -334,21 +334,16 @@ class _LIBCPP_TEMPLATE_VIS _LIBCPP_NO_SPECIALIZATIONS basic_format_arg {
 private:
   using char_type = typename _Context::char_type;
 
-  // TODO FMT Implement constrain [format.arg]/4
-  // Constraints: The template specialization
-  //   typename Context::template formatter_type<T>
-  // meets the Formatter requirements ([formatter.requirements]).  The extent
-  // to which an implementation determines that the specialization meets the
-  // Formatter requirements is unspecified, except that as a minimum the
-  // expression
-  //   typename Context::template formatter_type<T>()
-  //    .format(declval<const T&>(), declval<Context&>())
-  // shall be well-formed when treated as an unevaluated operand.
-
 public:
   __basic_format_arg_value<_Context> __value_;
   __format::__arg_t __type_;
 
+  // This constructor is used for the exposition only constructor.
+  // Per [format.arg]/4
+  //   template<class T> explicit basic_format_arg(T& v) noexcept;
+  //     Constraints: T satisfies formattable-with<Context>.
+  //
+  // This constraint is implemented in __create_format_arg
   _LIBCPP_HIDE_FROM_ABI explicit basic_format_arg(__format::__arg_t __type,
                                                   __basic_format_arg_value<_Context> __value) noexcept
       : __value_(__value), __type_(__type) {}

libcxx/include/__format/format_arg_store.h

@@ -161,12 +161,11 @@ consteval __arg_t __determine_arg_t() {
 //
 // Modeled after template<class T> explicit basic_format_arg(T& v) noexcept;
 // [format.arg]/4-6
-template <class _Context, class _Tp>
+template <class _Context, __formattable_with<_Context> _Tp>
 _LIBCPP_HIDE_FROM_ABI basic_format_arg<_Context> __create_format_arg(_Tp& __value) noexcept {
   using _Dp               = remove_const_t<_Tp>;
   constexpr __arg_t __arg = __format::__determine_arg_t<_Context, _Dp>();
   static_assert(__arg != __arg_t::__none, "the supplied type is not formattable");
-  static_assert(__formattable_with<_Tp, _Context>);
 
   // Not all types can be used to directly initialize the
   // __basic_format_arg_value.  First handle all types needing adjustment, the
@@ -205,6 +204,85 @@ _LIBCPP_HIDE_FROM_ABI basic_format_arg<_Context> __create_format_arg(_Tp& __valu
     return basic_format_arg<_Context>{__arg, __value};
 }
 
+// Helper function that issues a diagnostic when __formattable_with<_Tp, _Context> is false.
+//
+// Since it's quite easy to make a mistake writing a formatter specialization
+// this function tries to give a better explanation. This should improve the
+// diagnostics when trying to format type that has no properly specialized
+// formatter.
+template <class _Context, class _Tp>
+[[noreturn]] _LIBCPP_HIDE_FROM_ABI constexpr void __diagnose_invalid_formatter() {
+  using _Formatter = typename _Context::template formatter_type<remove_const_t<_Tp>>;
+  constexpr bool __is_disabled =
+      !is_default_constructible_v<_Formatter> && !is_copy_constructible_v<_Formatter> &&
+      !is_move_constructible_v<_Formatter> && !is_copy_assignable_v<_Formatter> && !is_move_assignable_v<_Formatter>;
+  constexpr bool __is_semiregular = semiregular<_Formatter>;
+
+  constexpr bool __has_parse_function =
+      requires(_Formatter& __f, basic_format_parse_context<typename _Context::char_type> __pc) {
+        { __f.parse(__pc) };
+      };
+  constexpr bool __correct_parse_function_return_type =
+      requires(_Formatter& __f, basic_format_parse_context<typename _Context::char_type> __pc) {
+        { __f.parse(__pc) } -> same_as<typename decltype(__pc)::iterator>;
+      };
+
+  constexpr bool __has_format_function = requires(_Formatter& __f, _Tp&& __t, _Context __fc) {
+    { __f.format(__t, __fc) };
+  };
+  constexpr bool __is_format_function_const_qualified = requires(const _Formatter& __cf, _Tp&& __t, _Context __fc) {
+    { __cf.format(__t, __fc) };
+  };
+  constexpr bool __correct_format_function_return_type = requires(_Formatter& __f, _Tp&& __t, _Context __fc) {
+    { __f.format(__t, __fc)->same_as<typename _Context::iterator> };
+  };
+
+  // The reason these static_asserts are placed in an if-constexpr-chain is to
+  // only show one error. For example, when the formatter is not specialized it
+  // would show all static_assert messages. With this chain the compiler only
+  // evaluates one static_assert.
+
+  if constexpr (__is_disabled)
+    static_assert(false, "The required formatter specialization has not been provided.");
+  else if constexpr (!__is_semiregular)
+    static_assert(false, "The required formatter specialization is not semiregular.");
+
+  else if constexpr (!__has_parse_function)
+    static_assert(
+        false, "The required formatter specialization does not have a parse function taking the proper arguments.");
+  else if constexpr (!__correct_parse_function_return_type)
+    static_assert(false, "The required formatter specialization's parse function does not return the required type.");
+
+  else if constexpr (!__has_format_function)
+    static_assert(
+        false, "The required formatter specialization does not have a format function taking the proper arguments.");
+  else if constexpr (!__is_format_function_const_qualified)
+    static_assert(false, "The required formatter specialization's format function is not const qualified.");
+  else if constexpr (!__correct_format_function_return_type)
+    static_assert(false, "The required formatter specialization's format function does not return the required type.");
+
+  else
+    // This should not happen; it makes sure the code is ill-formed.
+    static_assert(false, "The required formatter specialization is not formattable with its context.");
+}
+
+// The Psuedo constructor is constrained per [format.arg]/4.
+// The only way for a user to call __create_format_arg is from std::make_format_args.
+// Per [format.arg.store]/3
+//   template<class Context = format_context, class... Args>
+//     format-arg-store<Context, Args...> make_format_args(Args&... fmt_args);
+//
+//   Preconditions: The type typename Context::template formatter_type<remove_const_t<Ti>>
+//   meets the BasicFormatter requirements ([formatter.requirements]) for each Ti in Args.
+//
+// This function is only called when the precondition is violated.
+// Without this function the compilation would fail since the overload is
+// SFINAE'ed away. This function is used to provide better diagnostics.
+template <class _Context, class _Tp>
+_LIBCPP_HIDE_FROM_ABI basic_format_arg<_Context> __create_format_arg(_Tp&) noexcept {
+  __format::__diagnose_invalid_formatter<_Context, _Tp>();
+}
+
 template <class _Context, class... _Args>
 _LIBCPP_HIDE_FROM_ABI void
 __create_packed_storage(uint64_t& __types, __basic_format_arg_value<_Context>* __values, _Args&... __args) noexcept {

libcxx/include/__format/format_context.h

@@ -65,9 +65,13 @@ __format_context_create(_OutIt __out_it, basic_format_args<basic_format_context<
 }
 #  endif
 
-using format_context = basic_format_context<back_insert_iterator<__format::__output_buffer<char>>, char>;
+template <class _CharT>
+using __format_context _LIBCPP_NODEBUG =
+    basic_format_context<back_insert_iterator<__format::__output_buffer<_CharT>>, _CharT>;
+
+using format_context = __format_context<char>;
 #  if _LIBCPP_HAS_WIDE_CHARACTERS
-using wformat_context = basic_format_context< back_insert_iterator<__format::__output_buffer<wchar_t>>, wchar_t>;
+using wformat_context = __format_context<wchar_t>;
 #  endif
 
 template <class _OutIt, class _CharT>

libcxx/include/__format/format_functions.h

@@ -91,13 +91,22 @@ class _LIBCPP_TEMPLATE_VIS __compile_time_handle {
   }
 
   template <class _Tp>
+    requires __formattable_with<_Tp, __format_context<_CharT>>
   _LIBCPP_HIDE_FROM_ABI constexpr void __enable() {
     __parse_ = [](basic_format_parse_context<_CharT>& __ctx) {
       formatter<_Tp, _CharT> __f;
       __ctx.advance_to(__f.parse(__ctx));
     };
   }
 
+  template <class _Tp>
+  _LIBCPP_HIDE_FROM_ABI constexpr void __enable() {
+    // Avoids the throw set in the constructor.
+    // Otherwise two diagnostics will be issued.
+    __parse_ = [](basic_format_parse_context<_CharT>&) {};
+    __format::__diagnose_invalid_formatter<__format_context<_CharT>, _Tp>();
+  }
+
   // Before calling __parse the proper handler needs to be set with __enable.
   // The default handler isn't a core constant expression.
   _LIBCPP_HIDE_FROM_ABI constexpr __compile_time_handle()

libcxx/test/libcxx/utilities/format/format.arguments/format.arg.store/make_format_args.verify.cpp

@@ -0,0 +1,200 @@
+//===----------------------------------------------------------------------===//
+//
+// 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>
+
+// template<class Context = format_context, class... Args>
+// format-arg-store<Context, Args...> make_format_args(Args&... args);
+//
+// Preconditions: The type typename Context::template formatter_type<remove_const_t<Ti>>
+// meets the BasicFormatter requirements ([formatter.requirements]) for each Ti in Args.
+//
+// When the precondition is violated libc++ diagnoses the issue with the
+// formatter specialization.
+
+#include <format>
+
+#include "test_macros.h"
+
+struct no_formatter_specialization {};
+void test_no_formatter_specialization() {
+  no_formatter_specialization t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization has not been provided.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization has not been provided.}}
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct correct_formatter_specialization {};
+template <class CharT>
+struct std::formatter<correct_formatter_specialization, CharT> {
+  template <class ParseContext>
+  constexpr typename ParseContext::iterator parse(ParseContext&);
+
+  template <class FormatContext>
+  typename FormatContext::iterator format(correct_formatter_specialization&, FormatContext&) const;
+};
+void test_correct_formatter_specialization() {
+  correct_formatter_specialization t;
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct formatter_not_semiregular {};
+template <class CharT>
+struct std::formatter<formatter_not_semiregular, CharT> {
+  formatter(int);
+
+  template <class ParseContext>
+  constexpr typename ParseContext::iterator parse(ParseContext&);
+
+  template <class FormatContext>
+  typename FormatContext::iterator format(formatter_not_semiregular&, FormatContext&) const;
+};
+void test_formatter_not_semiregular() {
+  formatter_not_semiregular t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization is not semiregular.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization is not semiregular.}}
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct formatter_no_parse_function {};
+template <class CharT>
+struct std::formatter<formatter_no_parse_function, CharT> {
+  template <class FormatContext>
+  typename FormatContext::iterator format(formatter_no_parse_function&, FormatContext&) const;
+};
+void test_formatter_no_parse_function() {
+  formatter_no_parse_function t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization does not have a parse function taking the proper arguments.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization does not have a parse function taking the proper arguments.}}
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct parse_function_invalid_arguments {};
+template <class CharT>
+struct std::formatter<parse_function_invalid_arguments, CharT> {
+  template <class ParseContext>
+  constexpr typename ParseContext::iterator parse(ParseContext&, int);
+
+  template <class FormatContext>
+  typename FormatContext::iterator format(parse_function_invalid_arguments&, FormatContext&) const;
+};
+void test_parse_function_invalid_arguments() {
+  parse_function_invalid_arguments t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization does not have a parse function taking the proper arguments.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization does not have a parse function taking the proper arguments.}}
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct parse_function_invalid_return_type {};
+template <class CharT>
+struct std::formatter<parse_function_invalid_return_type, CharT> {
+  template <class ParseContext>
+  constexpr int parse(ParseContext&);
+
+  template <class FormatContext>
+  typename FormatContext::iterator format(parse_function_invalid_return_type&, FormatContext&) const;
+};
+void test_parse_function_invalid_return_type() {
+  parse_function_invalid_return_type t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization's parse function does not return the required type.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization's parse function does not return the required type.}}
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct no_format_function {};
+template <class CharT>
+struct std::formatter<no_format_function, CharT> {
+  template <class ParseContext>
+  constexpr typename ParseContext::iterator parse(ParseContext&);
+};
+void test_no_format_function() {
+  no_format_function t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization does not have a format function taking the proper arguments.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization does not have a format function taking the proper arguments.}}
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct format_function_invalid_arguments {};
+template <class CharT>
+struct std::formatter<format_function_invalid_arguments, CharT> {
+  template <class ParseContext>
+  constexpr typename ParseContext::iterator parse(ParseContext&);
+
+  template <class FormatContext>
+  typename FormatContext::iterator format(format_function_invalid_arguments&) const;
+};
+void test_format_function_invalid_arguments() {
+  format_function_invalid_arguments t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization does not have a format function taking the proper arguments.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization does not have a format function taking the proper arguments.}}
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct format_function_invalid_return_type {};
+template <class CharT>
+struct std::formatter<format_function_invalid_return_type, CharT> {
+  template <class ParseContext>
+  constexpr typename ParseContext::iterator parse(ParseContext&);
+
+  template <class FormatContext>
+  int format(format_function_invalid_return_type&, FormatContext&) const;
+};
+void test_format_function_invalid_return_type() {
+  format_function_invalid_return_type t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization's format function does not return the required type.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization's format function does not return the required type.}}
+  (void)std::make_wformat_args(t);
+#endif
+}
+
+struct format_function_not_const_qualified {};
+template <class CharT>
+struct std::formatter<format_function_not_const_qualified, CharT> {
+  template <class ParseContext>
+  constexpr typename ParseContext::iterator parse(ParseContext&);
+
+  template <class FormatContext>
+  typename FormatContext::iterator format(format_function_not_const_qualified&, FormatContext&);
+};
+void test_format_function_not_const_qualified() {
+  format_function_not_const_qualified t;
+  // expected-error@*:* {{static assertion failed: The required formatter specialization's format function is not const qualified.}}
+  (void)std::make_format_args(t);
+#ifndef TEST_HAS_NO_WIDE_CHARACTERS
+  // expected-error@*:* {{static assertion failed: The required formatter specialization's format function is not const qualified.}}
+  (void)std::make_wformat_args(t);
+#endif
+}