20 General utilities library [utilities]

20.20 Formatting [format]

20.20.7 Arguments [format.arguments]

20.20.7.1 Class template basic_­format_­arg [format.arg]

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(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(T* p) noexcept; // exposition only public: basic_format_arg() noexcept; explicit operator bool() const noexcept; }; }
An instance of basic_­format_­arg provides access to a formatting argument for user-defined formatters.
The behavior of a program that adds specializations of basic_­format_­arg is undefined.
basic_format_arg() noexcept;
Postconditions: !(*this).
template<class T> explicit basic_format_arg(T&& v) noexcept;
Constraints: The template specialization typename Context::template formatter_type<remove_cvref_t<T>> meets the BasicFormatter requirements ([formatter.requirements]).
The extent to which an implementation determines that the specialization meets the BasicFormatter requirements is unspecified, except that as a minimum the expression typename Context::template formatter_type<remove_cvref_t<T>>() .format(declval<T&>(), declval<Context&>()) shall be well-formed when treated as an unevaluated operand ([term.unevaluated.operand]).
Effects:
  • if T is bool or char_­type, initializes value with v;
  • otherwise, if T is char and char_­type is wchar_­t, initializes value with static_­cast<wchar_­t>(v);
  • otherwise, if T is a signed integer type ([basic.fundamental]) and sizeof(T) <= sizeof(int), initializes value with static_­cast<int>(v);
  • otherwise, if T is an unsigned integer type and sizeof(T) <= sizeof(unsigned int), initializes value with static_­cast<unsigned int>(v);
  • otherwise, if T is a signed integer type and sizeof(T) <= sizeof(long long int), initializes value with static_­cast<long long int>(v);
  • otherwise, if T is an unsigned integer type and sizeof(T) <= sizeof(unsigned long long int), initializes value with static_­cast<unsigned long long int>(v);
  • otherwise, initializes value with handle(v).
explicit basic_format_arg(float n) noexcept; explicit basic_format_arg(double n) noexcept; explicit basic_format_arg(long double n) noexcept;
Effects: Initializes value with n.
explicit basic_format_arg(const char_type* s);
Preconditions: s points to a NTCTS ([defns.ntcts]).
Effects: Initializes value with s.
template<class traits> explicit basic_format_arg(basic_string_view<char_type, traits> s) noexcept;
Effects: Initializes value with basic_­string_­view<char_­type>(s.data(), s.size()).
template<class traits, class Allocator> explicit basic_format_arg( const basic_string<char_type, traits, Allocator>& s) noexcept;
Effects: Initializes value with basic_­string_­view<char_­type>(s.data(), s.size()).
explicit basic_format_arg(nullptr_t) noexcept;
Effects: Initializes value with static_­cast<const void*>(nullptr).
template<class T> explicit basic_format_arg(T* p) noexcept;
Constraints: is_­void_­v<T> is true.
Effects: Initializes value with p.
[Note 1:
Constructing basic_­format_­arg from a pointer to a member is ill-formed unless the user provides an enabled specialization of formatter for that pointer to member type.
— end note]
explicit operator bool() const noexcept;
Returns: !holds_­alternative<monostate>(value).
The class handle allows formatting an object of a user-defined type.
namespace std { template<class Context> class basic_format_arg<Context>::handle { const void* ptr_; // exposition only void (*format_)(basic_format_parse_context<char_type>&, Context&, const void*); // exposition only template<class T> explicit handle(T&& val) noexcept; // exposition only friend class basic_format_arg<Context>; // exposition only public: void format(basic_format_parse_context<char_type>&, Context& ctx) const; }; }
template<class T> explicit handle(T&& val) noexcept;
Let
  • TD be remove_­cvref_­t<T>,
  • const-formattable be true if typename Context​::​template formatter_­type<TD>()
    .format(declval<const TD&>(), declval<Context&>())
    is well-formed, otherwise false,
  • TQ be const TD if const-formattable is true and TD otherwise.
Mandates: const-formattable || !is_­const_­v<remove_­reference_­t<T>> is true.
Effects: Initializes ptr_­ with addressof(val) and format_­ with [](basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx, const void* ptr) { typename Context::template formatter_type<TD> f; parse_ctx.advance_to(f.parse(parse_ctx)); format_ctx.advance_to(f.format(*const_cast<TQ*>(static_cast<const TD*>(ptr)), format_ctx)); }
void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
Effects: Equivalent to: format_­(parse_­ctx, format_­ctx, ptr_­);
template<class Visitor, class Context> decltype(auto) visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
Effects: Equivalent to: return visit(forward<Visitor>(vis), arg.value);