20 General utilities library [utilities]

20.20 Formatting [format]

20.20.4 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: As specified in [format.err.report].

🔗

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<type_identity_t<Out>, char> args);
template<class Out>
  Out vformat_to(Out out, wstring_view fmt,
                 format_args_t<type_identity_t<Out>, wchar_t> args);
template<class Out>
  Out vformat_to(Out out, const locale& loc, string_view fmt,
                 format_args_t<type_identity_t<Out>, char> args);
template<class Out>
  Out vformat_to(Out out, const locale& loc, wstring_view fmt,
                 format_args_t<type_identity_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: As specified in [format.err.report].

🔗

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

(16.1)
charT be decltype(fmt)::value_type,
(16.2)
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
(16.3)
M be clamp(n, 0, N).

Constraints: Out satisfies output_iterator<const charT&>.

Preconditions: Out models output_iterator<const charT&>, and formatter<

T_{i}

, charT> meets the Formatter requirements ([formatter.requirements]) for each

T_{i}

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: As specified in [format.err.report].

🔗

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<

T_{i}

, charT> meets the Formatter requirements ([formatter.requirements]) for each

T_{i}

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: As specified in [format.err.report].