strftime 或 strftime_l 子例程

在线编辑

用途

格式化时间和日期。

库

标准 C 库 (libc.a)

语法

#include <time.h>
size_t strftime ( String, Length, Format, TmDate)
char *String;
size_t Length;
const char *Format;
const struct tm *TmDate;
size_t strftime_l(char *restrict String, size_t Length,
const char *restrict Format, const struct tm *restrict TmDate,locale_t Locale);

描述

strftime 子例程将 tm 结构的内部时间和日期规范 (由 TmDate 参数指向) 转换为由 String 参数在 Format 参数指向的格式字符串的方向下指向的字符串。 格式说明符的实际值取决于 LC_TIME 类别的当前设置。 tm 结构值可以由用户指定，也可以由 localtime 或 gmtime 子例程生成。 生成的字符串类似于 printf Format 参数的结果，并放置在由 String 参数寻址的内存位置。 字符串的最大长度由 Length 参数确定，并以空字符终止。

许多转换规范与 date 命令使用的转换规范相同。 某些转换规范的解释取决于进程的当前语言环境。

Format 参数是一个字符串，其中包含两种类型的对象: 简单放置在输出字符串中的纯字符，以及将 TmDate 参数中的信息转换为输出字符串中的可读格式的转换规范。 每个转换规范都是以下格式的序列: % type。

  • % (百分号) 引入了转换规范。
  • 转换类型由一个或两个转换字符指定。 人物及其含义是:
    项 描述
    %a 表示语言环境的缩写平日名称 (例如，Sun) 由 LC_TIME 类别中的 abday 语句定义。
    %A 表示语言环境的完整工作日名称 (例如，Sunday) 由 LC_TIME 类别中的 day 语句定义。
    %b 表示语言环境的缩写月份名称 (例如，Jan) 由 LC_TIME 类别中的 abmon 语句定义。
    %B 表示语言环境的完整月份名称 (例如，January) 由 LC_TIME 类别中的 mon 语句定义。
    %c 表示由 LC_TIME 类别中的 d_t_fmt 语句定义的语言环境的日期和时间格式。
    %C

    将世纪数 (年除以 100 并截断为整数) 表示为十进制数 (从 time.h 库的 tm 结构中定义的标准项 tm_year 计算的 00 到 99)

    如果未指定最小字段宽度，那么放入 string 参数指向的数组中的字符数是年份中的位数除以 100 或 2 (以较大者为准)。 如果指定了最小字段宽度，那么放入 string 参数所指向的数组中的字符数是年份中的位数除以 100 或最小字段宽度 (以较大者为准)。
    %d 以十进制数字 (01 到 31) 表示月份中的日期。
    %D 以 %m/%d/%y 格式表示日期 (例如，01/31/91).
    %e 以十进制数字 (01 到 31) 表示月份中的日期。 %e 字段描述符使用两位数字段。 如果月份中的日期不是两位数，那么将使用空格字符填充前导数字。
    %E 分别以 %o %N 格式表示语言环境的组合备用年份和名称。
    %F

    如果未指定标志和最小字段宽度 (根据 time.h 库的 tm 结构中定义的标准术语 tm_year， tm_mon和 tm_mday 计算) ，那么表示 %+4Y-%m-%d 格式的日期。

    如果指定了小于或等于 6 字节的最小字段宽度，那么年份的输出字符串与 Y 说明符使用任何指定的标志和最小字段宽度 6 字节的输出字符串相同。 如果指定的字段宽度小于 6 字节，那么缺省情况下会将字段宽度视为 6 字节。

    如果将最小字段宽度指定为 10 字节，并且年份的长度为四位数，那么生成的输出字符串将与 ISO 8601:2000 标准子句 4.1.2.2 完整表示，特定日期 (YYYY-MM-DD) 的扩展格式日期表示相匹配。 例如， 2021-05-20。

    如果指定了 + 标志和大于 6 字节的最小字段宽度，并且 7 字节足以容纳年份的数字 (不包括任何符号字符) ，那么输出字符串将与 ISO 8601:2000 标准条款 4.1.2.4 完整表示，特定日期 (± YYYYY-MM-DD) 的扩展格式日期表示相匹配。 例如， + 002021-05-20。
    %G

    以十进制数字表示基于周的年份，例如，1977(根据 time.h 库的 tm 结构中定义的标准术语 tm_year， tm_wday和 tm_yday 计算)。

    如果指定了最小字段宽度，那么放置在 string 参数所指向的数组中的字符数是年份中的数字和前导符号字符 (如果有) 的数目，或最小字段宽度 (以较大者为准)。
    %g 以十进制数 (0 到 99) 表示基于 ISO 8601 周的年份的最后两位数字。 就像 %G ，但没有世纪。 (从 tm_year ， tm_yday 和 tm_wday 计算。)
    %h 表示语言环境的缩写月份名称 (例如，Jan) 由 LC_TIME 类别中的 abmon 语句定义。 此字段描述符是 %b 字段描述符的同义词。
    %H 以十进制数字 (00 到 23) 表示 24 小时制小时。
    %I 以十进制数字 (01 到 12) 表示 12 小时制小时。
    %j 以十进制数字 (001 到 366) 表示年的日期。
    %k 将 24 小时制时钟表示为右对齐的空间填充数字 (0 到 23)。
    %m 以十进制数字 (01 到 12) 表示一年中的月份。
    %m 以十进制数 (00 到 59) 表示小时的分钟数。
    %n 指定换行符。
    %N 表示语言环境的备用时代名称。
    %o 表示交替的时代年份。
    %p 表示语言环境的 a.m。 或 p.m。 由 LC_TIME 类别中的 am_pm 语句定义的字符串。
    %r 表示具有 a.m./p.m的 12 小时时钟时间。 t_fmt_ampm 语句定义的表示法。 通常的格式为 %I: %M: %S %p。
    %R 表示 %H: %M 格式的 24 小时时钟时间。
    %s 表示自 1970 年 1 月 1 以来的秒数，全球标准时间 (CUT)。
    %S 以十进制数 (00 到 59) 表示分钟的秒数。
    %t 指定跳进字符。
    %T 以格式 %H: %M: %S 表示 24 小时制时间 (例如，16:55:15).
    %u 以十进制数字 (1 到 7) 表示工作日。 对于计算此字段描述符的值， "星期一" 或其等效项被视为一周中的第一天。
    %u 以十进制数字 (00 到 53) 表示一年中的周。 周日或其等效项 (由 LC_TIME 类别中的 day 语句定义) 被视为计算此字段描述符的值的一周中的第一天。
    %V 表示基于 ISO 8601 周的年份 (以星期一为一周的第一天) 的周数作为十进制数 (01 到 53)。 如果包含 1 月 1 的周在新年中有 4 天或更多天，那么将其视为周 1; 否则，将其视为前一年的第 52 周 (如果前一年是闰年，那么将其视为 53 周) ，而下一周是新年的第 1 周。
    %w 以十进制数字 (0 到 6) 表示星期几。 对于计算此字段描述符的值，星期日或其等效项 (由 day 语句定义) 被视为 0。
    %W 以十进制数字 (00 到 53) 表示一年中的周。 在计算此字段描述符的值时，会将 "星期一" 或 day 语句定义的等效项视为一周中的第一天。
    %x 表示语言环境的日期格式，如 d_fmt 语句所定义。
    %X 表示语言环境的时间格式，如 t_fmt 语句所定义。
    %y 表示世纪之年。
    注: 当环境变量 XPG_TIME_FMT=ON时， %y 是世纪内的年份。 当没有以其他方式指定一个世纪时， 69 至 99 范围内的值是指 20 世纪的年份 (1969 至 1999 年包括在内); 00 至 68 范围内的值是指 2000 至 2068 (包括在内)。
    %Y

    以十进制数字表示年份，例如，1989(根据 time.h 库的 tm 结构中定义的标准术语 tm_year计算)。

    如果指定了最小字段宽度，那么放置在 string 参数所指向的数组中的字符数是年份中的数字和前导符号字符 (如果有) 的数目，或最小字段宽度 (以较大者为准)。
    %z 表示与全球标准时间 (UTC) 的偏移量，采用 ISO 8601 格式 − 4 3 0 表示比 UTC 晚 30 分钟 4 小时，格林威治以西 30 分钟，如果无法确定时区 [tm_isdst] ，那么不使用任何字符。
    注: 必须设置 XPG_SUS_ENV=ON 环境变量的值以使用 %z 选项，否则它将回退到 %Z 选项。
    %z 表示时区名称 (如果可以确定时区名称) (例如， EST)。 如果无法确定时区，那么不会显示任何字符。
    %% 指定% (百分号)。

某些转换说明符可由 E 或 O 修饰符字符修改，以指示应使用替代格式或规范。 如果当前语言环境不存在备用格式或规范，那么行为将与未修改的转换规范相同。 支持以下已修改的转换说明符:

项 描述
%ec 表示语言环境的备用适当日期和时间，如 era_d_t_fmt 语句所定义。
%ec 表示当前时代的 era_name 类别下的 era 语句所定义的语言环境备用格式的基准年 (或其他时间段) 的名称。
%Ex 表示语言环境的备用日期，由 era_d_fmt 语句定义。
%EX 表示语言环境的备用时间，如 era_t_fmt 语句所定义。
%Ey 以语言环境的替代格式表示与 %EC 修改的转换说明符 (仅限年份) 的偏移量。
%EY 表示完整的备用年份格式。
%Od 使用语言环境的备用数字符号表示月份中的日期，如果存在 0 的备用符号，那么将根据需要使用前导 0 进行填充。 如果 0 的备用符号不存在，那么 %Od 修改后的转换说明符将使用前导空格字符。
%Oe 使用语言环境的备用数字符号表示月份中的日期，如果存在 0 的备用符号，那么将根据需要使用前导 0 进行填充。 如果 0 的备用符号不存在，那么 %Oe 修改后的转换说明符将使用前导空格字符。
%OH 使用语言环境的备用数字符号表示 24 小时制时间中的小时。
%OI 表示使用语言环境的备用数字符号的 12 小时时钟时间中的小时。
%Om 表示月份，使用语言环境的备用数字符号。
%OM 表示分钟，使用语言环境的备用数字符号。
%OS 表示秒数，使用语言环境的备用数字符号。
%Ou 使用语言环境的备用数字符号将工作日表示为数字。
%OU 使用语言环境的备用数字符号表示年的周数。 星期日认为是一周中的第一天。 使用与 %U 转换说明符对应的规则。
%OV 使用语言环境的备用数字符号表示一年中的周数 (星期一作为一周的第一天，规则对应于 %V)。
%Ow 表示工作日的编号 (星期日等于 0) ，使用语言环境的备用数字符号。
%OW 表示使用语言环境的备用数字符号的年份的周数。 星期一认为是一周中的第一天。 使用与 %W 转换说明符对应的规则。
%Oy 表示使用语言环境的备用数字符号的年份 (与 %C 的偏移量)。

strftime_l() 子例程类似于 strftime() 子例程，但语言环境变量中指定的语言环境信息除外。 如果 strftime_l() 子例程中的语言环境变量设置为特殊语言环境对象 LC_GLOBAL_LOCALE，或者不是有效的语言环境对象句柄，那么 strftime_l() 子例程可能会产生意外结果。

参数

项 描述
String 指向用于保存格式化时间的字符串。
长度 指定 String 参数指向的字符串的最大长度。
格式 指向格式字符串。
TmDate 指向要转换的时间结构。
语言环境 指向包含语言环境信息的语言环境对象。

返回值

如果生成的字节总数 (包括终止空字节) 不超过 Length 值，那么 strftime 子例程返回放入 String 参数指向的数组中的字节数，不包括终止空字节。 否则，将返回值 0 ，并且数组的内容不确定。