Namespaces
Variants

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

From cppreference.net
C++
Date and time library
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 或其修饰变体，当 f. offset_sec 非空指针值时，将替换为 * f. offset_sec ；否则抛出 std::format_error 类型异常。

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

目录

格式说明

格式说明具有以下形式

填充与对齐  (可选) 宽度  (可选) 精度  (可选) L (可选) 时间规范  (可选)

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

用于格式化的区域设置按以下方式确定：

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

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

chrono-spec 由一个或多个转换说明符和普通字符（除 { 、 } 和 % 外）组成。 chrono-spec 必须以转换说明符开头。所有普通字符均不经修改直接写入输出。每个未修改的转换说明符以 % 字符开头，后接一个决定说明符行为的字符。部分转换说明符具有修改形式，即在 % 字符后插入 E 或 O 修饰符字符。如下所述，每个转换说明符将被输出中的相应字符替换。

除非另有说明，若 chrono-spec 为空，则时间对象的格式化方式等同于将其 流式输出 到类型为 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 		以十进制数字形式写入月份（1月为 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)
将参数的格式化表示存储于新字符串中
(函数模板)