当前位置： C语言 -- 标准库 -- <wchar.h> -- wcsftime

wcsftime函数

概要： 
#include <time.h>
#include <wchar.h>
size_t wcsftime(wchar_t * restrict s,
      size_t maxsize,
      const wchar_t * restrict format,
      const struct tm * restrict timeptr);
描述：

wcsftime函数等价于strftime函数，区别主要在于以下四个方面：

- wcsftime函数中，参数s指向宽字符数组的初始元素；而不是字符数组的初始元素。

- wcsftime函数中，参数maxsize表示宽字符的最大数量；而不是字符的最大数量。

- wcsftime函数中，参数format是宽字符串，转换说明符应使用对应的宽字符序列替换。

- wcsftime函数的返回值表示宽字符数；而不是字符数。


该函数将struct tm类型的分解时间格式化为宽字符串。

该函数将结果宽字符存入参数s指向的数组，结果宽字符的内容和格式由参数format指向的宽字符串控制。参数format指向宽字符串由0个或者多个转换说明符和普通宽字符组成。转换说明符由一个%字符、修饰字符E或者0（可能有）和决定转换说明符行为的宽字符组成。所有普通宽字符（包括终止空宽字符。）不作任何改变直接复制到数组中。如果复制发生在重叠对象之间，函数行为是未定义的。最多向参数s指向的数组存入maxsize个宽字符。


每个转换说明符由下表中的相应字符替换。相应字符应使用当前语言环境的LC_TIME类别和参数timeptr指向的分解时间中0个或者多个成员值来确定。如果指定值超出了正常范围，存入数组的宽字符是不确定的。

转换说明符 替换字符 实例
%a

当前语言环境简写的星期名称。[tm_wday]

 周五
%A

当前语言环境完整的星期名称。[tm_wday]

 星期五
%b

当前语言环境简写的月份名称。[tm_mon]

 10月
%B

当前语言环境完整的月份名称。[tm_mon]

 十月
%c

当前语言环境首选的日期和时间表示形式。[ISO/IEC 9899:2018标准第7.27.1节中指定。]

 2049/10/1 8:00:00
%C

将年份除以100，然后截取其整数部分(00-99)。[tm_year]

 20
%d

月的第几天，如果是个位数，前置0(01-31)。[tm_mday]

 01
%D

等价于"%m/%d/%y"。[tm_mon,tm_mday,tm_year]

 10/01/49
%e

月的第几天，如果是个位数，前置空格(1-31)。[tm_mday]

 .1
%F

等价于"%Y-%m-%d"(ISO 8601日期格式)。[tm_year,tm_mon,tm_mday]

 2049-10-01
%g

星期为基础的年份的最后两个数字(00-99)。[tm_year,tm_wday,tm_yday]

 49
%G

星期为基础的年份(例如：1997)。[tm_year,tm_wday,tm_yday]

 2049
%h

等价于"%b"。[tm_mon]

 10月
%H

24小时时钟的小时(00-23)。[tm_hour]

 08
%I

12小时时钟的小时(01-12)。[tm_hour]

 08
%j

年的第几天(001-366)。[tm_yday]

 274
%m

月份(01-12)。[tm_mon]

 10
%M

分钟(00-59)。[tm_min]

 00
%n

换行符('\n')。
%p

当前语言环境中等效于AM或者PM的字符，00:00:00至12:00:00（不包括12:00:00）为AM；12:00:00至 24:00:00（包括12:00:00）为PM。[tm_hour]

 上午
%r

当前语言环境12小时时钟时间。[tm_hour,tm_min,tm_sec]

 8:00:00
%R

等价于"%H:%M"。[tm_hour,tm_min]

 08:00
%S

秒(00-60)。[tm_sec]

 00
%t

水平制表符('\t')。
%T

等价于"%H:%M:%S(ISO 8601时间格式)"。[tm_hour,tm_min,tm_sec]

 08:00:00
%u

数字1-7，其中数字1表示Monday，以此类推。[tm_wday]

 5
%U

一年中的第几周(第一个星期天作为第一周的第一天。)(00-53)。[tm_year,tm_wday,tm_yday]

 39
%V

ISO 8601标准一年中的第几周(01-53)。[tm_year,tm_wday,tm_yday]

 39
%w

数字0-6，其中数字0表示Sunday，以此类推。[tm_wday]

 5
%W

一年中的第几周(第一个星期一作为第一周的第一天。)(00-53)。[tm_year,tm_wday,tm_yday]

 39
%x

当前语言环境的日期表示。[ISO/IEC 9899:2018标准第7.27.1节中指定。]

 2049/10/1
%X

当前语言环境的时间表示。[ISO/IEC 9899:2018标准第7.27.1节中指定。]

 8:00:00
%y

年份的最后两位数字(00-99)。[tm_year]

 49
%Y

年份(例如:1997)。[tm_year]

 2049
%z

ISO 8601标准中相对于UTC的偏离值，例如："-0430"表示位于格林威治以西，落后UTC时间4小时30分钟;如果时区不确定，将没有字符用来替换。[tm_isdst]

 +0800
%Z

当前语言环境的时区名称或者简写；如果时区不确定，将没有字符用来替换。[tm_isdst]

 中国标准时间
%% %

注：所有实例在本地默认的语言环境（即Chinese (Simplified)_China.936）下使用Visual Studio软件测试，所用时间为2049-10-1 08:00:00。


有些转换说明符可以通过包含E或者0修饰字符来表示替代格式或者规范。如果当前语言环境中替代格式或者规范不存在，修饰符会被忽略。

使用修饰符的转换说明符 替代字符 实例
%Ec

当前语言环境日期和时间的替代表示形式。

 2049/10/1 8:00:00
%EC

当前语言环境替代表示形式中基准年（期间）的名称。

 20
%Ex

当前语言环境日期的替代表示形式。

 2049/10/1
%EX

当前语言环境时间的替代表示形式。

 8:00:00
%Ey

当前语言环境的替代表示形式中相对于%EC（仅限年份）的偏移量。

 49
%EY

当前语言环境完整年份的替代表示形式。

 2049
%0d

使用当前语言环境替代数字符号（根据需要使用前导0填充，如果没有替代0符号，使用前导空格填充。）表示的月的第几天。
%0e

使用当前语言环境替代数字符号（根据需要使用前导空格填充。）表示的月的第几天。
%0H

使用当前语言环境替代数字符号表示的24小时时钟的小时。
%0I

使用当前语言环境替代数字符号表示的12小时时钟的小时。
%0m

使用当前语言环境替代数字符号表示的月份。
%0M

使用当前语言环境替代数字符号表示的分钟。
%0S

使用当前语言环境替代数字符号表示的秒。
%0u

使用当前语言环境替代表示中的数字表示的ISO 8601标准的星期几，其中星期一是1。
%0U

使用当前语言环境替代数字符号表示的一年中的第几周。
%0V

使用当前语言环境替代数字符号表示的ISO 8601标准一年中的第几周。
%0w

使用当前语言环境替代数字符号中的数字表示的的星期几。
%0W

使用当前语言环境替代数字符号表示的一年中的第几周。
%0y

使用当前语言环境替代数字符号表示的年份的最后两个数字。

注：所有实例在本地默认的语言环境（即Chinese (Simplified)_China.936）下使用Visual Studio软件测试，所用时间为2049-10-1 08:00:00。


%g、%G和%V根据ISO 8601标准基于周的年份给出值。在这个系统中，周从星期一开始，并且一年中的第一周是包含1月4日的那一周，这也是一年中包含第一个星期四的周，也是第一个至少包含四天的周。如果一月的第一个星期一是第2天、第3天或者第4天，则前几天是上一年最后一周的一部分，例如：1999年1月2日是星期六，%G使用1998替换，%V使用53替换。如果12月29日、30日或者31日是星期一，其以及其后的日子都是下一年第一周的一部分，例如：1997年12月29日是星期一，%G使用1998替换，%V使用01替换。

如果转换说明符不属于上述形式，函数行为是未定义的。


默认环境中(即“C”语言环境),修饰符E和0将被忽略；下述转换说明符的替换字符串分别如下表所示：

转换说明符 替换字符
%a

%A的前三个字符。
%A

"Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"其中之一。
%b

%B的前三个字符。
%B

“January”,"February","March","April","May","June","July","August","September","October","November","December"其中之一。
%c

等价于"%a %b %e %T %Y"。
%p

"AM","PM"其中之一。
%r

等价于"%I:%M:%S %p"。
%x

等价于"%m/%d/%y"。
%X

等价于%T。
%Z

由实现定义。
参数：
wchar_t * restrict s

wchar_t类型指针，结果宽字符将存储到其指向的数组中。

size_t maxsize

最多可以向参数s指向的数组中存储的宽字符数。

const wchar_t * restrict format

wchar_t类型指针，指向对象由普通宽字符和转换说明符组成。

const struct tm * restrict timeptr

指向struct tm类型对象的指针。

返回值：

如果结果总宽字符数(包括终止空宽字符)不超过maxsize，函数返回存入参数s指向数组的宽字符数(不包括终止空宽字符。)；否则函数返回0，并且数组内容是不确定的。

范例： 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
/*函数wcsftime范例*/

#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <wchar.h>

#define LENGTH 100

int main(void)
{
    setlocale(LC_ALL, "");
    
    struct tm queryDate = {0};  //存储查询日期。
    wchar_t wArr[LENGTH];       //存储调用wcsftime函数后的结果宽字符。
    
    /*输入查询的日期。*/
    fputws(L"输入年：", stdout);
    wscanf(L"%d", &(queryDate.tm_year));
    
    fputws(L"输入月：", stdout);
    wscanf(L"%d", &(queryDate.tm_mon));
    
    fputws(L"输入日：", stdout);
    wscanf(L"%d", &(queryDate.tm_mday));
    
    /*将数据处理成struct tm类型的要求格式。*/
    queryDate.tm_year -= 1900;
    queryDate.tm_mon -= 1;
    
    /*将struct tm对象所有结构成员都处理成对应的值。*/
    if(mktime(&queryDate) == (time_t)(-1))
    {
        fputws(L"不能表示日历时间。", stdout);
        exit(EXIT_FAILURE);
    }

    /*格式化struct tm类型日历时间，并输出结果。*/
    wcsftime(wArr, LENGTH, L"%c %A %Z", &queryDate);
    fputws(wArr, stdout);

    return 0;
}
结果：

假设输入为：

输入年: 2049

输入月: 10

输入日: 1

将输出：

2049/10/1 0:00:00 星期五 中国标准时间

注：使用Visual Studio编译。

相关内容：
struct tm 表示分解时间的结构类型。