最終更新日時(UTC): 2026年01月20日 03時05分18秒
Akira Takahashi が更新

履歴 編集

function template
<format>

# std::format_to(C++20)

    namespace std {
      template<class Out, class... Args>
      Out
        format_to(Out out,
                  format_string<Args...> fmt,
                  Args&&... args);            // (1) C++20
      template<class Out, class... Args>
      constexpr Out
        format_to(Out out,
                  format_string<Args...> fmt,
                  Args&&... args);            // (1) C++26

      template<class Out, class... Args>
      Out
        format_to(Out out,
                  wformat_string<Args...> fmt,
                  Args&&... args);            // (2) C++20
      template<class Out, class... Args>
      constexpr Out
        format_to(Out out,
                  wformat_string<Args...> fmt,
                  Args&&... args);            // (2) C++26

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

      template<class Out, class... Args>
      Out
        format_to(Out out,
                  const locale& loc,
                  wformat_string<Args...> fmt,
                  Args&&... args);            // (4) C++20
    }

## 概要

書式文字列`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++: ??

## 参照

- Working Draft, Standard for Programming Language C++ [format]
- P0645R10 Text Formatting
- P2216R3 std::format improvements
- ［C++］ std::formatあるいは{fmt}のコンパイル時フォーマット文字列チェックの魔術 - 地面を見下ろす少年の足蹴にされる私
- P2418R2 Add support for `std::generator`-like types to `std::format`
- P3391R2 `constexpr std::format`
  - C++26から非ロケール版が`constexpr`に対応した