From 2513346aaefb6f93d4740367084d9f30d30a05aa Mon Sep 17 00:00:00 2001 From: Akira Takahashi Date: Fri, 27 Jan 2023 16:28:04 +0900 Subject: [PATCH] =?UTF-8?q?=20:=20range-default-formatter=E3=82=92?= =?UTF-8?q?=E8=BF=BD=E5=8A=A0=20#1085?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- reference/format.md | 2 +- reference/format/formatter.md | 4 +- reference/format/range-default-formatter.md | 97 +++++++++++++++++++++ reference/format/range_formatter.md | 4 +- 4 files changed, 103 insertions(+), 4 deletions(-) create mode 100644 reference/format/range-default-formatter.md diff --git a/reference/format.md b/reference/format.md index 0fb6081f58..458e42a680 100644 --- a/reference/format.md +++ b/reference/format.md @@ -37,7 +37,7 @@ | [`const-formattable-range`](format/const-formattable-range.md) | `const Range`の要素型が文字列フォーマット可能 (concept) | C++23 | | [`fmt-maybe-const`](format/fmt-maybe-const.md) | `formatter::format()`関数のパラメータ型として使用するための(const) Range型を取得 (type-alias) | C++23 | | [`range_formatter`](format/range_formatter.md) | Rangeに対する書式文字列の解析、値のフォーマットを行う (class template) | C++23 | -| [`range-default-formatter`](format/range-default-formatter.md.nolink) | Rangeに対する共通の書式文字列の解析、値のフォーマットを行う説明専用クラス (class template) | C++23 | +| [`range-default-formatter`](format/range-default-formatter.md) | Rangeに対する共通の書式文字列の解析、値のフォーマットを行う説明専用クラス (class template) | C++23 | ## 引数 diff --git a/reference/format/formatter.md b/reference/format/formatter.md index 053e1069f0..0106bb135e 100644 --- a/reference/format/formatter.md +++ b/reference/format/formatter.md @@ -31,13 +31,13 @@ namespace std { * range_format[link range_format.md] * formattable[link formattable.md] * ranges::range_reference_t[link /reference/ranges/range_reference_t.md] -* range-default-formatter[link range-default-formatter.md.nolink] +* range-default-formatter[link range-default-formatter.md] ## 概要 フォーマット引数の個々の型に対応する書式文字列の解析と値のフォーマットを担うクラス。 - (1) : デフォルトのフォーマット -- (2) : Range用のフォーマット。実装は[`range-default-formatter`](range-default-formatter.md.nolink)クラスが行う +- (2) : Range用のフォーマット。実装は[`range-default-formatter`](range-default-formatter.md)クラスが行う - (3) : [`std::pair`](/reference/utility/pair.md)と[`std::tuple`](/reference/tuple/tuple.md)に対する特殊化 - (4) : コンテナアダプタである[`std::queue`](/reference/queue/queue.md)、[`std::priority_queue`](/reference/queue/priority_queue.md)、[`std::stack`](/reference/stack/stack.md)に対する特殊化 diff --git a/reference/format/range-default-formatter.md b/reference/format/range-default-formatter.md new file mode 100644 index 0000000000..3d5c97b1e5 --- /dev/null +++ b/reference/format/range-default-formatter.md @@ -0,0 +1,97 @@ +# range-default-formatter +* format[meta header] +* class template[meta id-type] +* std[meta namespace] +* cpp23[meta cpp] + +```cpp +namespace std { + template + struct range-default-formatter; // (1) C++23 + + template + struct range-default-formatter< + range_format::sequence, R, charT>; // (2) C++23 + + template + struct range-default-formatter< + range_format::map, R, charT>; // (3) C++23 + + template + struct range-default-formatter< + range_format::set, R, charT>; // (4) C++23 + + template + requires (K == range_format::string || K == range_format::debug_string) + struct range-default-formatter< + K, R, charT>; // (5) C++23 +} +``` +* range_format[link range_format.md] +* ranges::input_range[link /reference/ranges/input_range.md] + +## 概要 +`range-default-formatter`は、Range・コンテナに対するデフォルトの書式解析と書式文字列化を行う説明専用クラスである。 + +このクラスは、[`formatter`](formatter.md)クラスのRange・コンテナに対する特殊化実装として標準ライブラリの内部で使用される。 + +このクラスの内部実装として[`range_formatter`](range_formatter.md)が使用される。 + + +- (1) : プライマリテンプレート。宣言のみ +- (2) : Range・シーケンスコンテナに対する特殊化。デバッグ出力の有効化と、`[a, b, c]`形式の出力を行う +- (3) : [`std::map`](/reference/map/map.md)や[`std::flat_map`](/reference/flat_map/flat_map.md.nolink)などの連想コンテナに対する特殊化。デバッグ出力の有効化と、`{1: a, 2: b}`形式での出力を行う +- (4) : [`std::set`](/reference/set/set.md)や[`std::flat_set`](/reference/flat_set/flat_set.md.nolink)などの集合コンテナに対する特殊化。デバッグ出力の有効化と、`{a, b, c}`形式の出力を行う +- (5) : 文字列形式の出力を行うRangeに対する特殊化。Rangeを文字列として出力し、[`range_format::debug_string`](range_format.md)指定であればデバッグ文字列として出力する + + +## 備考 +- (5) : この特殊化は規格上、標準ライブラリ内では使用されないが ([`formatter`](formatter.md)`<`[`string`](/reference/string/basic_string.md)`, charT>`がすでにある)、以下のような用途が考えられる + - ユーザー定義の文字列クラスを定義する場合に、[`format_kind`](format_kind.md)で値として[`range_format::string`](range_format.md)もしくは[`range_format::debug_string`](range_format.md)をもつよう特殊化するか ([`formatter`](formatter.md)`<`[`string`](/reference/string/basic_string.md)`, charT>`をラップする方がかんたんではある) + - [`std::vector`](/reference/vector/vector.md)のような文字を要素とするシーケンスコンテナで、文字列形式で出力する書式オプション ([`s`や`?s`](format.md#range-format-options)) を指定した際に`range-default-formatter`の内部で使用される + + +## メンバ関数 + +| メンバ関数 | 説明 | 対応バージョン | +|------------|------|----------------| +| `parse` | 書式の解析を行う | C++23 | +| `format` | 書式化を行う | C++23 | + + +### sequenceに対する特殊化 + +| メンバ関数 | 説明 | 対応バージョン | +|------------|------|----------------| +| `constexpr void set_separator(basic_string_view sep);` | 要素の区切り文字を設定する | C++23 | +| `constexpr void set_brackets(basic_string_view opening, basic_string_view closing);` | 全体の囲み文字を設定する | C++23 | + + +### mapに対する特殊化 + +| メンバ関数 | 説明 | 対応バージョン | +|------------|------|----------------| +| `constexpr range-default-formatter();` | 全体の囲み文字を`{}`、要素の囲み文字を空、要素同士の区切り文字を`": "`に設定する | C++23 | + +### setに対する特殊化 + +| メンバ関数 | 説明 | 対応バージョン | +|------------|------|----------------| +| `constexpr range-default-formatter();` | 全体の囲み文字を`{}`に設定する | C++23 | + + +## バージョン +### 言語 +- C++23 + +### 処理系 +- [Clang](/implementation.md#clang): ?? +- [GCC](/implementation.md#gcc): ?? +- [ICC](/implementation.md#icc): ?? +- [Visual C++](/implementation.md#visual_cpp): ?? + + +## 参照 +- [P2286R8 Formatting Ranges](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2286r8.html) +- [P2585R1 Improve default container formatting](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2585r1.html) + - C++23から、Range・コンテナ、`pair`、`tuple`のフォーマット出力、および文字・文字列のデバッグ指定 (`"?"`) が追加された diff --git a/reference/format/range_formatter.md b/reference/format/range_formatter.md index c2d5c38f5e..71ff8a66f8 100644 --- a/reference/format/range_formatter.md +++ b/reference/format/range_formatter.md @@ -16,6 +16,8 @@ namespace std { ## 概要 `range_formatter`は、Range・コンテナに対する[`formatter`](formatter.md)クラスの特殊化を実装するためのユーティリティクラスである。 +このクラスは、説明専用クラス[`range-default-formatter`](range-default-formatter.md)の内部実装として使用される。 + ユーザー定義のコンテナ・RangeをRange書式に対応する場合は、以下のようにする： - オリジナル書式を定義しないのであれば、このクラスではなく、[`format_kind`](format_kind.md)を特殊化する @@ -148,7 +150,7 @@ aa:bb:cc:dd:ee:ff - [Visual C++](/implementation.md#visual_cpp): ?? ## 関連項目 -- [`range-default-formatter`](range-default-formatter.md.nolink) +- [`range-default-formatter`](range-default-formatter.md) - [`formatter`](formatter.md)