strftime, wcsftime, _strftime_l, _wcsftime_l

設定時間字串的格式。

語法

size_t strftime(
   char *strDest,
   size_t maxsize,
   const char *format,
   const struct tm *timeptr
);
size_t _strftime_l(
   char *strDest,
   size_t maxsize,
   const char *format,
   const struct tm *timeptr,
   _locale_t locale
);
size_t wcsftime(
   wchar_t *strDest,
   size_t maxsize,
   const wchar_t *format,
   const struct tm *timeptr
);
size_t _wcsftime_l(
   wchar_t *strDest,
   size_t maxsize,
   const wchar_t *format,
   const struct tm *timeptr,
   _locale_t locale
);

參數

strDest
輸出字串。

maxsize
strDest 緩衝區的大小，以字元 (char 或 wchar_t) 為單位。

format
格式控制字串。

timeptr
tm 資料結構。

locale
要使用的地區設定。

傳回值

strftime 會傳回放在 strDest 中的字元數，而 wcsftime 會傳回對應的寬字元數。

如果總字元數 (包括結束 Null) 超個 maxsize，strftime 和 wcsftime 會傳回 0 且無法確定 strDest 的內容。

中的 strDest 字元數等於 中的 format 常值字元數，加上任何可透過格式化程式碼新增至 format 的字元數。 字串的終止 Null 不會計入傳回值中。

備註

和 wcsftime 函 strftime 式會根據提供的 format 引數格式化 tm 中的 timeptr 時間值，並將結果儲存在緩衝區 strDest 中。 字串中最多可放置 maxsize 個字元。 如需 結構中 timeptr 欄位的描述，請參閱 asctime 。 wcsftime 是 strftime 的寬字元對應項，其字串指標引數會指向寬字元字串。 除此之外，這些函式的行為相同。

這個函式會驗證它的參數。 如果 strDest 、 format 或 timeptr 是 Null 指標，或 tm 如果定址 timeptr 的資料結構無效（例如，如果它包含時間或日期的範圍值超出範圍值），或 format 字串包含不正確格式代碼，則會叫用不正確參數處理常式，如參數驗證 中所述 。 如果允許繼續執行，則函式會傳回 0 並將 errno 設定為 EINVAL。

根據預設，此函式的全域狀態會限定于應用程式。 若要變更此行為，請參閱 CRT 中的全域狀態。

泛型文字常式對應

TCHAR.H 常規	_UNICODE 和 _MBCS 未定義	_MBCS 定義	_UNICODE 定義
_tcsftime	strftime	strftime	wcsftime

format 引數是由一或多個程式碼所組成；例如在 printf 中，格式代碼前會加上百分比符號 (%)。 開頭的 % 字元會保持不變地 strDest 複製到 。 目前地區設定的 LC_TIME 分類會影響 strftime 的輸出格式 （如需 的詳細資訊 LC_TIME ，請參閱 setlocale 。）和 wcsftime 函 strftime 式會使用目前設定的地區設定。 這些 _strftime_l 函式的 和 _wcsftime_l 版本完全相同，不同之處在于它們會採用地區設定做為參數，並使用 ，而不是目前設定的地區設定。 如需詳細資訊，請參閱 Locale。

函 strftime 式支援這些格式代碼：

代碼	取代字串
%a	地區設定中縮寫的工作日名稱
%A	地區設定中的完整工作日名稱
%b	地區設定中的縮寫月份名稱
%B	地區設定中的完整月份名稱
%c	適用於地區設定的日期和時間表示
%C	年份除以 100，並截斷為整數，以十進位數 （00~99）
%d	以十進位數表示的月份日 （01 - 31）
%D	相當於 %m/%d/%y。
%e	以十進位數表示的月份日 （1 - 31），其中單一數位前面有空格
%F	相當於 %Y-%m-%d。
%g	ISO 8601 周型年份的最後 2 位數為十進位數 （00 - 99）
%G	ISO 8601 以十進位數表示的 ISO 8601 周型年份
%h	縮寫月份名稱 （相當於 %b ）
%H	24 小時格式的小時 （00 - 23）
%I	12 小時格式的小時 （01 - 12）
%j	以十進位數表示的年度日 （001 - 366）
%m	月份為十進位數 （01 - 12）
%M	以十進位數表示的分鐘數 （00 - 59）
%n	分行符號 （ \n ）
%p	地區設定的 A.M./P.M. 指標為 12 小時制
%r	地區設定的 12 小時制時間
%R	相當於 %H:%M。
%S	第二個做為十進位數 （00 - 59）
%t	水準定位字元 （ \t ）
%T	相當於 %H:%M:%S ，ISO 8601 時間格式
%u	ISO 8601 工作日做為十進位數 （1 - 7;星期一為 1）
%U	年份的周數為十進位數 （00 - 53），其中第一個星期天是第 1 周的第一天
%V	ISO 8601 周數做為十進位數 （00 - 53）
%w	工作日為十進位數 （0 - 6;星期日為 0）
%W	年份的周數為十進位數 （00 - 53），其中第一個星期一是第一周的第一天
%x	地區設定的日期標記法
%X	地區設定的時程表示法
%y	無世紀年份，十進位數 （00 - 99）
%Y	含世紀的年份，以十進位數字表示
%z	ISO 8601 格式的 UTC 位移;如果時區未知，則不會有任何字元
%Z	視登錄設定而定，地區設定的時區名稱或時區縮寫;如果時區未知，則不會有任何字元
%%	百分比符號

如同 printf 函式，# 旗標前面可以加上任何格式代碼。 在此情況下，格式代碼的意義會變更如下。

格式化程式碼	意義
%#a, %#A, %#b, %#B, %#g, %#G, %#h, %#n, %#p, %#t, %#u, %#w, %#X, %#z, %#Z, %#%	會忽略 # 旗標。
%#c	適用于地區設定的長日期和時程表示法。 例如：「1995 年 3 月 14 日星期二 12:41:29」。
%#x	適用于地區設定的長日期標記法。 例如：「1995 年 3 月 14 日星期二」。
%#d, %#D, %#e, %#F, %#H, %#I, %#j, %#m, %#M, %#r, %#R, %#S, %#T, %#U, %#V, %#W, %#y, %#Y	移除前置零或空格（如果有的話）。

、 %g 和 %G 所產生的 %V ISO 8601 周和以周為基礎的年份會使用從星期一開始的一周。 第 1 周是包含 1 月第四天的星期，這是第一周，至少包含一年的四天。 如果今年的第一個星期一是第 2、3 或 4 日，則前天是前一年最後一周的一部分。 這些日子會 %V 由 53 取代，而且 %g 和 %G 都會由前一年的位數取代。

注意

使用其中一個 tm 函式搭配從 gmtime 傳回的 strftime 指標時，透過 %Z 和 %z 規範列印的值將無法正確。 這是因為 tm C 標準所指定的結構不包含時區名稱或位移的資訊。 相反地，時區資訊會透過全域變數 _timezone 和 _dstbias 填入。

需求

常式	必要的標頭
strftime	<time.h>
wcsftime	<time.h> 或 <wchar.h>
_strftime_l	<time.h>
_wcsftime_l	<time.h> 或 <wchar.h>

和 _wcsftime_l 函 _strftime_l 式是 Microsoft 特有的。 如需相容性詳細資訊，請參閱相容性。

範例

請參閱 的 time 範例。

另請參閱

地區設定
時間管理
字串操作
localeconv
setlocale, _wsetlocale
strcoll 函數
strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l