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 函数根据提供的 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 函数中一样，# 标志可以成为任何格式化代码前缀。 在这种情况下，格式代码的含义更改为如下内容。

格式代码	含义
%#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 函数与从 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
setlocale、_wsetlocale
strcoll 函数
strxfrm、wcsxfrm、_strxfrm_l、_wcsxfrm_l