strftime, wcsftime, _strftime_l, _wcsftime_l

格式化时间字符串。

语法

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 缓冲区的大小,以字符(char 或 wchar_t)为单位。

format
窗体控件字符串。

timeptr
tm 数据结构。

locale
要使用的区域设置。

返回值

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

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

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

备注

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

此函数验证其参数。 如果 strDest、format 或 timeptr 是空指针,或者如果由 tm 寻址的 timeptr 数据结构无效(例如,如果它包含超出时间或日期的范围值),或者如果 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 函数支持以下格式化代码:

Code 替换字符串
%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 函数中一样,# 标志可以成为任何格式化代码前缀。 在这种情况下,格式代码的含义更改为如下内容。

格式代码 含义
%#a, %#A, %#b, %#B, %#g, %#G, %#h, %#n, %#p, %#t, %#u, %#w, %#X, %#z, %#Z, %#% 忽略 # 标志。
%#c 长的日期和时间表示形式,适用于区域设置。 例如:“1995 年 3 月 14 日,星期二,12:41:29”。
%#x 长的日期表示形式,适用于区域设置。 例如:“1995 年 3 月 14 日,星期二”。
%#d, %#D, %#e, %#F, %#H, %#I, %#j, %#m, %#M, %#r, %#R, %#S, %#T, %#U, %#V, %#W, %#y, %#Y 请删除前导零或空格(如果有)。

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

注意

将其中一个 strftime 函数与从 tm 返回的 gmtime 指针一起使用时,通过 %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 函数
strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l