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 子常式會將 TmDate 參數所指向之 tm 結構的內部時間和日期規格，在 Format 參數所指向之格式字串的方向下，轉換成 String 參數所指向的字串。 格式指定元的實際值取決於 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

    以十進位數 (00 到 99 ，從 time.h 程式庫的 tm 結構中定義的標準術語 tm_year 計算) 代表世紀數字 (年份除以 100 並截斷為整數)

    如果未指定欄位寬度下限，則 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 以十進位數表示 12 小時制小時 (01 到 12)。
    %j 以十進位數 (001 至 366) 代表一年中的第幾天。
    %k 以向右對齊的填入空間數字 (0 到 23) 來代表 24 小時制時鐘。
    %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 代表 24 小時制時間，格式為 %H: %M: %S (例如，16:55:15).
    %u 以十進位數 (1 到 7) 代表平日。 在計算此欄位描述子的值時，會將星期一或其對等項目視為一週的第一天。
    %u 以十進位數 (00 到 53) 代表一年中的第幾週。 LC_TIME 種類中的 day 陳述式所定義的 Sunday 或其對等項目，會被視為計算此欄位描述子值的一週的第一天。
    %V 以十進位數 (01 至 53) 代表 ISO 8601 週型年的週數 (以星期一為一週的第一天)。 如果包含 1 月 1 日的週在新的一年中有四天以上，則會將它視為第 1 週; 否則會將它視為前一年的第 52 週 (如果前一年是閏年，則會將它視為第 53 週) ，而下一週則是新一年的第 1 週。
    %w 以十進位數表示星期幾 (0 到 6)。 在計算此欄位描述子的值時， Sunday 或其如 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 代表 ISO 8601 格式的「世界標準時間 (UTC)」偏移 − 0430 表示比 UTC 晚 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 代表年份的週數，使用語言環境的替代數值符號。 星期日被視為一週的第一天。 使用對應於 %U 轉換指定元的規則。
%OV 代表使用語言環境替代數值符號的年週數 (星期一是一週的第一天，規則對應於 %V)。
%Ow 代表平日 (星期日等於 0) 的數字，使用語言環境的替代數值符號。
%OW 代表使用語言環境替代數值符號的年份週數。 星期一被視為一週的第一天。 使用對應於 %W 轉換指定元的規則。
%Oy 代表使用語言環境替代數值符號的年份 (與 %C 的偏移)。

strftime_l() 子常式與 strftime() 子常式類似，但語言環境變數中指定的語言環境資訊除外。 如果 strftime_l() 子常式中的語言環境變數設為特殊語言環境物件 LC_GLOBAL_LOCALE，或不是有效的語言環境物件控點，則 strftime_l() 子常式可能會導致非預期的結果。

參數

項目 說明
字串 指向字串以保留格式化時間。
長度 指定 String 參數所指向的字串長度上限。
格式 指向格式字串。
TmDate 指向要轉換的時間結構。
語言環境 指向包含語言環境資訊的語言環境物件。

回覆值

如果產生的位元組總數 (包括終止空值位元組) 不超過 長度 值，則 strftime 子常式會傳回在 String 參數所指向的陣列中放置的位元組數，不包括終止空值位元組。 否則，會傳回值 0 ，且陣列內容不確定。