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 ,且陣列內容不確定。