# C 语言标准库函数 strftime

/*********************************************
 * @brief 将日历时间 struct tm 转换为自定义的文本形式
 * @param[out] str 返回转换后的文本
 * @param count 最多可写入 str 的字节数（含结尾的 '\0'）
 * @param fmt 格式字符串
 * @param t 要被转换的时间
 * @return 返回写入 str 的字节数
 ********************************************/
size_t strftime(char* str, size_t count, const char* fmt, const struct tm* t);

!subtitle:说明

将日历时间 tm 转换为自定义的文本形式。

!subtitle:参数

• str - 回转换后的文本（含结尾的 '\0'）

• count - 最多可写入 str 的字节数（含结尾的 '\0'）

• fmt - 格式字符串

• t - 要被转换的日历时间

!subtitle:返回值

• 成功时返回写入 str 的字节数（不含结尾的 \0）

• 失败时返回 0（例如需要写入的字节数大于 count）

# 格式

格式字符串由零个或多个转换说明符和普通字符（% 除外）组成。所有普通字符（包括终止字符 \0）均会原封不动地复制到输出字符串中。

每个转换说明符均以 % 字符开头，后跟可选的 E 或 O（大写字母）修饰符（如果语言环境不支持，则忽略），后跟决定说明符行为的字符。

可用的格式说明符如下：

| 占位符（日） | 标准 | 说明 | 示例输出 | | :- | :- | :- | :- | | %j | C89 | 一年中的第几天（范围[01,366]） | "233" | | %d | C89 | 月份中的日期（范围[01,31]） | "5" | | %e | C99 | 月份中的日期（范围[01,31]），单个数字前补空格 | " 5" | | %Od | C99 | 替代数字系统的 %d | "五" | | %0e C99 | 替代数字系统的 %e | " 五" |

# 示例

#include <locale.h>
#include <stdio.h>
#include <time.h>
 
int main(void)
{
    char buff[256];
    struct tm my_time = { .tm_year = 111,   // = 2012 年
                          .tm_mon = 9,      // = 10 月
                          .tm_mday = 9,     // = 5 日
                          .tm_hour = 13,    // = 13 时
                          .tm_min = 6,      // = 6 分
                          .tm_sec = 42      // = 43 秒
    };
 
    if (strftime(buff, sizeof buff, "%Y %m %d %A", &my_time))
        puts(buff);
    else
        puts("失败");

    // 日期格式设为中文
    setlocale(LC_TIME, "zh_CN.UTF-8");

    if (strftime(buff, sizeof buff, "%EY %Om %Od %A", &my_time))
        puts(buff);
    else
        puts("失败");

    // 日期格式设为日文
    setlocale(LC_TIME, "ja_JP.UTF-8");

    if (strftime(buff, sizeof buff, "%EY %Om %Od %A", &my_time))
        puts(buff);
    else
        puts("失败");

    return 0;
}

运行结果：

2011 10 09 Sunday
2011 10 09 星期日
平成23年 十 九 日曜日

# 推荐阅读

• strftime - cppreference

• strftime - POSIX

# 参考标准

• C23 standard (ISO/IEC 9899:2024):

  • 7.29.3.5 The strftime function (p: TBD)

• C17 standard (ISO/IEC 9899:2018):

  • 7.27.3.5 The strftime function (p: 288-291)

• C11 standard (ISO/IEC 9899:2011):

  • 7.27.3.5 The strftime function (p: 394-397)

• C99 standard (ISO/IEC 9899:1999):

  • 7.23.3.5 The strftime function (p: 343-347)

• C89/C90 standard (ISO/IEC 9899:1990):

  • 4.12.3.5 The strftime function