[format.arguments] (original) (raw)

28 Text processing library [text]

28.5 Formatting [format]

28.5.8 Arguments [format.arguments]

28.5.8.1 Class template basic_format_arg [format.arg]

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

28.5.8.3 Class template basic_format_args [format.args]

28.5.8.1 Class template basic_format_arg [format.arg]

namespace std { template<class Context> class basic_format_arg { public: class handle;private: using char_type = Context::char_type; 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; template<class T> explicit basic_format_arg(T& v) noexcept; public: basic_format_arg() noexcept;explicit operator bool() const noexcept;template<class Visitor> decltype(auto) visit(this basic_format_arg arg, Visitor&& vis);template<class R, class Visitor> R visit(this basic_format_arg arg, Visitor&& vis);};}

An instance of basic_format_arg provides access to a formatting argument for user-defined formatters.

The behavior of a program that adds specializations ofbasic_format_arg is undefined.

basic_format_arg() noexcept;

Postconditions: !(*this).

template<class T> explicit basic_format_arg(T& v) noexcept;

Preconditions: If decay_t<T> is char_type* or const char_type*,static_cast<const char_
type*>(v) points to an NTCTS ([defns.ntcts]).

Effects: Let TD be remove_const_t<T>.

If TD is bool or char_type, initializes value with v;
otherwise, if TD is char and char_type iswchar_t, initializes value withstatic_cast<wchar_t>(static_cast<unsigned char>(v));
otherwise, if TD is a signed integer type ([basic.fundamental]) and sizeof(TD) <= sizeof(int), initializes value with static_cast<int>(v);
otherwise, if TD is an unsigned integer type andsizeof(TD) <= sizeof(unsigned int), initializesvalue with static_cast<unsigned int>(v);
otherwise, if TD is a signed integer type andsizeof(TD) <= sizeof(long long int), initializesvalue with static_cast<long long int>(v);
otherwise, if TD is an unsigned integer type andsizeof(TD) <= sizeof(unsigned long long int), initializesvalue withstatic_cast<unsigned long long int>(v);
otherwise, if TD is a standard floating-point type, initializes value with v;
otherwise, if TD is a specialization of basic_string_view or basic_string andTD::value_type is char_type, initializes value withbasic_string_view<char_type>(v.data(), v.size());
otherwise, if decay_t<TD> ischar_type* or const char_type*, initializes value with static_cast<const char_type*>(v);
otherwise, if is_void_v<remove_pointer_t<TD>> is true oris_null_pointer_v<TD> is true, initializes value with static_cast<const void*>(v);
otherwise, initializes value with handle(v).

[Note 1:

Constructing basic_format_arg from a pointer to a member is ill-formed unless the user provides an enabled specialization of formatterfor that pointer to member type.

— _end note_]

explicit operator bool() const noexcept;

Returns: !holds_alternative<monostate>(value).

template<class Visitor> decltype(auto) visit(this basic_format_arg arg, Visitor&& vis);

Effects: Equivalent to: return arg.value.visit(std::forward<Visitor>(vis));

template<class R, class Visitor> R visit(this basic_format_arg arg, Visitor&& vis);

Effects: Equivalent to: return arg.value.visit<R>(std::forward<Visitor>(vis));

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_; void (*format_)(basic_format_parse_context<char_type>&, Context&, const void*); template<class T> explicit handle(T& val) noexcept; public: void format(basic_format_parse_context<char_type>&, Context& ctx) const;};}

template<class T> explicit handle(T& val) noexcept;

Let

TD be remove_const_t<T>,
TQ be const TD ifconst TD satisfies formattable-with<Context>and TD otherwise.

Effects: Initializesptr_ with addressof(val) andformat_ 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_);

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

namespace std { template<class Context, class... Args> class format-arg-store { array<basic_format_arg<Context>, sizeof...(Args)> args; };}

An instance of format-arg-store stores formatting arguments.

template<class Context = format_context, class... Args> _format-arg-store_<Context, Args...> make_format_args(Args&... fmt_args);

Preconditions: The typetypename Context::template formatter_type<remove_const_t<>>
meets the BasicFormatter requirements ([formatter.requirements]) for each in Args.

Returns: An object of type format-arg-store<Context, Args...>whose args data member is initialized with{basic_format_arg<Context>(fmt_args)...}.

template<class... Args> _format-arg-store_<wformat_context, Args...> make_wformat_args(Args&... args);

Effects: Equivalent to:return make_format_args<wformat_context>(args...);

28.5.8.3 Class template basic_format_args [format.args]

namespace std { template<class Context> class basic_format_args { size_t size_; const basic_format_arg<Context>* data_; public: template<class... Args> basic_format_args(const format-arg-store<Context, Args...>& store) noexcept; basic_format_arg<Context> get(size_t i) const noexcept;};template<class Context, class... Args> basic_format_args(format-arg-store<Context, Args...>) -> basic_format_args<Context>;}

An instance of basic_format_args provides access to formatting arguments.

Implementations should optimize the representation of basic_format_argsfor a small number of formatting arguments.

[Note 1:

For example, by storing indices of type alternatives separately from values and packing the former.

— _end note_]

template<class... Args> basic_format_args(const _format-arg-store_<Context, Args...>& store) noexcept;

Effects: Initializessize_ with sizeof...(Args) anddata_ with store.args.data().

basic_format_arg<Context> get(size_t i) const noexcept;

Returns: i < size_ ? data_[i] : basic_format_arg<Context>().