フォーマットライブラリ (C++20 から)

 

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)

 

テキストフォーマットライブラリは、printfファミリ関数に代わる、安全で拡張可能な代替手段を提供します。これは、既存のC++ I/Oストリームライブラリを補完することを目的としています。

フォーマット指定

フォーマット指定は、オブジェクトがさまざまな種類のオプションでどのようにフォーマットされるかを指定します。

基本型および標準文字列型のオブジェクトのフォーマットには、基本フォーマット指定が使用されます。他のライブラリコンポーネントも独自のフォーマット指定を提供することがあります。詳細はこちらを参照してください。

フォーマット関数

ヘッダー <format> で定義
format (C++20)	引数のフォーマット済み表現を新しい文字列に格納する (関数テンプレート)
format_to (C++20)	引数のフォーマット済み表現を出力イテレータを介して書き出す (関数テンプレート)
format_to_n (C++20)	指定されたサイズを超えないように、引数のフォーマット済み表現を出力イテレータを介して書き出す (関数テンプレート)
formatted_size (C++20)	引数のフォーマット済み表現を格納するために必要な文字数を決定する (関数テンプレート)

フォーマット文字列

ヘッダー <format> で定義
basic_format_stringformat_stringwformat_string (C++20)(C++20)(C++20)	構築時にコンパイル時フォーマット文字列チェックを実行するクラステンプレート (クラステンプレート)
runtime_format (C++26)	ユーザー指向のフォーマット関数で直接使用可能な実行時フォーマット文字列を作成する (関数)

フォーマット関連コンセプト

ヘッダー <format> で定義
formattable (C++23)	型がフォーマット可能であること、つまり std::formatter を特殊化し、メンバ関数 parse および format を提供することを指定する (コンセプト)

拡張性サポートと実装詳細

ヘッダー <format> で定義
vformat (C++20)	型消去された引数表現を使用する std::format の非テンプレート版 (関数)
vformat_to (C++20)	型消去された引数表現を使用する std::format_to の非テンプレート版 (関数テンプレート)
make_format_argsmake_wformat_args (C++20)(C++20)	format_args に変換可能な、すべてのフォーマット引数を参照する型消去されたオブジェクトを作成する (関数テンプレート)
visit_format_arg (C++20) (C++26で非推奨)	ユーザー定義フォーマッタのための引数訪問インターフェース (関数テンプレート)
formatter (C++20)	与えられた型のフォーマット規則を定義する (クラステンプレート)
range_formatter (C++23)	範囲型の std::formatter 特殊化の実装を助けるクラステンプレート (クラステンプレート)
enable_nonlocking_formatter_optimization (C++23)	引数型が効率的に出力できることを示す (変数テンプレート)
range_format (C++23)	範囲をどのようにフォーマットするかを指定する (enum)
format_kind (C++23)	範囲に適した std::range_format を選択する (変数テンプレート)
basic_format_arg (C++20)	ユーザー定義フォーマッタのためにフォーマット引数へのアクセスを提供するクラステンプレート (クラステンプレート)
basic_format_argsformat_argswformat_args (C++20)(C++20)(C++20)	すべてのフォーマット引数へのアクセスを提供するクラス (クラステンプレート)
basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)	すべてのフォーマット引数と出力イテレータを含むフォーマット状態 (クラステンプレート)
basic_format_parse_contextformat_parse_contextwformat_parse_context (C++20)(C++20)(C++20)	フォーマット文字列パーサの状態 (クラステンプレート)
format_error (C++20)	フォーマットエラー時にスローされる例外型 (クラス)

ヘルパー項目 (C++23から)

template< class R, class CharT > concept /*const-formattable-range*/ =     ranges::input_range<const R> &&     std::formattable<ranges::range_reference_t<const R>, CharT>;	(1)	(説明用*)
template< class R, class CharT > using /*fmt-maybe-const*/ =     std::conditional_t</*const-formattable-range*/<R, CharT>, const R, R>;	(2)	(説明用*)

注釈

機能テストマクロ	値	規格	機能
__cpp_lib_format	201907L	(C++20)	テキストフォーマット
	202106L	(C++23) (DR20)	コンパイル時フォーマット文字列チェック； std::vformat_toのパラメータ化の削減
	202110L	(C++23) (DR20)	chronoフォーマッタにおけるロケール処理の修正； const-formattableでない型のサポート
	202207L	(C++23) (DR20)	std::basic_format_stringの公開； chrono型のローカライズされたフォーマットにおけるエンコーディングの取り扱いの明確化
	202304L	(C++26)	ポインタのフォーマット
	202305L	(C++26)	フォーマット引数の型チェック
	202306L	(C++26)	メンバ std::basic_format_arg::visit
	202311L	(C++26)	実行時フォーマット文字列
	202403L	(C++26)	std::printlnによる空行の出力
	202403L	(C++26) (DR23)	std::printの効率的な実装を許可
__cpp_lib_format_ranges	202207L	(C++23)	範囲のフォーマット
__cpp_lib_format_path	202403L	(C++26)	std::filesystem::pathのフォーマット
__cpp_lib_format_uchar	202311L	(C++26)	コードユニットの整数としてのフォーマットを修正
__cpp_lib_formatters	202302L	(C++23)	std::thread::id と std::stacktrace のフォーマット

我々は意図的に、std::basic_format_string の追加（P2508）を欠陥報告として扱います。なぜなら、公式にはそう分類されていませんが、既知のすべての実装がこれらのコンポーネントをC++20モードで利用可能にしているためです。

例

このコードを実行

#include <cassert>
#include <format>
 
int main()
{
    std::string message = std::format("The answer is {}.", 42);
    assert(message == "The answer is 42.");
}

欠陥報告

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

DR	適用対象	公開された動作	正しい動作
P2418R2	C++20	const-formattableでもコピー可能でもないオブジェクト （ジェネレータのようなオブジェクトなど）はフォーマットできない	これらのオブジェクトのフォーマットを許可する （フォーマッタ要件の緩和）
P2508R1	C++20	この機能にはユーザーから見える名前がない	basic_format_stringという名前が公開された

関連項目

print (C++23)	引数のフォーマット済み表現を用いて stdout またはファイルストリームに出力する (関数テンプレート)
println (C++23)	std::printと同じだが、各出力の末尾に改行が追加される点が異なる (関数テンプレート)
print(std::ostream) (C++23)	引数のフォーマット済み表現を出力する (関数テンプレート)