格式化时间字符串。

语法

size_t strftime(
   char *strDest,
   size_t maxsize,
   const char *format,
   const struct tm *timeptr
);
size_t _strftime_l(
   char *strDest,
   size_t maxsize,
   const char *format,
   const struct tm *timeptr,
   _locale_t locale
);
size_t wcsftime(
   wchar_t *strDest,
   size_t maxsize,
   const wchar_t *format,
   const struct tm *timeptr
);
size_t _wcsftime_l(
   wchar_t *strDest,
   size_t maxsize,
   const wchar_t *format,
   const struct tm *timeptr,
   _locale_t locale
);

参数

strDest
输出字符串。

maxsize
strDest 缓冲区的大小,以字符(charwchar_t)为单位。

format
窗体控件字符串。

timeptr
tm 数据结构。

locale
要使用的区域设置。

返回值

strftime 返回置于 strDest 中的字符数,wcsftime 返回相应的宽字符数。

如果包括以 null 终止的字符在内的字符总数大于 maxsize,则 strftimewcsftime 都将返回 0,并且 strDest 的内容是不确定的。

strDest 中的字符数等于 format 中的文本字符外加可通过格式化代码添加到 format 的任何字符的数量。 返回值中一般不计算以 null 终止的字符串。

备注

strftimewcsftime 函数根据提供的 format 参数格式化 timeptr 中的 tm 时间值,并将结果存储在 strDest 缓冲区中。 该字符串最多可放置 maxsize 个字符。 有关 timeptr 结构中字段的说明,请参阅 asctimewcsftime 是等同于 strftime 的宽字符;它的字符串指针参数指向宽字符字符串。 否则这些函数具有相同行为。

此函数验证其参数。 如果 strDestformattimeptr 是空指针,或者如果由 timeptr 寻址的 tm 数据结构无效(例如,如果它包含超出时间或日期的范围值),或者如果 format 字符串包含无效的格式化代码,则调用无效的参数处理程序,如参数验证中所述。 如果允许执行继续,则该函数将返回 0 并将 errno 设置为 EINVAL

默认情况下,此函数的全局状态范围限定为应用程序。 若要更改此行为,请参阅 CRT 中的全局状态

一般文本例程映射

TCHAR.H 例程 _UNICODE_MBCS 未定义 _MBCS 已定义 _UNICODE 已定义
_tcsftime strftime strftime wcsftime

format 参数由一个或多个代码组成;比如在 printf 中,格式化代码前面带有百分号 (%)。 不以 % 开头的字符原样复制到 strDest。 当前区域设置的 LC_TIME 分类会影响 strftime 的输出格式。 (有关 LC_TIME 的详细信息,请参阅 setlocale。)strftimewcsftime 函数使用当前设置的区域设置。 这些函数的 _strftime_l_wcsftime_l 版本相同,只不过它们将区域设置用作参数并使用它,而不是使用当前设置的区域设置。 有关详细信息,请参阅 Locale

strftime 函数支持以下格式化代码:

代码 替换字符串
%a 区域设置中的缩写工作日名称
%A 区域设置中的完整工作日名称
%b 区域设置中的缩写月份名称
%B 区域设置中的完整月份名称
%c 适用于区域设置的日期和时间表示
%C 年份除以 100,截断为整数,以十进制数表示 (00−99)
%d 月内日期以十进制数表示 (01 - 31)
%D 等效于 %m/%d/%y
%e 月内日期以十进制数表示 (1 - 31),其中单个数字前面加一个空格
%F 等效于 %Y-%m-%d
%g ISO 8601 基于周的年份的最后 2 位数字以十进制数字表示 (00 - 99)
%G ISO 8601 基于周的年份以十进制数表示
%h 缩写月份名称(等效于 %b
%H 24 小时制的小时 (00 - 23)
%I 12 小时制的小时 (01 - 12)
%j 一年中的某天以十进制数表示 (001 - 366)
%m 月份以十进制数字表示 (01 - 12)
%M 分钟以十进制数字表示 (00 - 59)
%n 换行符 (\n)
%p 区域设置的 A.M./P.M. 指示器,12 小时制
%r 区域设置的 12 小时制时间
%R 等效于 %H:%M
%S 秒以十进制数表示 (00 - 59)
%t 水平制表符 (\t)
%T 等效于 %H:%M:%S,ISO 8601 时间格式
%u ISO 8601 工作日以十进制数字表示(1 - 7;星期一为 1)
%U 年份的周数以十进制数字表示 (00 - 53),其中第一个星期日是第 1 周的第一天
%V ISO 8601 周数以十进制数字表示 (00 - 53)
%w 工作日以十进制数字表示(0 - 6;星期日为 0)
%W 年份的周数以十进制数字表示 (00 - 53),其中第一个星期一是第 1 周的第一天
%x 区域设置的日期表示形式
%X 区域设置的时间表示形式
%y 不带世纪数的年份以十进制数字表示 (00 - 99)
%Y 以十进制数字表示的带有世纪数的年份
%z 采用 ISO 8601 格式的 UTC 偏移量;如果时区未知,则没有字符
%Z 区域设置的时区名称或时区缩写取决于注册表设置;如果时区未知,则没有字符
%% 百分号

与在 printf 函数中一样,# 标志可以成为任何格式化代码前缀。 在这种情况下,格式代码的含义更改为如下内容。

格式代码 含义
忽略 # 标志。
%#c 长的日期和时间表示形式,适用于区域设置。 例如:“1995 年 3 月 14 日,星期二,12:41:29”。
%#x 长的日期表示形式,适用于区域设置。 例如:“1995 年 3 月 14 日,星期二”。
请删除前导零或空格(如果有)。

%V%g%G 生成的 ISO 8601 周和基于周的年份使用从周一开始的一周。 第 1 周是包含 1 月第 4 天的一周,这是包含一年中至少四天的第一周。 如果年份的第一个星期一是 2 日、3 日或 4 日,则前几天属于上一年的最后一周。 对于这些日期,%V 将替换为 53,并且 %g%G 都将替换为上一年的数字。

注意

将其中一个 strftime 函数与从 gmtime 返回的 tm 指针一起使用时,通过 %Z%z 说明符打印的值将不准确。 这是因为 C 标准指定的 tm 结构不包含时区名称或偏移量信息, 而是通过全局变量 _timezone_dstbias 填充时区信息。

要求

例程 必需的标头
strftime <time.h>
wcsftime <time.h><wchar.h>
_strftime_l <time.h>
_wcsftime_l <time.h><wchar.h>

_strftime_l_wcsftime_l 函数是 Microsoft 特定函数。 有关兼容性的详细信息,请参阅 兼容性

示例

请参阅 time 的示例。

另请参阅

区域设置
工时管理
字符串操作
localeconv
%>
strcoll 函数