std::format_to

 

C++

コンパイラサポート

フリースタンディングとホスト

言語

標準ライブラリ

標準ライブラリヘッダー

名前付き要件

機能テストマクロ (C++20)

言語サポートライブラリ

コンセプトライブラリ (C++20)

診断ライブラリ

メモリ管理ライブラリ

メタプログラミングライブラリ (C++11)

汎用ユーティリティライブラリ

コンテナライブラリ

イテレータライブラリ

Rangesライブラリ (C++20)

アルゴリズムライブラリ

文字列ライブラリ

テキスト処理ライブラリ

数値ライブラリ

日付と時刻ライブラリ

入出力ライブラリ

ファイルシステムライブラリ (C++17)

並行サポートライブラリ (C++11)

実行制御ライブラリ (C++26)

Technical specifications (技術仕様)

シンボルインデックス

外部ライブラリ

 

テキスト処理ライブラリ

ローカライズライブラリ

正規表現ライブラリ (C++11)

フォーマットライブラリ (C++20)

ヌル終端シーケンスユーティリティ

バイト文字列

マルチバイト文字列

ワイド文字列

プリミティブな数値変換

to_chars (C++17) to_chars_result (C++17) from_chars (C++17) from_chars_result (C++17) chars_format (C++17)

テキストエンコーディング識別

text_encoding (C++26)

 

書式設定ライブラリ

標準フォーマット指定

フォーマット関数

format (C++20)

format_to (C++20)

format_to_n (C++20)

formatted_size (C++20)

vformat (C++20)

vformat_to (C++20)

フォーマット文字列

basic_format_stringformat_stringwformat_string (C++20)(C++20)(C++20)

runtime_format (C++26)

フォーマット関連コンセプト

formattable (C++23)

フォーマッタ

formatter (C++20)

formatter<pair-or-tuple> (C++23)

formatter<range> (C++23)

range_formatter (C++23)

enable_nonlocking_formatter_optimization (C++23)

basic_format_parse_contextformat_parse_contextwformat_parse_context (C++20)(C++20)(C++20)

basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)

range_format (C++23)

format_kind (C++23)

フォーマット引数

basic_format_arg (C++20)

basic_format_arg::handle (C++20)

basic_format_argsformat_argswformat_args (C++20)(C++20)(C++20)

visit_format_arg (C++20) (C++26で非推奨)

make_format_argsmake_wformat_args (C++20)(C++20)

フォーマットエラー

format_error (C++20)

 

ヘッダー <format> で定義
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out,                     std::format_string<Args...> fmt, Args&&... args );	(1)	(C++20以降)
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out,                     std::wformat_string<Args...> fmt, Args&&... args );	(2)	(C++20以降)
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, const std::locale& loc,                     std::format_string<Args...> fmt, Args&&... args );	(3)	(C++20以降)
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, const std::locale& loc,                     std::wformat_string<Args...> fmt, Args&&... args );	(4)	(C++20以降)

フォーマット文字列 fmt に従って引数 args をフォーマットし、結果を出力イテレータ out に書き込みます。指定されている場合、 loc はロケール固有のフォーマットに使用されます。

以下と等価です。

1) return std::vformat_to(std::move(out), fmt.str, std::make_format_args(args...));

2) return std::vformat_to(std::move(out), fmt.str, std::make_wformat_args(args...));

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

4) return std::vformat_to(std::move(out), loc, fmt.str, std::make_wformat_args(args...));。

オーバーロード (1,3) では CharT は char、オーバーロード (2,4) では wchar_t です。

これらのオーバーロードは、 OutputIt がコンセプト std::output_iterator<const CharT&> を満たす場合にのみ、オーバーロード解決に参加します。

次のいずれかの条件が満たされる場合、動作は未定義です。

• OutputIt は std::output_iterator<const CharT&> をモデル化しません。
• Args 内のいくつかの Ti について、 std::formatter<Ti, CharT> は BasicFormatter の要件を満たさないため、 std::make_format_args および std::make_wformat_args から要求されます。

Parameters

out	-	出力バッファへのイテレータ
fmt	-	フォーマット文字列を表すオブジェクト。フォーマット文字列は以下で構成される： 通常の文字（{ と } を除く）は、変更されずに出力にコピーされる。 エスケープシーケンス {{ と }} は、それぞれ出力で { と } に置き換えられる。 置換フィールド。 各置換フィールドは以下の形式を持つ。 { arg-id (オプション) } (1) { arg-id (オプション) : format-spec } (2) 1) フォーマット指定なしの置換フィールド 2) フォーマット指定ありの置換フィールド arg-id - フォーマットに使用する args 内の引数のインデックスを指定する。省略された場合、引数は順番に使用される。 フォーマット文字列内の arg-id は、すべて存在するか、すべて省略されなければならない。手動と自動のインデックス付けを混在させることはエラーである。 format-spec - 対応する引数に対する std::formatter 特殊化によって定義されるフォーマット指定。} で開始することはできない。 基本型および標準文字列型の場合、フォーマット指定は標準フォーマット指定として解釈される。 chrono型の場合、フォーマット指定はchronoフォーマット指定として解釈される。 範囲型の場合、フォーマット指定は範囲フォーマット指定として解釈される。 std::pair および std::tuple の場合、フォーマット指定はtupleフォーマット指定として解釈される。 std::thread::id および std::stacktrace_entry の場合、スレッドIDフォーマット指定およびスタックトレースエントリフォーマット指定を参照。 std::basic_stacktrace の場合、フォーマット指定子は許可されない。 (C++23から) std::filesystem::path の場合、パスフォーマット指定を参照。 (C++26以降) その他のフォーマット可能な型の場合、フォーマット指定はユーザー定義の formatter 特殊化によって決定される。
args...	-	フォーマットする引数
loc	-	ロケール固有のフォーマットに使用される std::locale

Return value

出力範囲の終端以降のイテレータ。

Exceptions

フォーマッタまたはイテレータ操作によってスローされた例外を伝播します。

Notes

P2216R3 によると、フォーマット文字列が定数式でない場合はエラーとなります。この場合、 std::vformat_to （または std::runtime_format （ C++26 以降））を使用できます。

Example

このコードを実行

#include <format>
#include <iostream>
#include <iterator>
#include <string>
 
int main()
{
    std::string buffer;
 
    std::format_to
    (
        std::back_inserter(buffer), // < OutputIt
        "Hello, C++{}!\n",          // < fmt
        "20"                        // < arg
    );
    std::cout << buffer;
    buffer.clear();
 
    std::format_to
    (
        std::back_inserter(buffer), // < OutputIt
        "Hello, {0}::{1}!{2}",      // < fmt
        "std",                      // < arg {0}
        "format_to()",              // < arg {1}
        "\n",                       // < arg {2}
        "extra param(s)..."         // < unused
    );
    std::cout << buffer << std::flush;
 
    std::wstring wbuffer;
    std::format_to
    (
        std::back_inserter(wbuffer),// < OutputIt
        L"Hello, {2}::{1}!{0}",     // < fmt
        L"\n",                      // < arg {0}
        L"format_to()",             // < arg {1}
        L"std",                     // < arg {2}
        L"...is not..."             // < unused
        L"...an error!"             // < unused
    );
    std::wcout << wbuffer;
}

出力

Hello, C++20!
Hello, std::format_to()!
Hello, std::format_to()!

Defect reports

以下の動作変更を伴う欠陥報告が、以前に公開されたC++標準に遡って適用されました。

DR	適用対象	公開された動作	正しい動作
LWG 3539	C++20	out はムーブオンリーイテレータではありえなかった	そうである場合がある
P2216R3	C++20	無効なフォーマット文字列に対して std::format_error をスローします。	代わりにコンパイル時エラーとなる
P2418R2	C++20	const-usableでもコピー可能でもないオブジェクト （ジェネレータのようなオブジェクトなど）はフォーマットできない	これらのオブジェクトのフォーマットを許可する
P2508R1	C++20	この機能にはユーザーから見える名前がない	basic_format_stringという名前が公開された

See also

format (C++20)	引数のフォーマット済み表現を新しい文字列に格納する (関数テンプレート)
format_to_n (C++20)	指定されたサイズを超えないように、引数のフォーマット済み表現を出力イテレータを介して書き出す (関数テンプレート)