namespace std {
template<class Out, class... Args>
Out format_to(Out out, format_string<Args...> fmt, Args&&... args); // (1)
template<class Out, class... Args>
Out format_to(Out out, wformat_string<Args...> fmt, Args&&... args); // (2)
template<class Out, class... Args>
Out format_to(Out out, const locale& loc, format_string<Args...> fmt, Args&&... args); // (3)
template<class Out, class... Args>
Out format_to(Out out, const locale& loc, wformat_string<Args...> fmt, Args&&... args); // (4)
}
概要
書式文字列fmt
に従ったフォーマットでargs...
の文字列表現を出力イテレータout
に出力する。
- (1): マルチバイト文字列版
- (2): ワイド文字列版
- (3): マルチバイト文字列版 (ロケール指定あり)
- (4): ワイド文字列版 (ロケール指定あり)
string buffer;
format_to(back_inserter(buffer), "The answer is {}.", 42);
書式文字列は定数式でなければならず、コンパイル時にチェックされる。実行時に決まるフォーマット文字列を使用したい場合、vformat_to
を使用できる。
適格要件
- 書式文字列は定数式であり、
string_view
(ワイド文字列版はwstring_view
)に暗黙変換できること。 - 書式文字列にエラーがないこと。例えば、
- 閉じていないカッコなどの構文エラーがないこと。
- 実際に渡している引数の型が書式文字列中の置換フィールドが要求する型に合うこと。
テンプレートパラメータ制約
Out
は以下の制約を満たす。
- (1),(3):
output_iterator<Out, const char&>
- (2),(4):
output_iterator<Out, const wchar_t&>
事前条件
Out
は以下のコンセプトのモデルである。
- (1),(3):
output_iterator<Out, const char&>
- (2),(4):
output_iterator<Out, const wchar_t&>
効果
以下のコードと等しい。
// (1), (2)
return vformat_to(out, fmt.str, make_format_args(args...));
// (3), (4)
return vformat_to(out, loc, fmt.str, make_wformat_args(args...));
戻り値
out + N
(ただし、N
=formatted_size(fmt, args...)
または formatted_size(loc, fmt, args...)
)
例外
フォーマット実行時に失敗した場合、format_error
を投げる。
備考
マルチバイト文字列、ワイド文字列の区別は、可変長引数部分で受け取れる文字列の型にも適用される。
例
#include <iostream>
#include <string>
#include <format>
int main()
{
std::string buffer;
std::format_to(std::back_inserter(buffer), "The answer is {}.", 42);
std::cout << buffer << std::endl;
}
出力
The answer is 42.
実装例
template<class Out, class... Args>
string format_to(Out out, format_string<Args...> fmt, const Args&... args)
{
return vformat_to(out, fmt.str, {make_format_args>(args...)});
}
template<class Out, class... Args>
wstring format_to(Out out, wformat_string<Args...> fmt, const Args&... args)
{
using context = basic_format_context<Out, decltype(fmt)::value_type>;
return vformat_to(out, fmt.str, {make_format_args<context>(args...)});
}
template<class Out, class... Args>
string format_to(Out out, const locale& loc, format_string<Args...> fmt, const Args&... args)
{
using context = basic_format_context<Out, decltype(fmt)::value_type>;
return vformat_to(out, loc, fmt.str, {make_format_args<context>(args...)});
}
template<class Out, class... Args>
wstring format_to(Out out, const locale& loc, wformat_string<Args...> fmt, const Args&... args)
{
using context = basic_format_context<Out, decltype(fmt)::value_type>;
return vformat_to(out, loc, fmt.str, {make_format_args<context>(args...)});
}
バージョン
言語
- C++20
処理系
- Clang: ??
- GCC: ??
- ICC: ??
- Visual C++: ??