Namespaces
Variants

std:: format_to_n, std:: format_to_n_result

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(C++20)
format_to_n
(C++20)
(C++20)
(C++20)
(C++20)
Format strings
(C++20) (C++20) (C++20)
(C++26)
Formatting concepts
(C++23)
Formatter
(C++20)
(C++23)
(C++23)
(C++23)
(C++23)
(C++20) (C++20) (C++20)
(C++20) (C++20) (C++20)
(C++23)
(C++23)
Formatting arguments
(C++20)
(C++20)
(C++20) (C++20) (C++20)
(C++20) (deprecated in C++26)
(C++20) (C++20)
Format error
(C++20)
ヘッダーで定義 <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 はロケール固有のフォーマットに使用されます。

CharT を char としてオーバーロード (1,3) を、 wchar_t としてオーバーロード (2,4) を定義する。

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

OutputIt が std:: output_iterator < const CharT & > コンセプトの意味要件を満たさない場合、または std:: formatter < std:: remove_cvref_t < Ti > , CharT > が Args 内のいずれかの Ti について BasicFormatter 要件を満たさない場合、動作は未定義です。

5) std::format_to_n_result には基底クラスがなく、メンバーも out 、 size および暗黙的に宣言される特別なメンバー関数以外には存在しません。

目次

翻訳のポイント： - 「Contents」→「目次」に翻訳 - HTMLタグ、属性、リンク先は一切変更せず保持 - C++関連の専門用語（Parameters, Return value, Exceptions, Notes, Example, Defect reports, See also）は原文のまま保持 - 数字や構造は完全に維持 - プロフェッショナルな技術文書としての正確性を確保

パラメータ

out - 出力バッファへのイテレータ
n - バッファに書き込まれる最大文字数
fmt -
フォーマット文字列を表すオブジェクト。フォーマット文字列は以下から構成される：
  • { と } を除く通常の文字は、変更されずに出力にコピーされる
  • エスケープシーケンス { { と } } は、出力でそれぞれ { と } に置き換えられる
  • 置換フィールド

各置換フィールドは以下の形式を持つ：

{ arg-id (optional) } (1)
{ arg-id (optional) : format-spec } (2)
1) フォーマット指定なしの置換フィールド
2) フォーマット指定ありの置換フィールド
arg-id - フォーマットに使用される args 内の引数のインデックスを指定する。省略された場合、引数は順番に使用される。

フォーマット文字列内の arg-id はすべて存在するか、すべて省略されなければならない。手動インデックスと自動インデックスの混合はエラーである。

format-spec - 対応する引数に対する std::formatter 特殊化によって定義されるフォーマット仕様。 } で始めることはできない。

(C++23以降)
(C++26以降)
  • その他のフォーマット可能な型の場合、フォーマット仕様はユーザー定義の formatter 特殊化によって決定される。
args... - フォーマットされる引数
loc - std::locale ロケール固有のフォーマットに使用されるロケール

戻り値

format_to_n_result は、 out メンバが出力範囲の終端を過ぎたイテレータであり、 size メンバが全体（切り詰められていない）の出力サイズであるような結果を返します。

例外

formatterまたはiterator操作によってスローされた例外を伝播します。

注記

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でもcopyableでもないオブジェクト
（ジェネレーターのようなオブジェクト）はフォーマット不可 		これらのオブジェクトのフォーマットを許可
P2508R1 C++20 この機能に対するユーザー可視の名前が存在しない 名前 basic_format_string が公開される

関連項目

(C++20)
引数の書式化された表現を新しい文字列に格納する
(関数テンプレート)
(C++20)
出力イテレータを通じて引数の書式化された表現を書き出す
(関数テンプレート)
(C++20)
引数の書式化された表現を格納するために必要な文字数を決定する
(関数テンプレート)