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
:
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>().
[Note
:
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
]