304 lines
10 KiB
Markdown
304 lines
10 KiB
Markdown
[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)
|