Namespaces
Variants

wcsftime

From cppreference.net
定义于头文件 <wchar.h>
size_t wcsftime ( wchar_t * str, size_t count, const wchar_t * format, const struct tm * time ) ;
(自 C95 起)

将给定日历时间 time 中的日期和时间信息,按照 格式字符串 format 转换为以空字符结尾的宽字符字符串 str 。最多写入 count 个字节。

目录

参数

str - 指向输出目标 wchar_t 数组首元素的指针
count - 最大写入宽字符数
format - 指向以空字符结尾的宽字符串的指针,用于指定 转换格式

格式字符串

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

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

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

  • 包含1月4日
  • 包含该年的第一个星期四
tm_year tm_wday tm_yday
g
(C99)
输出 ISO 8601 基于周的年份 的最后两位数字,即包含指定周的年份(范围 [00,99] )。

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

  • 包含1月4日
  • 包含该年的第一个星期四
tm_year tm_wday tm_yday
月份
b 写入 月份缩写 名称,例如 Oct (取决于区域设置) tm_mon
Ob
(C23)
写入本地化替代表示中的 缩写月份名称 tm_mon
h
(C99)
b 的同义词 tm_mon
B 写入 完整月份 名称,例如 October (取决于区域设置) tm_mon
OB
(C23)
写入本地化替代表示法中对应的 完整月份 名称 tm_mon
m 月份 写作十进制数字(范围 [01,12] tm_mon
Om
(C99)
使用替代数字系统写入 月份 ,例如在 ja_JP 区域设置中显示为"十二"而非"12" tm_mon
周次
U 写入 年份中的周数 (以十进制数表示,周日为一周的第一天)(范围 [00,53] tm_year , tm_wday , tm_yday
OU
(C99)
写入 年份周数 ,如同 %U 的规则,但使用替代数字系统,例如在 ja_JP 区域设置中显示为"五十二"而非"52" tm_year , tm_wday , tm_yday
W 写入 年份中的周数 (以星期一作为每周的第一天)(范围 [00,53] tm_year , tm_wday , tm_yday
OW
(C99)
写入 年份中的周数 ,如同 %W 的规则,使用替代数字系统,例如在 ja_JP 区域设置中显示为"五十二"而非"52" tm_year , tm_wday , tm_yday
V
(C99)
写入 ISO 8601 周序号 (范围 [01,53] )。

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

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

单个字符前会添加空格。

tm_mday
e
(C99)
日期 以十进制数字形式写入(范围 [1,31] )。

单个数字前会添加空格。

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

单个字符前会添加空格。

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

返回值

成功时写入由 str 指向的宽字符数组的宽字符数量(不包含终止符 L ' \0 ' )。如果在完整字符串存储前达到 count 限制,则返回 0 且内容未定义。

示例

#include <locale.h>
#include <stdio.h>
#include <time.h>
#include <wchar.h>
int main(void)
{
    wchar_t buff[40];
    struct tm my_time =
    {
        .tm_year = 112, // = 年份 2012
        .tm_mon = 9,    // = 第10个月
        .tm_mday = 9,   // = 第9天
        .tm_hour = 8,   // = 8小时
        .tm_min = 10,   // = 10分钟
        .tm_sec = 20    // = 20秒
    };
    if (wcsftime(buff, sizeof buff, L"%A %c", &my_time))
        printf("%ls\n", buff);
    else
        puts("wcsftime failed");
    setlocale(LC_ALL, "ja_JP.utf8");
    if (wcsftime(buff, sizeof buff, L"%A %c", &my_time))
        printf("%ls\n", buff);
    else
        puts("wcsftime failed");
}

输出:

Sunday Sun Oct  9 08:10:20 2012
日曜日 2012年10月09日 08時10分20秒

参考文献

  • C23标准(ISO/IEC 9899:2024):
  • 7.29.5.1 wcsftime函数(页码:待定)
  • C17标准(ISO/IEC 9899:2018):
  • 7.29.5.1 wcsftime函数(页码:230-231)
  • C11标准(ISO/IEC 9899:2011):
  • 7.29.5.1 wcsftime函数(页码:439-440)
  • C99标准(ISO/IEC 9899:1999):
  • 7.24.5.1 wcsftime函数(页码:385-386)

另请参阅

tm 对象转换为自定义文本表示
(函数)
C++ documentation 关于 wcsftime