Namespaces
Variants

std::time_put<CharT,OutputIt>:: put, std::time_put<CharT,OutputIt>:: do_put

From cppreference.net
C++
Text processing library
Localization library
std::time_put
Member functions
time_put::put time_put::do_put
定义于头文件 <locale>
public :

iter_type put ( iter_type out, std:: ios_base & str,
char_type fill, const std:: tm * t,

const CharT * fmtbeg, const CharT * fmtend ) const ;
(1)
public :

iter_type put ( iter_type out, std:: ios_base & str,
char_type fill, const std:: tm * t,

char format, char modifier = 0 ) const ;
(2)
protected :

virtual iter_type do_put ( iter_type out, std:: ios_base & str,
char_type fill, const std:: tm * t,

char format, char modifier ) const ;
(3)

将指向 std::tm 对象中存储的日历日期和时间转换为字符串，转换依据为 格式字符串 [fmtbeg, fmtend) 。该格式字符串与 std:: strftime 所使用的格式相同，但每个格式说明符都通过单独调用 do_put() 进行处理，这一处理过程可通过扩展此facet进行自定义。

1) 遍历字符序列 [fmtbeg, fmtend) ，逐个检查字符。所有不属于格式序列的字符会立即写入输出迭代器 out 。为识别格式序列，本函数会通过 std:: ctype < char_type > ( str. getloc ( ) ) . narrow ( c, 0 ) 对 [fmtbeg, fmtend) 中的下一个字符 c 进行窄化处理。若该字符等于 '%' ，则将其后一个或两个字符与 std::strftime 识别的格式序列列表及该区域设置支持的实现定义格式进行比对。对于每个有效格式序列，将调用 do_put ( out, str, fill, t, format, modifier ) ，其中 format 为格式序列字符， modifier 为可选的格式序列修饰符（ 'E' 或 'O' ）。若修饰符不存在，则使用 ' \0 ' 值。
2) 调用最派生类的 do_put 成员函数。
3) 将存储在 std::tm 对象（由 t 指向）中的日历日期和时间转换为字符字符串，转换依据由 '%' 与 modifier 的值（若不为 ' \0 ' ）以及 format 的值拼接而成的格式转换序列。格式解析方式与函数 std::strftime 相同，但被描述为依赖于区域设置的格式由此区域设置定义，且可能支持额外的格式说明符（ fill 参数供这些实现定义的格式说明符使用）。生成的字符串被写入输出迭代器 out 。

目录

参数

out - 输出迭代器，转换结果将写入此处
str - 流对象，此函数在需要时通过它获取本地化facet，例如 std::ctype 用于字符窄化
t - 指向 std::tm 对象的指针，从中获取日期/时间值
fmtbeg - 指向 char_type 字符序列首字符的指针，该序列指定 转换格式
fmtend - 指向 char_type 字符序列末字符后一位置的指针，该序列指定 转换格式
fill - 填充字符（通常为空格）
format - 命名 转换说明符 的字符
modifier - 可选的修饰符，可能出现在 % 与 转换说明符 之间

格式字符串

格式字符串由零个或多个转换说明符和普通字符（除 % 外）组成。所有普通字符（包括终止空字符）都会不经修改地复制到输出字符串中。每个转换规范以 % 字符开头，可选地后跟 E 或 O 修饰符（若区域设置不支持则忽略），最后是决定说明符行为的字符。可用的格式说明符如下：

转换
说明符 		说明 使用字段
% 写入字面量 % 。完整转换规范必须为 %% 。
n
(C++11) 		写入换行符
t
(C++11) 		写入水平制表符
年份
Y 将 年份 写作十进制数字，例如 2017 tm_year
EY
(C++11) 		以替代表示法写入 年份 ，例如在 ja_JP 区域设置中输出平成23年（平成23年）而非 2011年（2011年） tm_year
y 将 year 的最后两位数字写作十进制数（范围 [00,99] ） tm_year
Oy
(C++11) 		使用替代数字系统写入 年份 的最后两位数字，例如在 ja_JP 区域设置中显示为"十一"而非 11 tm_year
Ey
(C++11) 		将 年份 写作基于本地化替代日历周期的偏移量 %EC (依赖于本地化设置) tm_year
C
(C++11) 		将 年份 的前两位数字写作十进制数（范围 [00,99] ） tm_year
EC
(C++11) 		写入 基准年（周期） 在本地化环境中的替代表示名称，例如 ja_JP 中的平成（平成时代） tm_year
G
(C++11) 		写入 ISO 8601 基于周的年份 ，即包含指定周的年份。

在 ISO 8601 标准中，周从周一开始，且年份的第一周必须满足以下要求：

  • 包含1月4日
  • 包含该年的第一个星期四
tm_year 、 tm_wday 、 tm_yday
g
(C++11) 		写入 ISO 8601 基于周的年份 的最后两位数字，即包含指定周的年份（范围 [00,99] ）。

在 ISO 8601 标准中，周从周一开始，且一年的第一周必须满足以下要求：

  • 包含 1 月 4 日
  • 包含该年的第一个星期四
tm_year 、 tm_wday 、 tm_yday
月份
b 写入 缩写月份名称 ，例如 Oct （取决于区域设置） tm_mon
h
(C++11) 		b 的同义词 tm_mon
B 写入 完整月份 名称，例如 October （取决于区域设置） tm_mon
m 将 月份 写作十进制数字（范围 [01,12] ） tm_mon
Om
(C++11) 		使用替代数字系统写入 月份 ，例如在 ja_JP 区域设置中显示“十二”而非“12” tm_mon
周次
U 写入 一年中的周数 作为十进制数（周日为一周的第一天）（范围 [00,53] ） tm_year , tm_wday , tm_yday
OU
(C++11) 		写入 年份的周数 ，如同 %U 的规则，但使用替代数字系统，例如在 ja_JP 区域设置中显示为"五十二"而非"52" tm_year , tm_wday , tm_yday
W 写入 年份中的周数 （以星期一作为每周的第一天）（范围 [00,53] ） tm_year , tm_wday , tm_yday
OW
(C++11) 		写入 年份中的周数 ，如同使用 %W 格式符，但采用替代数字系统，例如在 ja_JP 区域设置中会显示为"五十二"而非"52" tm_year , tm_wday , tm_yday
V
(C++11) 		写入 ISO 8601 周数 （范围 [01,53] ）。

根据 ISO 8601 标准，每周从周一开始，且年份的第一周必须满足以下要求：

  • 包含1月4日
  • 包含该年的第一个星期四
tm_year 、 tm_wday 、 tm_yday
OV
(C++11) 		写入 年份中的周数 ，如同 %V 所做，但使用替代数字系统，例如在 ja_JP 区域设置中显示为"五十二"而非"52" tm_year ， tm_wday ， tm_yday
年/月中的日期
j 写入 一年中的第几天 （范围 [001,366] ） tm_yday
d 将 月份中的日期 写作十进制数字（范围 [01,31] ） tm_mday
Od
(C++11) 		使用替代数字系统写入从零开始的 月份中的日期 ，例如在 ja_JP 区域设置中显示为 二十七 而非 27

单个字符前会添加空格。

tm_mday
e
(C++11) 		将 月份中的日期 以十进制数字形式写入（范围 [1,31] ）。

单数字前会添加一个空格。

tm_mday
Oe
(C++11) 		使用替代数字系统写入基于1的 月份日期 ，例如在ja_JP区域设置中显示为"二十七"而非"27"

单个字符前会添加空格。

tm_mday
星期几
a 写入 缩写星期名 ，例如 Fri （取决于区域设置） tm_wday
A 输出 完整星期名称 ，例如 Friday （取决于区域设置） tm_wday
w 将 weekday 写作十进制数字，其中周日为 0 （范围 [0-6] ） tm_wday
Ow
(C++11) 		写入使用替代数字系统的 星期几 ，其中周日为 0 ，例如在 ja_JP 区域设置中显示为"二"而非 2 tm_wday
u
(C++11) 		将 weekday 以十进制数字形式输出，其中周一为 1 （ISO 8601格式）（范围 [1-7] ） tm_wday
Ou
(C++11) 		写入使用替代数字系统的 工作日 ，其中周一为 1 ，例如在 ja_JP 区域设置中显示为"二"而非"2" tm_wday
时、分、秒
H 将 小时 写作十进制数字，24小时制（范围 [00-23] ） tm_hour
OH
(C++11) 		使用替代数字系统写入 小时 （基于24小时制），例如在 ja_JP 区域设置中输出"十八"而非"18" tm_hour
I 将 hour 写作十进制数字，12小时制（范围 [01,12] ） tm_hour
OI
(C++11) 		使用替代数字系统写入 12小时制的小时 ，例如在 ja_JP 区域设置中显示为"六"而非"06" tm_hour
M 将 分钟 写作十进制数字（范围 [00,59] ） tm_min
OM
(C++11) 		使用替代数字系统写入 分钟 ，例如在 ja_JP 区域设置中写作"二十五"而非 25 tm_min
S 写入 秒 为十进制数字（范围 [00,60] ） tm_sec
OS
(C++11) 		使用替代数字系统写入 秒 ，例如在 ja_JP 区域设置中显示为"二十四"而非数字 24 tm_sec
其他
c 写入 标准日期时间字符串 ，例如 Sun Oct 17 04:41:13 2010 （取决于区域设置） 全部
Ec
(C++11) 		写入 替代日期和时间字符串 ，例如在 ja_JP 区域设置中使用 平成23年 替代 2011年 全部
x 写入本地化的 日期表示 （依赖于区域设置） 全部
Ex
(C++11) 		写入 替代日期表示形式 ，例如在 ja_JP 区域设置中使用 平成23年 替代 2011年 全部
X 写入本地化的 时间表示 ，例如 18:40:20 或 6:40:20 PM（取决于区域设置） 全部
EX
(C++11) 		写入 替代时间表示 （依赖于区域设置） 全部
D
(C++11) 		等同于 "%m/%d/%y" tm_mon , tm_mday , tm_year
F
(C++11) 		等同于 "%Y-%m-%d" （ISO 8601 日期格式） tm_mon 、 tm_mday 、 tm_year
r
(C++11) 		写入本地化的 12小时制 时间（取决于区域设置） tm_hour , tm_min , tm_sec
R
(C++11) 		等同于 "%H:%M" tm_hour , tm_min
T
(C++11) 		等同于 "%H:%M:%S" （ISO 8601 时间格式） tm_hour , tm_min , tm_sec
p 输出本地化的 上午或下午 （取决于区域设置） tm_hour
z
(C++11) 		以ISO 8601格式写入 UTC偏移量 （例如 -0430 ），若时区信息不可用则不输出任何字符 tm_isdst
Z 写入与区域设置相关的 时区名称或缩写 ，若时区信息不可用则不输出任何字符 tm_isdst

返回值

指向已生成最后一个字符之后位置的迭代器。

注释

未提供错误处理。

填充字符是为那些实现定义的格式说明符以及使用填充和填充逻辑的用户自定义 do_put() 重载提供的。这类实现通常利用来自 str 的格式化标志。

示例

运行此代码 
#include <iostream>
#include <sstream>
#include <iomanip>
#include <ctime>
void try_time_put(const std::tm* t, const std::string& fmt)
{
    std::cout.imbue(std::locale());
    std::cout << "In the locale '" << std::cout.getloc().name() << "' : '";
    std::use_facet<std::time_put<char>>(std::cout.getloc()).put(
        {std::cout}, std::cout, ' ', t, &fmt[0], &fmt[0] + fmt.size());
    std::cout << "'\n";
}
int main()
{
    std::time_t t = std::time(NULL);
    std::tm tm = *std::localtime(&t);
    std::string fmt = "%c";
    std::cout << "Using the format string '" << fmt
              << "' to format the time: " << std::ctime(&t) << '\n';
    std::locale::global(std::locale("de_DE.utf8"));
    try_time_put(&tm, fmt);
    std::locale::global(std::locale("el_GR.utf8"));
    try_time_put(&tm, fmt);
    std::locale::global(std::locale("ja_JP.utf8"));
    try_time_put(&tm, fmt);
}

可能的输出： 

Using the format string '%c' to format the time: Mon Feb 11 22:58:50 2013
In the locale 'de_DE.utf8' : 'Mo 11 Feb 2013 23:02:38 EST'
In the locale 'el_GR.utf8' : 'Δευ 11 Φεβ 2013 11:02:38 μμ EST'
In the locale 'ja_JP.utf8' : '2013年02月11日 23時02分38秒'

缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的C++标准。

DR 适用版本 发布行为 正确行为
LWG 164 C++98 参数 fill 的用途不明确 已明确说明

另请参阅

(C++11)
根据指定格式格式化并输出日期/时间值
(函数模板)
[virtual] (C++11)
根据指定格式从输入流提取日期/时间组件
( std::time_get<CharT,InputIt> 的虚保护成员函数)