20 General utilities library [utilities]

20.20 Formatting [format]

20.20.6 Arguments [format.arguments]

20.20.6.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(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; }; }
1
#
An instance of basic_­format_­arg provides access to a formatting argument for user-defined formatters.
2
#
The behavior of a program that adds specializations of basic_­format_­arg is undefined.
🔗
basic_format_arg() noexcept;
3
#
Postconditions: !(*this).
🔗
template<class T> explicit basic_format_arg(const T& v) noexcept;
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.
5
#
Effects:
  • (5.1)
    if T is bool or char_­type, initializes value with v;
  • (5.2)
    otherwise, if T is char and char_­type is wchar_­t, initializes value with static_­cast<wchar_­t>(v);
  • (5.3)
    otherwise, if T is a signed integer type ([basic.fundamental]) and sizeof(T) <= sizeof(int), initializes value with static_­cast<int>(v);
  • (5.4)
    otherwise, if T is an unsigned integer type and sizeof(T) <= sizeof(unsigned int), initializes value with static_­cast<unsigned int>(v);
  • (5.5)
    otherwise, if T is a signed integer type and sizeof(T) <= sizeof(long long int), initializes value with static_­cast<long long int>(v);
  • (5.6)
    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);
  • (5.7)
    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;
6
#
Effects: Initializes value with n.
🔗
explicit basic_format_arg(const char_type* s);
7
#
Preconditions: s points to a NTCTS ([defns.ntcts]).
8
#
Effects: Initializes value with s.
🔗
template<class traits> explicit basic_format_arg(basic_string_view<char_type, traits> s) noexcept;
9
#
Effects: Initializes value with s.
🔗
template<class traits, class Allocator> explicit basic_format_arg( const basic_string<char_type, traits, Allocator>& s) noexcept;
10
#
Effects: Initializes value with basic_­string_­view<char_­type>(s.data(), s.size()).
🔗
explicit basic_format_arg(nullptr_t) noexcept;
11
#
Effects: Initializes value with static_­cast<const void*>(nullptr).
🔗
template<class T> explicit basic_format_arg(const T* p) noexcept;
12
#
Constraints: is_­void_­v<T> is true.
13
#
Effects: Initializes value with p.
14
#
[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;
15
#
Returns: !holds_­alternative<monostate>(value).
16
#
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(const 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(const T& val) noexcept;
17
#
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<T> f; parse_ctx.advance_to(f.parse(parse_ctx)); format_ctx.advance_to(f.format(*static_cast<const T*>(ptr), format_ctx)); }
🔗
void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
18
#
Effects: Equivalent to: format_­(parse_­ctx, format_­ctx, ptr_­);
🔗
template<class Visitor, class Context> see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
19
#
Effects: Equivalent to: return visit(forward<Visitor>(vis), arg.value);

20.20.6.2 Class template format-arg-store [format.arg.store]

namespace std { template<class Context, class... Args> struct format-arg-store { // exposition only array<basic_format_arg<Context>, sizeof...(Args)> args; }; }
1
#
An instance of format-arg-store stores formatting arguments.
🔗
template<class Context = format_context, class... Args> format-arg-store<Context, Args...> make_format_args(const Args&... args);
2
#
Preconditions: The type typename Context​::​template formatter_­type<> meets the Formatter requirements ([formatter.requirements]) for each in Args.
3
#
Returns: {basic_­format_­arg<Context>(args)...}.
🔗
template<class... Args> format-arg-store<wformat_context, Args...> make_wformat_args(const Args&... args);
4
#
Effects: Equivalent to: return make_­format_­args<wformat_­context>(args...);

20.20.6.3 Class template basic_­format_­args [format.args]

namespace std { 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; }; }
1
#
An instance of basic_­format_­args provides access to formatting arguments.
🔗
basic_format_args() noexcept;
2
#
Effects: Initializes size_­ with 0.
🔗
template<class... Args> basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
3
#
Effects: Initializes size_­ with sizeof...(Args) and data_­ with store.args.data().
🔗
basic_format_arg<Context> get(size_t i) const noexcept;
4
#
Returns: i < size_­ ? data_­[i] : basic_­format_­arg<Context>().
5
#
[Note 1:
Implementations are encouraged to optimize the representation of basic_­format_­args for small number of formatting arguments by storing indices of type alternatives separately from values and packing the former.
— end note]