4. format_to

最終更新日時(UTC):
が更新

履歴 編集

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は以下の制約を満たす。

事前条件

Outは以下のコンセプトのモデルである。

効果

以下のコードと等しい。

// (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

処理系

参照