cppdraft_translate/cppdraft/format/functions.md

[format.functions]

28 Text processing library [text]

28.5 Formatting [format]

28.5.5 Formatting functions [format.functions]

1

#

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(format_string<Args...> fmt, Args&&... args);

2

#

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

🔗

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

3

#

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

🔗

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

4

#

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

🔗

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

5

#

Effects: Equivalent to:return vformat(loc, fmt.str, 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);

6

#

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.

7

#

Throws: As specified in [format.err.report].

🔗

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

8

#

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

🔗

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

9

#

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

🔗

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

10

#

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

🔗

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

11

#

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

🔗

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

#

Let charT be decltype(fmt)​::​value_type.

13

#

Constraints: Out satisfies output_iterator<const charT&>.

14

#

Preconditions: Out models output_iterator<const charT&>.

15

#

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.

If present, loc is used for locale-specific formatting.

16

#

Returns: out + N.

17

#

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, 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

#

Let

• (18.1)

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

• (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)

M be clamp(n, 0, N).

19

#

Constraints: Out satisfies output_iterator<const charT&>.

20

#

Preconditions: Out models output_iterator<const charT&>, andformatter<remove_cvref_t, charT> meets the BasicFormatter requirements ([formatter.requirements]) for each Ti in Args.

21

#

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.

22

#

Returns: {out + M, N}.

23

#

Throws: As specified in [format.err.report].

🔗

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

#

Let charT be decltype(fmt.str)​::​value_type.

25

#

Preconditions: formatter<remove_cvref_t, charT> meets the BasicFormatter requirements ([formatter.requirements]) for each Ti in Args.

26

#

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.

27

#

Throws: As specified in [format.err.report].