std::format_to_n, std::format_to_n_result

ヘッダー `<format>` で定義
template< class OutputIt, class... Args > std::format_to_n_result<OutputIt> format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n, std::format_string<Args...> fmt, Args&&... args );	(1)	(C++20以降)
template< class OutputIt, class... Args > std::format_to_n_result<OutputIt> format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n, std::wformat_string<Args...> fmt, Args&&... args );	(2)	(C++20以降)
template< class OutputIt, class... Args > std::format_to_n_result<OutputIt> format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n, const std::locale& loc, std::format_string<Args...> fmt, Args&&... args );	(3)	(C++20以降)
template< class OutputIt, class... Args > std::format_to_n_result<OutputIt> format_to_n( OutputIt out, std::iter_difference_t<OutputIt> n, const std::locale& loc, std::wformat_string<Args...> fmt, Args&&... args );	(4)	(C++20以降)
ヘルパー型
template< class OutputIt > struct format_to_n_result { OutputIt out; std::iter_difference_t<OutputIt> size; };	(5)	(C++20以降)

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

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

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

OutputIt がコンセプト std::output_iterator<const CharT&> の意味的要件を満たさない場合、または Args 内の任意の Ti に対して std::formatter<std::remove_cvref_t<Ti>, CharT> が BasicFormatter 要件を満たさない場合、振る舞いは未定義です。

5) std::format_to_n_result は基底クラスを持たず、 out 、 size 、および暗黙的に宣言された特殊メンバ関数以外のメンバを持ちません。

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

[編集] 戻り値

format_to_n_result。その out メンバは出力範囲の末尾の次を指すイテレータであり、 size メンバは合計（切り詰められていない）出力サイズです。

[編集] 例外

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

[編集] 注記

GCC-13.3 より前の libstdc++ の実装には、 format_to_n_result::out の正しい値を報告する際のバグがありました。

[編集] 例

Godbolt's Compiler Explorer で: clang (trunk) + libc++、 GCC (trunk) + libstdc++。

このコードを実行

#include <format>
#include <initializer_list>
#include <iomanip>
#include <iostream>
#include <string_view>
 
int main()
{
    char buffer[64];
 
    for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz, 21uz})
    {
        const std::format_to_n_result result =
            std::format_to_n(
                buffer, max_chars_to_write,
                "Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.", // 24 bytes w/o formatters
                71,       // {0}, occupies 2 bytes
                8,        // {1}, occupies 1 byte
                "\u2080", // {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO)
                "\u2245", // {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO)
                "\u00B1"  // {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN)
                ); // 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\0'
 
        *result.out = '\0'; // adds terminator to buffer
 
        const std::string_view str(buffer, result.out);
 
        std::cout << "Buffer until '\\0': " << std::quoted(str) << '\n'
                  << "Max chars to write: " << max_chars_to_write << '\n'
                  << "result.out offset: " << result.out - buffer << '\n'
                  << "Untruncated output size: " << result.size << "\n\n";
    }
}

出力

Buffer until '\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc."
Max chars to write: 63
result.out offset: 35
Untruncated output size: 35
 
Buffer until '\0': "Hubble's H₀ ≅ 71±8"
Max chars to write: 23
result.out offset: 23
Untruncated output size: 35
 
Buffer until '\0': "Hubble's H₀ ≅ 71�"
Max chars to write: 21
result.out offset: 21
Untruncated output size: 35

[編集] 不具合報告

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

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

[編集] 関連項目

format (C++20)	引数のフォーマット済み表現を新しい文字列に格納する (関数テンプレート) [編集]
format_to (C++20)	引数のフォーマット済み表現を出力イテレータを介して書き出す (関数テンプレート) [編集]
formatted_size (C++20)	引数のフォーマット済み表現を格納するために必要な文字数を決定する (関数テンプレート) [編集]

コンパイラサポート
フリースタンディングとホスト
言語
標準ライブラリ
標準ライブラリヘッダー
名前付き要件
機能テストマクロ (C++20)
言語サポートライブラリ
コンセプトライブラリ (C++20)
診断ライブラリ
メモリ管理ライブラリ
メタプログラミングライブラリ (C++11)
汎用ユーティリティライブラリ
コンテナライブラリ
イテレータライブラリ
Rangesライブラリ (C++20)
アルゴリズムライブラリ
文字列ライブラリ
テキスト処理ライブラリ
数値ライブラリ
日付と時刻ライブラリ
入出力ライブラリ
ファイルシステムライブラリ (C++17)
並行サポートライブラリ (C++11)
実行制御ライブラリ (C++26)
Technical specifications (技術仕様)
シンボルインデックス
外部ライブラリ

標準フォーマット指定
フォーマット関数
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)

cppreference.com

名前空間

変種

表示

操作