20 General utilities library [utilities]

20.20 Formatting [format]

20.20.3 Formatting functions [format.functions]

In the description of the functions, operator + is used for some of the iterator categories for which it does not have to be defined.
In these cases the semantics of a + n are the same as in [algorithms.requirements].
template<class... Args> string format(string_view fmt, const Args&... args);
Effects: Equivalent to:
return vformat(fmt, make_format_args(args...));
template<class... Args> wstring format(wstring_view fmt, const Args&... args);
Effects: Equivalent to:
return vformat(fmt, make_wformat_args(args...));
template<class... Args> string format(const locale& loc, string_view fmt, const Args&... args);
Effects: Equivalent to:
return vformat(loc, fmt, make_format_args(args...));
template<class... Args> wstring format(const locale& loc, wstring_view fmt, const Args&... args);
Effects: Equivalent to:
return vformat(loc, fmt, make_wformat_args(args...));
string vformat(string_view fmt, format_args args); wstring vformat(wstring_view fmt, wformat_args args); string vformat(const locale& loc, string_view fmt, format_args args); wstring vformat(const locale& loc, wstring_view fmt, wformat_args args);
Returns: A string object holding the character representation of formatting arguments provided by args formatted according to specifications given in fmt.
If present, loc is used for locale-specific formatting.
Throws: format_­error if fmt is not a format string.
template<class Out, class... Args> Out format_to(Out out, string_view fmt, const Args&... args); template<class Out, class... Args> Out format_to(Out out, wstring_view fmt, const Args&... args);
Effects: Equivalent to:
using context = basic_format_context<Out, decltype(fmt)::value_type>;
return vformat_to(out, fmt, {make_format_args<context>(args...)});
template<class Out, class... Args> Out format_to(Out out, const locale& loc, string_view fmt, const Args&... args); template<class Out, class... Args> Out format_to(Out out, const locale& loc, wstring_view fmt, const Args&... args);
Effects: Equivalent to:
using context = basic_format_context<Out, decltype(fmt)::value_type>;
return vformat_to(out, loc, fmt, {make_format_args<context>(args...)});
template<class Out> Out vformat_to(Out out, string_view fmt, format_args_t<Out, char> args); template<class Out> Out vformat_to(Out out, wstring_view fmt, format_args_t<Out, wchar_t> args); template<class Out> Out vformat_to(Out out, const locale& loc, string_view fmt, format_args_t<Out, char> args); template<class Out> Out vformat_to(Out out, const locale& loc, wstring_view fmt, format_args_t<Out, wchar_t> args);
Let charT be decltype(fmt)​::​value_­type.
Constraints: Out satisfies output_­iterator<const charT&>.
Preconditions: Out models output_­iterator<const charT&>.
Effects: Places the character representation of formatting the arguments provided by args, formatted according to the specifications given in fmt, into the range [out, out + N), where N is formatted_­size(fmt, args...) for the functions without a loc parameter and formatted_­size(loc, fmt, args...) for the functions with a loc parameter.
If present, loc is used for locale-specific formatting.
Returns: out + N.
Throws: format_­error if fmt is not a format string.
template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, string_view fmt, const Args&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, wstring_view fmt, const Args&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, const locale& loc, string_view fmt, const Args&... args); template<class Out, class... Args> format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n, const locale& loc, wstring_view fmt, const Args&... args);
Let
  • charT be decltype(fmt)​::​value_­type,
  • N be formatted_­size(fmt, args...) for the functions without a loc parameter and formatted_­size(loc, fmt, args...) for the functions with a loc parameter, and
  • M be clamp(n, 0, N).
Constraints: Out satisfies output_­iterator<const charT&>.
Preconditions: Out models output_­iterator<const charT&>, and formatter<, charT> meets the Formatter requirements ([formatter.requirements]) for each in Args.
Effects: Places the first M characters of the character representation of formatting the arguments provided by args, formatted according to the specifications given in fmt, into the range [out, out + M).
If present, loc is used for locale-specific formatting.
Returns: {out + M, N}.
Throws: format_­error if fmt is not a format string.
template<class... Args> size_t formatted_size(string_view fmt, const Args&... args); template<class... Args> size_t formatted_size(wstring_view fmt, const Args&... args); template<class... Args> size_t formatted_size(const locale& loc, string_view fmt, const Args&... args); template<class... Args> size_t formatted_size(const locale& loc, wstring_view fmt, const Args&... args);
Let charT be decltype(fmt)​::​value_­type.
Preconditions: formatter<, charT> meets the Formatter requirements ([formatter.requirements]) for each in Args.
Returns: The number of characters in the character representation of formatting arguments args formatted according to specifications given in fmt.
If present, loc is used for locale-specific formatting.
Throws: format_­error if fmt is not a format string.