格式化时间字符串。
语法
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 函数根据提供的 format 参数格式化 timeptr 中的 tm 时间值，并将结果存储在 strDest 缓冲区中。 该字符串最多可放置 maxsize 个字符。 有关 timeptr 结构中字段的说明，请参阅 asctime。 wcsftime 是等同于 strftime 的宽字符；它的字符串指针参数指向宽字符字符串。 否则这些函数具有相同行为。
此函数验证其参数。 如果 strDest、format 或 timeptr 是空指针，或者如果由 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。）strftime 和 wcsftime 函数使用当前设置的区域设置。 这些函数的 _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 的示例。