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 的语法为：

范围填充与对齐  （可选） 宽度  （可选） n （可选） 范围类型  （可选） 范围底层规范  （可选）

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 指定了 m （在 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}");
（注：根据要求，所有HTML标签、属性及 标签内的C++代码均保持原样未翻译，仅对注释性说明文字进行了简体中文翻译。实际代码段中无需要翻译的自然语言文本，故输出内容与输入完全一致）
  • s : 表示该范围应格式化为字符串。
  • ?s : 表示该范围应格式化为 转义字符串 。
  • 若选择 s 或 ?s 作为 范围类型 ，则格式说明符中不得包含 n 选项和 范围底层说明 ，且
  • 除非 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
为范围格式化结果设置指定的分隔符
(公开成员函数)
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 嵌套范围的格式化不正确 已修正

参见

(C++20)
为给定类型定义格式化规则
(类模板)