11 KiB
[format.arguments]
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]
namespace std {templateclass 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 onlytemplate explicit basic_format_arg(T& v) noexcept; // exposition onlypublic: basic_format_arg() noexcept; explicit operator bool() const noexcept; templatedecltype(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;
Constraints: T satisfies formattable-with.
Preconditions: If decay_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.
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(v));
otherwise, if TD is a signed integer type ([basic.fundamental]) and sizeof(TD) <= sizeof(int), initializes value with static_cast(v);
otherwise, if TD is an unsigned integer type andsizeof(TD) <= sizeof(unsigned int), initializesvalue with static_cast(v);
otherwise, if TD is a signed integer type andsizeof(TD) <= sizeof(long long int), initializesvalue with static_cast(v);
otherwise, if TD is an unsigned integer type andsizeof(TD) <= sizeof(unsigned long long int), initializesvalue withstatic_cast(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 ischar_type* or const char_type*, initializes value with static_cast<const char_type*>(v);
otherwise, if is_void_v<remove_pointer_t> is true oris_null_pointer_v 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 formatter for that pointer to member type.
â end note]
explicit operator bool() const noexcept;
Returns: !holds_alternative(value).
template<class Visitor> decltype(auto) visit(this basic_format_arg arg, Visitor&& vis);
Effects: Equivalent to: return arg.value.visit(std::forward(vis));
template<class R, class Visitor> R visit(this basic_format_arg arg, Visitor&& vis);
Effects: Equivalent to: return arg.value.visit(std::forward(vis));
The class handle allows formatting an object of a user-defined type.
namespace std {templateclass basic_format_arg::handle {const void* ptr_; // exposition onlyvoid (format_)(basic_format_parse_context<char_type>&, Context&, const void); // exposition onlytemplate explicit handle(T& val) noexcept; // exposition onlypublic: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,
TQ be const TD ifconst TD satisfies formattable-with and TD otherwise.
Mandates: TQ satisfies formattable-with.
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 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 { // exposition only array<basic_format_arg, sizeof...(Args)> args; // exposition only};}
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 Ti in Args.
Returns: An object of type format-arg-store<Context, Args...> whose args data member is initialized with{basic_format_arg(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 {templateclass basic_format_args { size_t size_; // exposition onlyconst basic_format_arg* data_; // exposition onlypublic:template<class... Args> basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
basic_format_arg get(size_t i) const noexcept; }; template<class Context, class... Args> basic_format_args(format-arg-store<Context, Args...>) -> basic_format_args;}
An instance of basic_format_args provides access to formatting arguments.
Implementations should optimize the representation of basic_format_args for 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().