std::range_formatter

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

文字處理庫

本地化庫

正則表示式庫 (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

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 的解釋方式與 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: 表示開括號應為 "{"，閉括號應為 "}"，分隔符應為 ", "，並且每個範圍元素應格式化，如同為其 tuple-type（在 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\"");

資料成員

成員名稱 (Member name)	定義
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	為範圍格式化結果設定指定的分隔符 (公開成員函式)
set_brackets	為範圍格式化結果設定指定的開括號和閉括號 (公開成員函式)
underlying	返回底層格式化器 (公開成員函式)
parse	按 range-format-spec 指定解析格式說明符 (公開成員函式)
format	按 range-format-spec 指定寫入範圍格式化輸出 (公開成員函式)

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 的結果，以及
• separator_，除非 e 是 r 的最後一個元素，以及

• closing-bracket_.

返回一個迭代器，指向輸出範圍的末尾之後。

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 3892	C++23	巢狀範圍的格式化不正確	已更正

另請參閱

formatter (C++20)

定義給定型別的格式化規則 (類模板)