Namespaces
Variants

std:: range_formatter

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
Format strings
(C++20) (C++20) (C++20)
(C++26)
Formatting concepts
(C++23)
Formatter
(C++20)
(C++23)
(C++23)
range_formatter
(C++23)
(C++23)
(C++20) (C++20) (C++20)
(C++20) (C++20) (C++20)
(C++23)
(C++23)
Formatting arguments
(C++20)
(C++20)
(C++20) (C++20) (C++20)
(C++20) (deprecated in C++26)
(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 は、 fill-and-align と同様に解釈されますが、 range-fill-and-align における fill は、 { 、 } 、または : 以外の任意の文字です。

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 : 開き括弧が "{" 、閉じ括弧が "}" 、区切り文字が ", " であることを示し、各範囲要素は m がその tuple-type に対して指定されたかのようにフォーマットされる（ tuple-format-spec 内）。
  • m が range-type として選択された場合、 T が以下のいずれかの特殊化でない限り、プログラムは不適格です： 
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_ （非公開） 要素の基盤となるフォーマッタ
( 説明専用メンバーオブジェクト* )
std:: basic_string_view < CharT > separator_ （非公開） 範囲フォーマット結果の区切り文字を表す文字列。デフォルトの区切り文字は ", " です。
( 説明専用メンバーオブジェクト* )
std:: basic_string_view < CharT > opening-bracket_ （非公開） 範囲フォーマット結果の開始括弧を表す文字列。デフォルトの開始括弧は "[" です。
( 説明専用メンバーオブジェクト* )
std:: basic_string_view < CharT > closing-bracket_ （非公開） 範囲フォーマット結果の終了括弧を表す文字列。デフォルトの終了括弧は "]" です。
( 説明専用メンバーオブジェクト* )

メンバー関数

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 として解析し、解析された指定子を現在のオブジェクトに格納します。

underlying_ . parse ( ctx ) を呼び出して、 range-format-spec 内の format-spec 、または後者が存在しない場合は空の 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 を書き込んだ結果、および
  • e が r の最後の要素でない限り separator_ 、
  • closing-bracket_ .

出力範囲の終端を過ぎたイテレータを返します。

不具合報告

以下の動作変更の欠陥報告書は、以前に公開されたC++規格に対して遡及的に適用されました。

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

関連項目

(C++20)
指定された型のフォーマット規則を定義する
(クラステンプレート)