[libc++][format] Adds formatter handle.

[Mordante]

Summary

This implements the handler according to P0645. P2418 changes the wording
in the Standard. That isn't implemented and requires changes in more
places. LWG3631 applies modifications to P2418, but is currently
unresolved.

Implements parts of:

• P0645 Text Formatting

Depends on D115989

[Mordante]

Disable failing gcc tests.

[Mordante]

Attempt to fix the no-exception CI builds.

[vitaut]

libcxx/include/__format/format_arg.h

49–51

Not directly related to this diff but this seems to make the ABI depend on _LIBCPP_HAS_NO_INT128. A better approach would be to always define these enumerators but only use them conditionally.

libcxx/test/std/utilities/format/format.functions/format_tests.h

71–75

Maybe move error reporting to a function to have _LIBCPP_NO_EXCEPTIONS check in one place?

122

Looks like begin may be unterminated in some cases because buffer is uninitialized and to_chars doesn't nul-terminate.

[Mordante]

Thanks for the review.

libcxx/include/__format/format_arg.h

49–51

Thanks for the suggestion! I'll do that in a separate patch.

libcxx/test/std/utilities/format/format.functions/format_tests.h

122

This should be save since this code is only executed when type == 2 and begin is always initialized with a string literal.

[Mordante]

Address review comments.

[Mordante]

libcxx/include/__format/format_arg.h

49–51

Applied your suggestion in D116120.

[vitaut]

LGTM

libcxx/include/__format/format_arg.h

49–51

Great, thank you!

libcxx/test/std/utilities/format/format.functions/format_tests.h

122

Missed that, sorry for the noise.

libcxx/include/__format/format_arg.h

 // -*- 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_FORMAT_ARG_H
 #define _LIBCPP___FORMAT_FORMAT_ARG_H
 
 #include <__concepts/arithmetic.h>
 #include <__config>
 #include <__format/format_error.h>
 #include <__format/format_fwd.h>
+#include <__format/format_parse_context.h>
 #include <__functional_base>
+#include <__memory/addressof.h>
 #include <__variant/monostate.h>
 #include <string>
 #include <string_view>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #pragma GCC system_header
 #endif
 

 namespace __format {
 /** The type stored in @ref basic_format_arg. */
 enum class _LIBCPP_ENUM_VIS __arg_t : uint8_t {
   __none,
   __boolean,
   __char_type,
   __int,
   __long_long,
 #ifndef _LIBCPP_HAS_NO_INT128
   __i128,
 #endif
   __unsigned,
   __unsigned_long_long,
 #ifndef _LIBCPP_HAS_NO_INT128
   __u128,
 #endif
   __float,
   __double,
   __long_double,
   __const_char_type_ptr,
   __string_view,
-  __ptr
+  __ptr,
+  __handle
 };
 } // namespace __format
 
 template <class _Visitor, class _Context>
 _LIBCPP_HIDE_FROM_ABI _LIBCPP_AVAILABILITY_FORMAT decltype(auto)
 visit_format_arg(_Visitor&& __vis, basic_format_arg<_Context> __arg) {
   switch (__arg.__type_) {
   case __format::__arg_t::__none:
case __format::__arg_t::__long_double:
     return _VSTD::invoke(_VSTD::forward<_Visitor>(__vis), __arg.__long_double);
   case __format::__arg_t::__const_char_type_ptr:
     return _VSTD::invoke(_VSTD::forward<_Visitor>(__vis),
                          __arg.__const_char_type_ptr);
   case __format::__arg_t::__string_view:
     return _VSTD::invoke(_VSTD::forward<_Visitor>(__vis), __arg.__string_view);
   case __format::__arg_t::__ptr:
     return _VSTD::invoke(_VSTD::forward<_Visitor>(__vis), __arg.__ptr);
+  case __format::__arg_t::__handle:
+    return _VSTD::invoke(_VSTD::forward<_Visitor>(__vis), __arg.__handle);
   }
   _LIBCPP_UNREACHABLE();
 }
 
 template <class _Context>
 class _LIBCPP_TEMPLATE_VIS _LIBCPP_AVAILABILITY_FORMAT basic_format_arg {
 public:
-  // TODO FMT Define the handle class.
-  class handle;
+  class _LIBCPP_TEMPLATE_VIS handle;
 
   _LIBCPP_HIDE_FROM_ABI basic_format_arg() noexcept
       : __type_{__format::__arg_t::__none} {}
 
   _LIBCPP_HIDE_FROM_ABI explicit operator bool() const noexcept {
     return __type_ != __format::__arg_t::__none;
   }
 
#ifndef _LIBCPP_HAS_NO_INT128
     __uint128_t __u128;
 #endif
     float __float;
     double __double;
     long double __long_double;
     const char_type* __const_char_type_ptr;
     basic_string_view<char_type> __string_view;
     const void* __ptr;
-    // TODO FMT Add the handle.
+    handle __handle;
   };
   __format::__arg_t __type_;
 
   _LIBCPP_HIDE_FROM_ABI explicit basic_format_arg(bool __v) noexcept
       : __boolean(__v), __type_(__format::__arg_t::__boolean) {}
 
   template <class _Tp>
   _LIBCPP_HIDE_FROM_ABI explicit basic_format_arg(_Tp __v) noexcept
#endif
 
   _LIBCPP_HIDE_FROM_ABI
   explicit basic_format_arg(nullptr_t) noexcept
       : __ptr(nullptr), __type_(__format::__arg_t::__ptr) {}
 
   template <class _Tp>
   requires is_void_v<_Tp> _LIBCPP_HIDE_FROM_ABI explicit basic_format_arg(_Tp* __p) noexcept
       : __ptr(__p), __type_(__format::__arg_t::__ptr) {}
+
+  template <class _Tp>
+  _LIBCPP_HIDE_FROM_ABI explicit basic_format_arg(const _Tp& __v) noexcept
+      : __handle(__v), __type_(__format::__arg_t::__handle) {}
+};
+
+template <class _Context>
+class _LIBCPP_TEMPLATE_VIS basic_format_arg<_Context>::handle {
+  friend class basic_format_arg<_Context>;
+
+public:
+  _LIBCPP_HIDE_FROM_ABI
+  void format(basic_format_parse_context<char_type>& __parse_ctx, _Context& __ctx) const {
+    __format_(__parse_ctx, __ctx, __ptr_);
+  }
+
+private:
+  const void* __ptr_;
+  void (*__format_)(basic_format_parse_context<char_type>&, _Context&, const void*);
+
+  template <class _Tp>
+  _LIBCPP_HIDE_FROM_ABI explicit handle(const _Tp& __v) noexcept
+      : __ptr_(_VSTD::addressof(__v)),
+        __format_([](basic_format_parse_context<char_type>& __parse_ctx, _Context& __ctx, const void* __ptr) {
+          typename _Context::template formatter_type<_Tp> __f;
+          __parse_ctx.advance_to(__f.parse(__parse_ctx));
+          __ctx.advance_to(__f.format(*static_cast<const _Tp*>(__ptr), __ctx));
+        }) {}
 };
 
 #endif // !defined(_LIBCPP_HAS_NO_CONCEPTS)
 
 #endif //_LIBCPP_STD_VER > 17
 
 _LIBCPP_END_NAMESPACE_STD
 
 _LIBCPP_POP_MACROS
 
 #endif // _LIBCPP___FORMAT_FORMAT_ARG_H

libcxx/include/format

default:
     __throw_format_error(
         "The replacement field arg-id should terminate at a ':' or '}'");
   }
 
   _VSTD::visit_format_arg(
       [&](auto __arg) {
         if constexpr (same_as<decltype(__arg), monostate>)
           __throw_format_error("Argument index out of bounds");
+        else if constexpr (same_as<decltype(__arg), typename basic_format_arg<_Ctx>::handle>)
+          __arg.format(__parse_ctx, __ctx);
         else {
           formatter<decltype(__arg), _CharT> __formatter;
           __parse_ctx.advance_to(__formatter.parse(__parse_ctx));
           __ctx.advance_to(__formatter.format(__arg, __ctx));
         }
       },
       __ctx.arg(__r.__value));
 

libcxx/test/std/utilities/format/format.formatter/format.context/format.formatter.spec/formatter.handle.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
+// UNSUPPORTED: libcpp-no-concepts
+// UNSUPPORTED: libcpp-has-no-incomplete-format
+
+// <format>
+
+// A user defined formatter using
+// template<class Context>
+// class basic_format_arg<Context>::handle
+
+#include <format>
+
+#include <array>
+#include <cassert>
+#include <cmath>
+#include <charconv>
+#include <concepts>
+#include <string>
+#include <type_traits>
+
+#include "test_macros.h"
+
+enum class color { black, red, gold };
+const char* color_names[] = {"black", "red", "gold"};
+
+template <>
+struct std::formatter<color> : std::formatter<const char*> {
+  auto format(color c, format_context& ctx) {
+    return formatter<const char*>::format(color_names[static_cast<int>(c)], ctx);
+  }
+};
+
+void test(std::string expected, std::string_view fmt, color arg) {
+  auto parse_ctx = std::format_parse_context(fmt);
+  std::formatter<color, char> formatter;
+  static_assert(std::semiregular<decltype(formatter)>);
+
+  auto it = formatter.parse(parse_ctx);
+  assert(it == fmt.end() - (!fmt.empty() && fmt.back() == '}'));
+
+  std::string result;
+  auto out = std::back_inserter(result);
+  using FormatCtxT = std::basic_format_context<decltype(out), char>;
+
+  auto format_ctx = std::__format_context_create<decltype(out), char>(out, std::make_format_args<FormatCtxT>(arg));
+  formatter.format(arg, format_ctx);
+  assert(result == expected);
+}
+
+void test_termination_condition(std::string expected, std::string f, color arg) {
+  // The format-spec is valid if completely consumed or terminates at a '}'.
+  // The valid inputs all end with a '}'. The test is executed twice:
+  // - first with the terminating '}',
+  // - second consuming the entire input.
+  std::string_view fmt{f};
+  assert(fmt.back() == '}' && "Pre-condition failure");
+
+  test(expected, fmt, arg);
+  fmt.remove_suffix(1);
+  test(expected, fmt, arg);
+}
+
+int main(int, char**) {
+  test_termination_condition("black", "}", color::black);
+  test_termination_condition("red", "}", color::red);
+  test_termination_condition("gold", "}", color::gold);
+
+  return 0;
+}

libcxx/test/std/utilities/format/format.functions/format_tests.h

 //===----------------------------------------------------------------------===//
 // 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 TEST_STD_UTILITIES_FORMAT_FORMAT_FUNCTIONS_FORMAT_TESTS_H
 #define TEST_STD_UTILITIES_FORMAT_FORMAT_FUNCTIONS_FORMAT_TESTS_H
 
 #include <format>
 
-#include "make_string.h"
-
+#include <algorithm>
+#include <charconv>
 #include <cmath>
+#include <cstdint>
+
+#include "make_string.h"
 
 // In this file the following template types are used:
 // TestFunction must be callable as check(expected-result, string-to-format, args-to-format...)
 // ExceptionTest must be callable as check_exception(expected-exception, string-to-format, args-to-format...)
 
 #define STR(S) MAKE_STRING(CharT, S)
 #define CSTR(S) MAKE_CSTRING(CharT, S)
 

 struct context<wchar_t> {
   using type = std::wformat_context;
 };
 #endif
 
 template <class T>
 using context_t = typename context<T>::type;
 
+// A user-defined type used to test the handle formatter.
+enum class status : uint16_t { foo = 0xAAAA, bar = 0x5555, foobar = 0xAA55 };
+
+// The formatter for a user-defined type used to test the handle formatter.
+template <class CharT>
+struct std::formatter<status, CharT> {
+  int type = 0;
+
+  constexpr auto parse(auto& parse_ctx) -> decltype(parse_ctx.begin()) {
+    auto begin = parse_ctx.begin();
+    auto end = parse_ctx.end();
+    if (begin == end)
+      return begin;
+
+    switch (*begin) {
+    case CharT('x'):
+      break;
+    case CharT('X'):
+      type = 1;
+      break;
+    case CharT('s'):
+      type = 2;
+      break;
+    case CharT('}'):
+      return begin;
+    default:
+      throw std::format_error("The format-spec type has a type not supported for a status argument");
+    }
+
+    ++begin;
+    if (begin != end && *begin != CharT('}'))
+      throw std::format_error("The format-spec should consume the input or end with a '}'");
+
+    return begin;
+  }
+
+  auto format(status s, auto& ctx) -> decltype(ctx.out()) {
+    const char* names[] = {"foo", "bar", "foobar"};
+    char buffer[6];
+    const char* begin;
+    const char* end;
+    switch (type) {
+    case 0:
+      begin = buffer;
+      buffer[0] = '0';
+      buffer[1] = 'x';
+      end = std::to_chars(&buffer[2], std::end(buffer), static_cast<uint16_t>(s), 16).ptr;
+      break;
+
+    case 1:
+      begin = buffer;
+      buffer[0] = '0';
+      buffer[1] = 'X';
+      end = std::to_chars(&buffer[2], std::end(buffer), static_cast<uint16_t>(s), 16).ptr;
+      std::transform(static_cast<const char*>(&buffer[2]), end, &buffer[2], [](char c) { return std::toupper(c); });
+      break;
+
+    case 2:
+      switch (s) {
+      case status::foo:
+        begin = names[0];
+        break;
+      case status::bar:
+        begin = names[1];
+        break;
+      case status::foobar:
+        begin = names[2];
+        break;
+      }
+      end = begin + strlen(begin);
+      break;
+    }
+
+    return std::copy(begin, end, ctx.out());
+  }
+};
+
 template <class CharT>
 std::vector<std::basic_string<CharT>> invalid_types(std::string valid) {
   std::vector<std::basic_string<CharT>> result;
 
 #define CASE(T)                                                                \
   case #T[0]:                                                                  \
     result.push_back(STR("Invalid formatter type {:" #T "}"));                 \
     break;
 
void format_test_pointer(TestFunction check, ExceptionTest check_exception) {
   check_exception("The format-spec should consume the input or end with a '}'", STR("{:L}"), P(nullptr));
 
   // *** type ***
   for (const auto& fmt : invalid_types<CharT>("p"))
     check_exception("The format-spec type has a type not supported for a pointer argument", fmt, P(nullptr));
 }
 
 template <class CharT, class TestFunction, class ExceptionTest>
+void format_test_handle(TestFunction check, ExceptionTest check_exception) {
+  // *** Valid permuatations ***
+  check(STR("answer is '0xaaaa'"), STR("answer is '{}'"), status::foo);
+  check(STR("answer is '0xaaaa'"), STR("answer is '{:x}'"), status::foo);
+  check(STR("answer is '0XAAAA'"), STR("answer is '{:X}'"), status::foo);
+  check(STR("answer is 'foo'"), STR("answer is '{:s}'"), status::foo);
+
+  check(STR("answer is '0x5555'"), STR("answer is '{}'"), status::bar);
+  check(STR("answer is '0x5555'"), STR("answer is '{:x}'"), status::bar);
+  check(STR("answer is '0X5555'"), STR("answer is '{:X}'"), status::bar);
+  check(STR("answer is 'bar'"), STR("answer is '{:s}'"), status::bar);
+
+  check(STR("answer is '0xaa55'"), STR("answer is '{}'"), status::foobar);
+  check(STR("answer is '0xaa55'"), STR("answer is '{:x}'"), status::foobar);
+  check(STR("answer is '0XAA55'"), STR("answer is '{:X}'"), status::foobar);
+  check(STR("answer is 'foobar'"), STR("answer is '{:s}'"), status::foobar);
+
+  // *** type ***
+  for (const auto& fmt : invalid_types<CharT>("xXs"))
+    check_exception("The format-spec type has a type not supported for a status argument", fmt, status::foo);
+}
+
+template <class CharT, class TestFunction, class ExceptionTest>
 void format_test_pointer(TestFunction check, ExceptionTest check_exception) {
   format_test_pointer<std::nullptr_t, CharT>(check, check_exception);
   format_test_pointer<void*, CharT>(check, check_exception);
   format_test_pointer<const void*, CharT>(check, check_exception);
 }
 
 template <class CharT, class TestFunction, class ExceptionTest>
 void format_tests(TestFunction check, ExceptionTest check_exception) {
#endif
   check(STR("hello 42"), STR("hello {}"), static_cast<long double>(42));
   format_test_floating_point<CharT>(check, check_exception);
 
   // *** Test pointer formater argument ***
   check(STR("hello 0x0"), STR("hello {}"), nullptr);
   check(STR("hello 0x42"), STR("hello {}"), reinterpret_cast<void*>(0x42));
   check(STR("hello 0x42"), STR("hello {}"), reinterpret_cast<const void*>(0x42));
   format_test_pointer<CharT>(check, check_exception);
+
+  // *** Test handle formatter argument ***
+  format_test_handle<CharT>(check, check_exception);
 }
 
 #ifndef TEST_HAS_NO_WIDE_CHARACTERS
 template <class TestFunction>
 void format_tests_char_to_wchar_t(TestFunction check) {
   using CharT = wchar_t;
   check(STR("hello 09azA"), STR("hello {}{}{}{}{}"), '0', '9', 'a', 'z', 'A');
 }
 #endif
 
 #endif