std::range_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 >     requires std::same_as<std::remove_cvref_t<T>, T> && std::formattable<T, CharT> class range_formatter;		(C++23から)

std::range_formatterは、範囲 std::formatter の特殊化を実装するためのヘルパークラステンプレートです。

範囲フォーマット指定子

range-format-spec の構文は次のとおりです。

range-fill-and-align (任意) width (任意) n(任意) range-type (任意) range-underlying-spec (任意)

range-fill-and-align は、 range-fill-and-align の fill が {、}、または : 以外の文字である場合を除き、 fill-and-align と同じように解釈されます。

width は、 標準フォーマット幅指定子で説明されています。

n オプションを指定すると、範囲は開始と終了のブラケットなしでフォーマットされます。

assert(std::format("{}", views::iota(1, 5)) == "[1, 2, 3, 4]");
assert(std::format("{:n}", views::iota(1, 5)) == "1, 2, 3, 4");

range-underlying-spec (構文は : format-spec と同等) の format-spec は、範囲要素フォーマッタ std::formatter<T, CharT> によって解釈されます。

std::array ints{12, 10, 15, 14};
 
assert(std::format("{}", ints) == "[12, 10, 15, 14]");
assert(std::format("{::X}", ints) == "[C, A, F, E]");
assert(std::format("{:n:_^4}", ints) == "_12_, _10_, _15_, _14_");

range-type は、範囲のフォーマット方法を変更します。特定のオプションは、特定の引数型でのみ有効です。

利用可能な範囲プレゼンテーション型は次のとおりです。

• m: 開始ブラケットが "{"、終了ブラケットが "}"、区切り文字が ", " であることを示し、各範囲要素は tuple-format-spec の m が指定されたかのようにフォーマットされます。

• m が range-type として選択された場合、プログラムは、T が次のいずれかの特殊化である場合を除き、不正な形式となります。

• std::pair、または
• std::tuple であり、 std::tuple_size_v<T> == 2 が true である場合。

std::array char_pairs
{
    std::pair{'A', 5}, std::pair{'B', 10}, std::pair{'C', 12}
};
 
assert(std::format("{}", char_pairs) == "[('A', 5), ('B', 10), ('C', 12)]");
assert(std::format("{:m}", char_pairs) == "{'A': 5, 'B': 10, 'C': 12}");

• s: 範囲が文字列としてフォーマットされることを示します。
• ?s: 範囲が エスケープされた文字列としてフォーマットされることを示します。

• s または ?s が range-type として選択された場合、n オプションと range-underlying-spec の両方をフォーマット指定子に含めてはなりません。そして、
• T が CharT である場合を除き、プログラムは不正な形式となります。

std::array star{'S', 'T', 'A', 'R'};
 
assert(std::format("{}", star) == "['S', 'T', 'A', 'R']");
assert(std::format("{:s}", star) == "STAR");
assert(std::format("{:?s}", star) == "\"STAR\"");

データメンバー

メンバ名	定義
std::formatter<T, CharT> underlying_ (private)	要素の基になるフォーマッタ (説明用のメンバオブジェクト*)
std::basic_string_view<CharT> separator_ (private)	範囲フォーマット結果の区切り文字を表す文字列。デフォルトの区切り文字は ", " です。 (説明用のメンバオブジェクト*)
std::basic_string_view<CharT> opening-bracket_ (private)	範囲フォーマット結果の開始ブラケットを表す文字列。デフォルトの開始ブラケットは "[" です。 (説明用のメンバオブジェクト*)
std::basic_string_view<CharT> closing-bracket_ (private)	範囲フォーマット結果の終了ブラケットを表す文字列。デフォルトの終了ブラケットは "]" です。 (説明用のメンバオブジェクト*)

メンバー関数

set_separator	範囲フォーマット結果の指定された区切り文字を設定します。 (public member function)
set_brackets	範囲フォーマット結果の指定された開始と終了のブラケットを設定します。 (public member function)
underlying	基になるフォーマッタを返します。 (public member function)
parse	range-format-spec によって指定されたフォーマット指定子を解析します。 (public member function)
format	range-format-spec によって指定された範囲フォーマット出力を書き込みます。 (public member function)

std::range_formatter::set_separator

constexpr void set_separator( std::basic_string_view<CharT> sep ) noexcept;

sep を separator_ に代入します。

std::range_formatter::set_brackets

constexpr void set_brackets( std::basic_string_view<CharT> opening,                              std::basic_string_view<CharT> closing ) noexcept;

opening と closing をそれぞれ opening-bracket_ と closing-bracket_ に代入します。

std::range_formatter::underlying

constexpr std::formatter<T, CharT>& underlying();	(1)
constexpr const std::formatter<T, CharT>& underlying() const;	(2)

underlying_ (基になるフォーマッタ) を返します。

std::range_formatter::parse

template< class ParseContext > constexpr auto parse( ParseContext& ctx ) -> ParseContext::iterator;

range-format-spec としてフォーマット指定子を解析し、解析された指定子を現在のオブジェクトに格納します。

range-format-spec 内の format-spec を解析するために underlying_.parse(ctx) を呼び出すか、後者が存在しない場合は空の format-spec を呼び出します。

range-type または n オプションが存在する場合、 opening-bracket_、 closing-bracket_、および separator_ の値は必要に応じて変更されます。

次の場合に underlying_.set_debug_format() を呼び出します。

• range-type が s でも ?s でもない場合。
• underlying_.set_debug_format() が有効な式であり、
• range-underlying-spec が存在しない場合。

range-format-spec の終端の次のイテレータを返します。

std::range_formatter::format

template< ranges::input_range R, class FormatContext >   requires std::formattable<ranges::range_reference_t<R>, CharT> &&            std::same_as<std::remove_cvref_t<ranges::range_reference_t<R>>, T> auto format( R&& r, FormatContext& ctx ) const -> FormatContext::iterator;

range-type が s または ?s のいずれかであった場合、フォーマットされた std::basic_string<CharT>(std::from_range, r) を文字列またはエスケープされた文字列として、それぞれ ctx.out() に書き込みます。

それ以外の場合、 range-format-spec によって指定された順序で、次のものを ctx.out() に書き込みます。

• opening-bracket_,
• 範囲 r のフォーマット可能な各要素 e について

• underlying_ を介して e を書き出した結果、および
• separator_ (ただし、 e が r の最後の要素である場合を除く)、および

• closing-bracket_.

出力範囲の末尾以降のイテレータを返します。

不具合報告

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

DR	適用対象	公開された動作	正しい動作
LWG 3892	C++23	ネストされた範囲のフォーマットが正しくありませんでした。	修正済み

関連項目

formatter (C++20)

与えられた型のフォーマット規則を定義する (クラステンプレート)