std::make_format_args, std::make_wformat_args

 

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 Context = std::format_context, class... Args > /*format-arg-store*/<Context, Args...>     make_format_args( Args&... args );	(1)	(C++20以降)
template< class... Args > /*format-arg-store*/<std::wformat_context, Args...>     make_wformat_args( Args&... args );	(2)	(C++20以降)

書式設定引数の配列を格納し、std::basic_format_args<Context> に暗黙的に変換できるオブジェクトを返します。

Args 内のいずれかの Ti について、typename Context::template formatter_type<std::remove_const_t<Ti>> が BasicFormatter 要件を満たさない場合、動作は未定義です。

Args 内のいずれかの型 Ti について、Ti が __formattable_with<Context> を満たさない場合、プログラムは不正な形式です。

2) return std::make_format_args<std::wformat_context>(args...); と等価です。

パラメータ

args...

-

書式設定引数として使用される値

戻り値

書式設定引数を保持するオブジェクト。

型 T の各引数 t について、TD を std::remove_const_t<std::remove_reference_t<T>> とします。結果の対応する std::basic_format_arg は以下のように決定されます。

• TD が bool または Context::char_type の場合、std::basic_format_arg は t を格納します。
• それ以外の場合、TD が char で Context::char_type が wchar_t の場合、std::basic_format_arg は static_cast<wchar_t>(static_cast<unsigned char>(t)) を格納します。
• それ以外の場合、TD が int 以下のサイズの符号付き整数型の場合、std::basic_format_arg は static_cast<int>(t) を格納します。
• それ以外の場合、TD が unsigned int 以下のサイズの符号なし整数型の場合、std::basic_format_arg は static_cast<unsigned int>(t) を格納します。
• それ以外の場合、TD が long long 以下のサイズの符号付き整数型の場合、std::basic_format_arg は static_cast<long long>(t) を格納します。
• それ以外の場合、TD が unsigned long long 以下のサイズの符号なし整数型の場合、std::basic_format_arg は static_cast<unsigned long long>(t) を格納します。
• それ以外の場合、TD が float、double、または long double の場合、std::basic_format_arg は t を格納します。
• それ以外の場合、TD が std::basic_string_view または std::basic_string 特殊化で TD::char_type が Context::char_type の場合、std::basic_format_arg は std::basic_string_view<Context::char_type>(t.data(), t.size()) を格納します。
• それ以外の場合、std::decay_t<TD> が Context::char_type* または const Context::char_type* の場合、std::basic_format_arg は static_cast<const Context::char_type*>(t) を格納します。
• それ以外の場合、std::is_void_v<std::remove_pointer_t<TD>> が true または std::is_null_pointer_v<TD> が true の場合、std::basic_format_arg は static_cast<const void*>(t) を格納します。
• それ以外の場合、std::basic_format_arg は、handle::format() に必要な追加データとともに、t への std::basic_format_arg<Context>::handle を格納します。

備考

書式設定引数はユーザー定義型に対して参照セマンティクスを持ち、args の寿命を延長しません。戻り値よりも args の寿命が長いことを保証するのはプログラマの責任です。通常、結果は書式設定関数の引数としてのみ使用されます。

機能テストマクロ	値	規格	機能
__cpp_lib_format_uchar	202311L	(C++20) (DR)	符号なし整数としてのコード単位の書式設定

例

このコードを実行

#include <array>
#include <format>
#include <iostream>
#include <string_view>
 
void raw_write_to_log(std::string_view users_fmt, std::format_args&& args)
{
    static int n{};
    std::clog << std::format("{:04} : ", n++) << std::vformat(users_fmt, args) << '\n';
}
 
template<typename... Args>
constexpr void log(Args&&... args)
{
    // Generate formatting string "{} "...
    std::array<char, sizeof...(Args) * 3 + 1> braces{};
    constexpr const char c[4] = "{} ";
    for (auto i{0uz}; i != braces.size() - 1; ++i)
        braces[i] = c[i % 3];
    braces.back() = '\0';
 
    raw_write_to_log(std::string_view{braces.data()}, std::make_format_args(args...));
}
 
template<typename T>
const T& unmove(T&& x)
{
    return x;
}
 
int main()
{
    log("Number", "of", "arguments", "is", "arbitrary.");
    log("Any type that meets the BasicFormatter requirements", "can be printed.");
    log("For example:", 1, 2.0, '3', "*42*");
 
    raw_write_to_log("{:02} │ {} │ {} │ {}",
                     std::make_format_args(unmove(1), unmove(2.0), unmove('3'), "4"));
}

出力

0000 : Number of arguments is arbitrary.
0001 : Any type that meets the BasicFormatter requirements can be printed.
0002 : For example: 1 2.0 3 *42*
0003 : 01 │ 2.0 │ 3 │ 4

欠陥報告

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

DR	適用対象	公開された動作	正しい動作
P2418R2	C++20	const-usableでもコピー可能でもないオブジェクト （ジェネレータのようなオブジェクトなど）はフォーマットできない	これらのオブジェクトのフォーマットを許可する
P2905R2	C++20	make_format_args は転送参照によって右辺値引数を受け入れました	左辺値参照のみを受け取る
P2909R4	C++20	char または wchar_t は以下のように書式設定される可能性があります 範囲外の符号なし整数値	コード単位は対応する型に変換されます このような書式設定の前に符号なし型に変換されます
LWG 3631	C++20	P2418R2 の後、cv修飾された引数が誤って処理されました	処理が修正されました

関連項目

basic_format_argsformat_argswformat_args (C++20)(C++20)(C++20)	すべてのフォーマット引数へのアクセスを提供するクラス (クラステンプレート)
vformat (C++20)	型消去された引数表現を使用する std::format の非テンプレート版 (関数)
vformat_to (C++20)	型消去された引数表現を使用する std::format_to の非テンプレート版 (関数テンプレート)