[format.functions]

# 28 Text processing library [[text]](./#text)

## 28.5 Formatting [[format]](format#functions)

### 28.5.5 Formatting functions [format.functions]

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6697)

In the description of the functions, operator + is used
for some of the iterator categories for which it does not have to be defined[.](#1.sentence-1)

In these cases the semantics of a + n are
the same as in [[algorithms.requirements]](algorithms.requirements "26.2 Algorithms requirements")[.](#1.sentence-2)

[🔗](#lib:format)

`template<class... Args>
  string format(format_string<Args...> fmt, Args&&... args);
`

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6710)

*Effects*: Equivalent to:return vformat(fmt.*str*, make_format_args(args...));

[🔗](#lib:format_)

`template<class... Args>
  wstring format(wformat_string<Args...> fmt, Args&&... args);
`

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6725)

*Effects*: Equivalent to:return vformat(fmt.*str*, make_wformat_args(args...));

[🔗](#lib:format__)

`template<class... Args>
  string format(const locale& loc, format_string<Args...> fmt, Args&&... args);
`

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6740)

*Effects*: Equivalent to:return vformat(loc, fmt.*str*, make_format_args(args...));

[🔗](#lib:format___)

`template<class... Args>
  wstring format(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
`

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6755)

*Effects*: Equivalent to:return vformat(loc, fmt.*str*, make_wformat_args(args...));

[🔗](#lib:vformat)

`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);
`

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6772)

*Returns*: A string object holding the character representation of
formatting arguments provided by args formatted according to
specifications given in fmt[.](#6.sentence-1)

If present, loc is used for locale-specific formatting[.](#6.sentence-2)

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6779)

*Throws*: As specified in [[format.err.report]](format.err.report "28.5.3 Error reporting")[.](#7.sentence-1)

[🔗](#lib:format_to)

`template<class Out, class... Args>
  Out format_to(Out out, format_string<Args...> fmt, Args&&... args);
`

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6791)

*Effects*: Equivalent to:return vformat_to(std::move(out), fmt.*str*, make_format_args(args...));

[🔗](#lib:format_to_)

`template<class Out, class... Args>
  Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args);
`

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6806)

*Effects*: Equivalent to:return vformat_to(std::move(out), fmt.*str*, make_wformat_args(args...));

[🔗](#lib:format_to__)

`template<class Out, class... Args>
  Out format_to(Out out, const locale& loc, format_string<Args...>  fmt, Args&&... args);
`

[10](#10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6821)

*Effects*: Equivalent to:return vformat_to(std::move(out), loc, fmt.*str*, make_format_args(args...));

[🔗](#lib:format_to___)

`template<class Out, class... Args>
  Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args);
`

[11](#11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6836)

*Effects*: Equivalent to:return vformat_to(std::move(out), loc, fmt.*str*, make_wformat_args(args...));

[🔗](#lib:vformat_to)

`template<class Out>
  Out vformat_to(Out out, string_view fmt, format_args args);
template<class Out>
  Out vformat_to(Out out, wstring_view fmt, wformat_args args);
template<class Out>
  Out vformat_to(Out out, const locale& loc, string_view fmt, format_args args);
template<class Out>
  Out vformat_to(Out out, const locale& loc, wstring_view fmt, wformat_args args);
`

[12](#12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6857)

Let charT be decltype(fmt)​::​value_type[.](#12.sentence-1)

[13](#13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6860)

*Constraints*: Out satisfies [output_iterator](iterator.concept.output#concept:output_iterator "24.3.4.10 Concept output_­iterator [iterator.concept.output]")<const charT&>[.](#13.sentence-1)

[14](#14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6864)

*Preconditions*: Out models [output_iterator](iterator.concept.output#concept:output_iterator "24.3.4.10 Concept output_­iterator [iterator.concept.output]")<const charT&>[.](#14.sentence-1)

[15](#15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6868)

*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 the number of characters in that character representation[.](#15.sentence-1)

If present, loc is used for locale-specific formatting[.](#15.sentence-2)

[16](#16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6877)

*Returns*: out + N[.](#16.sentence-1)

[17](#17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6881)

*Throws*: As specified in [[format.err.report]](format.err.report "28.5.3 Error reporting")[.](#17.sentence-1)

[🔗](#lib:format_to_n)

`template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                      format_string<Args...> fmt, Args&&... args);
template<class Out, class... Args>
  format_to_n_result<Out> format_to_n(Out out, iter_difference_t<Out> n,
                                      wformat_string<Args...> fmt, 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, format_string<Args...> fmt,
                                      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, wformat_string<Args...> fmt,
                                      Args&&... args);
`

[18](#18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6905)

Let

- [(18.1)](#18.1)

charT be decltype(fmt.*str*)​::​value_type,

- [(18.2)](#18.2)

N beformatted_size(fmt, args...) for the functions without a loc parameter andformatted_size(loc, fmt, args...) for the functions with a loc parameter, and

- [(18.3)](#18.3)

M be clamp(n, 0, N)[.](#18.sentence-1)

[19](#19)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6915)

*Constraints*: Out satisfies [output_iterator](iterator.concept.output#concept:output_iterator "24.3.4.10 Concept output_­iterator [iterator.concept.output]")<const charT&>[.](#19.sentence-1)

[20](#20)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6919)

*Preconditions*: Out models [output_iterator](iterator.concept.output#concept:output_iterator "24.3.4.10 Concept output_­iterator [iterator.concept.output]")<const charT&>, andformatter<remove_cvref_t<Ti>, charT> meets the *BasicFormatter* requirements ([[formatter.requirements]](formatter.requirements "28.5.6.1 Formatter requirements"))
for each Ti in Args[.](#20.sentence-1)

[21](#21)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6926)

*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)[.](#21.sentence-1)

If present, loc is used for locale-specific formatting[.](#21.sentence-2)

[22](#22)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6934)

*Returns*: {out + M, N}[.](#22.sentence-1)

[23](#23)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6938)

*Throws*: As specified in [[format.err.report]](format.err.report "28.5.3 Error reporting")[.](#23.sentence-1)

[🔗](#lib:formatted_size)

`template<class... Args>
  size_t formatted_size(format_string<Args...> fmt, Args&&... args);
template<class... Args>
  size_t formatted_size(wformat_string<Args...> fmt, Args&&... args);
template<class... Args>
  size_t formatted_size(const locale& loc, format_string<Args...> fmt, Args&&... args);
template<class... Args>
  size_t formatted_size(const locale& loc, wformat_string<Args...> fmt, Args&&... args);
`

[24](#24)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6956)

Let charT be decltype(fmt.*str*)​::​value_type[.](#24.sentence-1)

[25](#25)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6959)

*Preconditions*: formatter<remove_cvref_t<Ti>, charT> meets the *BasicFormatter* requirements ([[formatter.requirements]](formatter.requirements "28.5.6.1 Formatter requirements"))
for each Ti in Args[.](#25.sentence-1)

[26](#26)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6965)

*Returns*: The number of characters in the character representation of
formatting arguments args formatted according to specifications given in fmt[.](#26.sentence-1)

If present, loc is used for locale-specific formatting[.](#26.sentence-2)

[27](#27)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L6972)

*Throws*: As specified in [[format.err.report]](format.err.report "28.5.3 Error reporting")[.](#27.sentence-1)