命名空间
变体
操作

std::formatter<std::chrono::zoned_time>, std::chrono::local_time_format

来自 cppreference.cn
< cpp‎ | chrono‎ | zoned time
 
C++
 
日期和时间库
时间点
(C++11)
(C++20)  
(C++20)
时长
(C++11)
时钟
(C++11)
(C++11)
(C++20)
(C++20)
(C++20)
(C++11)
(C++20)
(C++20)
(C++20)
日间时间
(C++20)(C++20)
(C++20)(C++20)
(C++20)
日历
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)  
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)(C++20)
chrono I/O
(C++20)

 
std::chrono::zoned_time
 
定义于头文件 <chrono>
template< class Duration, class TimeZonePtr, class CharT >

struct formatter<std::chrono::zoned_time<Duration, TimeZonePtr>, CharT>
    : std::formatter</*local-time-format-t*/
                         <std::common_type_t<Duration,

                                             std::chrono::seconds>>, CharT>
 (1) (C++20 起)
template< class Duration >

/*local-time-format-t*/<Duration>
    local_time_format( const std::chrono::local_time<Duration>& tp,
                       const std::string* abbrev = nullptr,

                       const std::chrono::seconds* offset_sec = nullptr );
 (2) (C++20 起)
帮助模板
template< class Duration >

struct /*local-time-format-t*/
{
    std::chrono::local_time<Duration> /*time*/;
    const std::string* /*abbrev*/;
    const std::chrono::seconds* /*offset_sec*/;

};
 (3) (C++20 起)
(仅作说明*)
template< class Duration, class CharT >
struct formatter</*local-time-format-t*/<Duration>, CharT>;
 (4) (C++20 起)
1) std::formatter 的特化，它定义了 std::chrono::zoned_time 的格式化规则。
  • parse 成员继承自基类。
  • 设 tp 为格式化参数，ctx 为格式化上下文，format 成员的行为等同于

using common_duration_type = std::common_type_t<Duration, std::chrono::seconds>;
using formatter_type = std::formatter<local-time-format-t <common_duration_type>;

std::chrono::sys_info info = tp.get_info();
return formatter_type::format({tp.get_local_time(), &info.abbrev, &info.offset_sec}), ctx);

2) 创建一个可以格式化为 std::chrono::zoned_time 的对象。
返回 {time, abbrev, offset_sec}。
3) 一个仅用于说明的类型，包含格式化 std::chrono::zoned_time 所需的所有信息。
  • abbrev 包含时区缩写。
  • offset_sec 包含与 UTC 的偏移量。
  • time 包含所有其他所需信息。
4) std::formatter 的特化，它定义了 std::chrono::zoned_time 的底层格式化规则。
设 f 为格式化参数，该特化具有以下额外的格式化规则：
  • 如果省略 chrono-spec，结果等同于使用 %F %T %Z 作为 chrono-spec。
  • 如果使用 %Z，当 f.abbrev 不是空指针值时，它会被替换为 *f.abbrev；否则抛出 std::format_error 类型的异常。
  • 如果使用 %z 或 %z 的修改变体，当 f.offset_sec 不是空指针值时，它会被替换为 *f.offset_sec；否则抛出 std::format_error 类型的异常。

std::formatter 特化通常不直接访问，而是通过格式化函数使用。

目录

[编辑] 格式说明

格式规范的形式为

fill-and-align (可选) width (可选) precision (可选) L(可选) chrono-spec (可选)

fill-and-align、width 和 precision 的含义与标准格式说明中相同。precision 仅对表示类型 Rep 为浮点类型的 std::chrono::duration 类型有效，否则抛出 std::format_error。

用于格式化的区域设置确定如下：

  • 如果格式规范中不存在 L，则使用默认的 "C" 区域设置，
  • 否则，如果传递给格式化函数，则使用 std::locale 所表示的区域设置，
  • 否则（存在 L 但没有将 std::locale 传递给格式化函数），则使用全局区域设置。

如果（普通或宽）字符串字面量编码是 Unicode 编码形式且区域设置在实现定义的区域设置集合中，则每个依赖于区域设置的替换都将执行，如同替换字符序列被转换为字面量编码。

chrono-spec 由一个或多个转换说明符和普通字符（除了 {、} 和 %）组成。chrono-spec 必须以转换说明符开头。所有普通字符都会不经修改地写入输出。每个未经修改的转换说明符以 % 字符开头，后跟一个决定说明符行为的字符。一些转换说明符具有修改形式，其中在 % 字符后插入 E 或 O 修饰符字符。每个转换说明符都会被输出中的适当字符替换，如下所述。

除非另有说明，如果 chrono-spec 为空，则 chrono 对象将按照将其流式传输到类型为 std::basic_ostringstream<CharT> 的对象 os 的方式进行格式化，并使用格式化区域设置（std::locale::classic()、传入的 std::locale 对象和 std::locale::global() 之一）填充，并将 os.str() 复制到输出缓冲区，并根据格式说明符进行额外的填充和调整。

以下格式说明符可用：

转换
说明符		 解释
%% 写入字面量 % 字符。
%n 写入换行符。
%t 写入水平制表符。
年
%C
%EC 		使用向下取整除法写入年份除以 100 的结果。如果结果是一个十进制数字，则在其前面加上 0。

修改后的命令 %EC 写入区域设置的世纪的替代表示。

%y
%Oy
%Ey 		写入年份的最后两位十进制数字。如果结果是一位数字，则在其前面加上 0。

修改后的命令 %Oy 写入区域设置的替代表示。

修改后的命令 %Ey 写入区域设置的从 %EC 偏移量（仅年份）的替代表示。

%Y
%EY 		将年份作为十进制数字写入。如果结果小于四位数字，则在其前面用 0 填充到四位数字。

修改后的命令 %EY 写入区域设置的替代完整年份表示。

月
%b
%h 		写入区域设置的缩写月份名称。
%B 写入区域设置的完整月份名称。
%m
%Om 		将月份作为十进制数字写入（一月为 01）。如果结果是一个数字，则在其前面加上 0。

修改后的命令 %Om 写入区域设置的替代表示。

日
%d
%Od 		将月份中的日期作为十进制数字写入。如果结果是一个十进制数字，则在其前面加上 0。

修改后的命令 %Od 写入区域设置的替代表示。

%e
%Oe 		将月份中的日期作为十进制数字写入。如果结果是一个十进制数字，则在其前面加上一个空格。

修改后的命令 %Oe 写入区域设置的替代表示。

星期几
%a 写入区域设置的缩写工作日名称。
%A 写入区域设置的完整工作日名称。
%u
%Ou 		将 ISO 工作日作为十进制数字写入 (1-7)，其中星期一为 1。

修改后的命令 %Ou 写入区域设置的替代表示。

%w
%Ow 		将工作日作为十进制数字写入 (0-6)，其中星期日为 0。

修改后的命令 %Ow 写入区域设置的替代表示。

ISO 8601 基于周的年份

在ISO 8601中，周以星期一开始，一年的第一周必须满足以下要求

  • 包含1月4日
  • 包含一年中的第一个星期四
%g 写入 ISO 8601 基于周的年份的最后两位十进制数字。如果结果是一位数字，则在其前面加上 0。
%G 将 ISO 8601 基于周的年份作为十进制数字写入。如果结果小于四位数字，则在其前面用 0 填充到四位数字。
%V
%OV 		将 ISO 8601 年份的周数作为十进制数字写入。如果结果是一个数字，则在其前面加上 0。

修改后的命令 %OV 写入区域设置的替代表示。

年份中的周/天
%j 将年份中的日期作为十进制数字写入（1 月 1 日为 001）。如果结果小于三位数字，则在其前面用 0 填充到三位数字。
%U
%OU 		将年份的周数作为十进制数字写入。年份的第一个星期日是第 01 周的第一天。在此之前的同年日期属于第 00 周。如果结果是一个数字，则在其前面加上 0。

修改后的命令 %OU 写入区域设置的替代表示。

%W
%OW 		将年份的周数作为十进制数字写入。年份的第一个星期一是第 01 周的第一天。在此之前的同年日期属于第 00 周。如果结果是一个数字，则在其前面加上 0。

修改后的命令 %OW 写入区域设置的替代表示。

日期
%D 等效于"%m/%d/%y"。
%F 等同于 "%Y-%m-%d"。
%x
%Ex 		写入区域设置的日期表示。

修改后的命令 %Ex 生成区域设置的替代日期表示。

日间时间
%H
%OH 		将小时（24 小时制）作为十进制数字写入。如果结果是一个数字，则在其前面加上 0。

修改后的命令 %OH 写入区域设置的替代表示。

%I
%OI 		将小时（12 小时制）作为十进制数字写入。如果结果是一个数字，则在其前面加上 0。

修改后的命令 %OI 写入区域设置的替代表示。

%M
%OM 		将分钟作为十进制数字写入。如果结果是一个数字，则在其前面加上 0。

修改后的命令 %OM 写入区域设置的替代表示。

%S
%OS 		将秒作为十进制数字写入。如果秒数小于 10，则结果前面加上 0。

如果输入的精度不能用秒精确表示，则格式为固定格式的十进制浮点数，其精度与输入精度匹配（如果转换为浮点十进制秒不能在 18 位小数内完成，则为微秒精度）。小数点字符根据区域设置进行本地化。

修改后的命令 %OS 写入区域设置的替代表示。

%p 写入区域设置中与 12 小时制相关联的 AM/PM 表示。
%R 等效于"%H:%M"。
%T 等效于"%H:%M:%S"。
%r 写入区域设置的 12 小时制时间。
%X
%EX 		写入区域设置的时间表示。

修改后的命令 %EX 写入区域设置的替代时间表示。


时区
%z
%Ez
%Oz 		以 ISO 8601 格式写入与 UTC 的偏移量。例如 -0430 表示比 UTC 晚 4 小时 30 分钟。如果偏移量为零，则使用 +0000。

修改后的命令 %Ez 和 %Oz 在小时和分钟之间插入 :（例如，-04:30）。

%Z 写入时区缩写。
杂项
%c
%Ec 		写入区域设置的日期和时间表示。

修改后的命令 %Ec 写入区域设置的替代日期和时间表示。

以下说明符可识别，但会抛出 std::format_error

转换
说明符		 解释
持续时间计数
%Q 写入持续时间的滴答计数，即通过 count() 获得的值。
%q 写入持续时间的单位后缀，如 operator<<() 中指定。

[编辑] 示例

本节不完整
原因：无示例

[编辑] 缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告 应用于 发布时的行为 正确的行为
LWG 4124 C++20 1. chrono-spec 无法省略
2. zoned_time 无法格式化
    精度低于秒		 1. 可以省略
2. 可以格式化为
    这些精度
P2372R3 C++20 formatter 使用全局区域设置或传入的区域设置 当 L 不存在时，使用默认的 "C" 区域设置

[编辑] 参见

(C++20)
 将参数的格式化表示存储在新字符串中
(函数模板) [编辑]
取自 "https://cppreference.cn/mwiki/index.php?title=cpp/chrono/zoned_time/formatter&oldid=181014"