std::formatter

 

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 T, class CharT = char > struct formatter;		(C++20以降)

std::formatter の有効化された特殊化は、指定された型のフォーマット規則を定義します。有効化された特殊化は BasicFormatter の要件を満たし、特に指定がない限り Formatter の要件も満たします。

std::formatter<T, CharT> の特殊化が有効化されていないすべての型 T および CharT について、その特殊化は完全な型であり、無効化されています。

無効化された特殊化は Formatter の要件を満たさず、以下のすべてが false となります。

• std::is_default_constructible_v
• std::is_copy_constructible_v
• std::is_move_constructible_v
• std::is_copy_assignable_v
• std::is_move_assignable_v.

基本的な標準特殊化

以下のリストでは、CharT は char または wchar_t、ArithmeticT は char、wchar_t、char8_t、char16_t、または char32_t 以外の任意の cv-修飾されていない算術型です。

文字フォーマッタ
template<> struct formatter<char, char>;	(1)
template<> struct formatter<char, wchar_t>;	(2)
template<> struct formatter<wchar_t, wchar_t>;	(3)
文字列フォーマッタ
template<> struct formatter<CharT*, CharT>;	(4)
template<> struct formatter<const CharT*, CharT>;	(5)
template< std::size_t N > struct formatter<CharT[N], CharT>;	(6)
template< class Traits, class Alloc > struct formatter<std::basic_string<CharT, Traits, Alloc>, CharT>;	(7)
template< class Traits > struct formatter<std::basic_string_view<CharT, Traits>, CharT>;	(8)
算術フォーマッタ
template<> struct formatter<ArithmeticT, CharT>;	(9)
ポインタフォーマッタ
template<> struct formatter<std::nullptr_t, CharT>;	(10)
template<> struct formatter<void*, CharT>;	(11)
template<> struct formatter<const void*, CharT>;	(12)

その他のポインタやメンバポインタのフォーマッタは無効化されています。

std::formatter<wchar_t, char> や std::formatter<const char*, wchar_t> のような、エンコーディング変換を必要とする特殊化は無効化されています。

C++23 では、一部の char シーケンスを wchar_t の範囲としてフォーマットすることを避けるため、以下の特殊化は引き続き無効化されています。 無効化された wchar_t 用フォーマッタ template<> struct formatter<char*, wchar_t>; (1) template<> struct formatter<const char*, wchar_t>; (2) template< std::size_t N > struct formatter<char[N], wchar_t>; (3) template< class Traits, class Allocator > struct formatter<std::basic_string<char, Traits, Allocator>, wchar_t>; (4) template< class Traits > struct formatter<std::basic_string_view<char, Traits>, wchar_t>; (5) デバッグ有効なフォーマッタ特殊化は、さらに公開の非静的メンバ関数 constexpr void set_debug_format(); を提供します。これは、フォーマッタオブジェクトの状態を変更し、フォーマット仕様の最後の parse の呼び出しで解析されたフォーマット指定子の type が ? であるかのように、値をエスケープおよび引用符付きでフォーマットするようにします。 文字列型または文字型の各フォーマッタ特殊化は、デバッグ有効です。

(C++23から)

ライブラリ型のための標準特殊化

std::formatter<std::chrono::duration> (C++20)	duration の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::sys_time> (C++20)	sys_time の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::utc_time> (C++20)	utc_time の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::tai_time> (C++20)	tai_time の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::gps_time> (C++20)	gps_time の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::file_time> (C++20)	file_time の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::local_time> (C++20)	local_time の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::day> (C++20)	day の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::month> (C++20)	month の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::year> (C++20)	year の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::weekday> (C++20)	weekday の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::weekday_indexed> (C++20)	weekday_indexed の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::weekday_last> (C++20)	weekday_last の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::month_day> (C++20)	month_day の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::month_day_last> (C++20)	month_day_last の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::month_weekday> (C++20)	month_weekday の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::month_weekday_last> (C++20)	month_weekday_last の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::year_month> (C++20)	year_month の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::year_month_day> (C++20)	year_month_day の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::year_month_day_last> (C++20)	year_month_day_last の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::year_month_weekday> (C++20)	year_month_weekday の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::year_month_weekday_last> (C++20)	year_month_weekday_last の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::hh_mm_ss> (C++20)	hh_mm_ss の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::sys_info> (C++20)	sys_info の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::local_info> (C++20)	local_info の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::chrono::zoned_time> (C++20)	zoned_time の書式設定サポート (クラス テンプレートの特殊化)
std::formatter<std::basic_stacktrace> (C++23)	basic_stacktrace のフォーマットサポート (クラステンプレート特殊化)
std::formatter<std::stacktrace_entry> (C++23)	stacktrace_entry のフォーマットサポート (クラステンプレート特殊化)
std::formatter<std::thread::id> (C++23)	thread::id のフォーマットサポート (クラステンプレート特殊化)
std::formatter<std::vector<bool>::reference> (C++23)	vector<bool>::reference のフォーマットサポート (クラステンプレート特殊化)
std::formatter<pair-or-tuple> (C++23)	pair と tuple のフォーマットサポート (クラステンプレート特殊化)
std::formatter<range> (C++23)	範囲 (range) のフォーマットサポート (クラステンプレート特殊化)
std::formatter<std::stack> (C++23)	std::stack のフォーマットサポート (class template specialization)
std::formatter<std::queue> (C++23)	std::queue のフォーマットサポート (class template specialization)
std::formatter<std::priority_queue> (C++23)	std::priority_queue のフォーマットサポート (class template specialization)
std::formatter<std::filesystem::path> (C++26)	filesystem::path のフォーマットサポート (クラステンプレート特殊化)

例

このコードを実行

#include <algorithm>
#include <format>
#include <iomanip>
#include <iostream>
#include <sstream>
#include <string_view>
 
struct QuotableString : std::string_view
{};
 
template<>
struct std::formatter<QuotableString, char>
{
    bool quoted = false;
 
    template<class ParseContext>
    constexpr ParseContext::iterator parse(ParseContext& ctx)
    {
        auto it = ctx.begin();
        if (it == ctx.end())
            return it;
 
        if (*it == '#')
        {
            quoted = true;
            ++it;
        }
        if (it != ctx.end() && *it != '}')
            throw std::format_error("Invalid format args for QuotableString.");
 
        return it;
    }
 
    template<class FmtContext>
    FmtContext::iterator format(QuotableString s, FmtContext& ctx) const
    {
        std::ostringstream out;
        if (quoted)
            out << std::quoted(s);
        else
            out << s;
 
        return std::ranges::copy(std::move(out).str(), ctx.out()).out;
    }
};
 
int main()
{
    QuotableString a("be"), a2(R"( " be " )");
    QuotableString b("a question");
    std::cout << std::format("To {0} or not to {0}, that is {1}.\n", a, b);
    std::cout << std::format("To {0:} or not to {0:}, that is {1:}.\n", a, b);
    std::cout << std::format("To {0:#} or not to {0:#}, that is {1:#}.\n", a2, b);
}

出力

To be or not to be, that is a question.
To be or not to be, that is a question.
To " \" be \" " or not to " \" be \" ", that is "a question".

不具合報告

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

DR	適用対象	公開された動作	正しい動作
LWG 3944	C++23	一部の char シーケンスが wchar_t の範囲としてフォーマット可能であった	特殊化が無効化された

関連項目

basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)	すべてのフォーマット引数と出力イテレータを含むフォーマット状態 (クラステンプレート)
formattable (C++23)	型がフォーマット可能であること、すなわち std::formatter を特殊化し、parse および format メンバ関数を提供することを示します。 (コンセプト)
range_formatter (C++23)	std::formatter の特殊化を範囲型に対して実装するのに役立つクラステンプレート。 (クラステンプレート)