strftime、wcsftime、_strftime_l、_wcsftime_l

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

時刻文字列の書式を指定します。

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 バッファのサイズ。
format
書式指定文字列。
timeptr
tm データ構造。
locale
使用するロケール。

戻り値

strftime 関数は strDest の文字数を返し、wcsftime 関数は対応するワイド文字数を返します。

終端の null を含む合計文字数が maxsize を超える場合、strftime 関数と wcsftime 関数は 0 を返し、strDest の内容は不定になります。

strDest の文字数は、format のリテラル文字数に、書式指定コードで format に追加される文字数を加えた数になります。文字列の終端の NULL 文字は、戻り値には含まれません。

解説

strftime と wcsftime 関数は、提供されている format 引数に基づいて timeptr の tm 時間値を書式指定し、結果を strDest バッファに保存します。文字列の最大文字数は、maxsize で指定する数になります。timeptr 構造体のフィールドの詳細については、「asctime」を参照してください。wcsftime 関数は strftime 関数のワイド文字バージョンで、文字列ポインタ引数はワイド文字列を指します。それ以外では、これらの関数の動作は同じです。

メモ :
Visual C++ 2005 以前のバージョンの説明では、wcsftime の format パラメータのデータ型は const wchar_t * になっていましたが、実際の format データ型の実装は const char * でした。Visual C++ 2005 では、format データ型の実装は、ドキュメントを反映して const wchar_t * に更新されています。

この関数は、パラメータを検証します。strDest、format、または timeptr が null ポインタの場合、timeptr によってアドレス指定された tm データ構造が無効の場合 (範囲外の時刻または日付の値が含まれるなど)、または format 文字列に無効な書式指定コードが含まれている場合、「パラメータの検証」に説明されているように、無効なパラメータハンドラが呼び出されます。実行の継続が許可された場合、この関数は 0 を返し、errno を EINVAL に設定します。

汎用テキストルーチンのマップ

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_tcsftime	strftime	strftime	wcsftime

format 引数は、printf 関数と同様に 1 つ以上のコードで構成され、書式指定コードの先頭にはパーセント記号 (%) が付きます。% が先頭に付かない文字は、そのまま strDest にコピーされます。strftime 関数の出力書式には、現在のロケールの LC_TIME カテゴリが影響します。LC_TIME カテゴリの詳細については、「setlocale、_wsetlocale」を参照してください。_l サフィックスが付いていない関数は、現在設定されているロケールを使用します。_l サフィックスが付けられたバージョンは、現在設定されているロケールの代わりにパラメータとして渡されたロケールを使用する点を除いて同じです。詳細については、「ロケール」を参照してください。

strftime 関数の書式指定コードを次に示します。

%a
曜日の省略形。
%A
曜日の正式名。
%b
月の省略形。
%B
月の正式名。
%c
ロケールに対応する日付と時刻の表現。
%d
10 進数で表す月の日付 (01 ～ 31)。
%H
24 時間表記の時間 (00 ～ 23)。
%I
12 時間表記の時間 (01 ～ 12)。
%j
10 進数で表す年初からの日数 (001 ～ 366)。
%m
10 進数で表す月 (01 ～ 12)。
%M
10 進数で表す分 (00 ～ 59)。
%p
現在のロケールの午前/午後。
%S
10 進数で表す秒 (00 ～ 59)。
%U
10 進数で表す週の通し番号。日曜日を週の最初の日とする (00 ～ 53)。
%w
10 進数で表す曜日 (0 ～ 6、日曜日が 0)。
%W
10 進数で表す週の通し番号。月曜日を週の最初の日とする (00 ～ 53)。
%x
現在のロケールの日付表現。
%X
現在のロケールの時刻表現。
%y
10 進数で表す西暦の下 2 桁 (00 ～ 99)。
%Y
10 進数で表す 4 桁の西暦。
%z, %Z
レジストリの設定に応じて、タイムゾーンの名前または省略形を指定します。タイムゾーンが不明な場合は指定しません。
%%
パーセント記号。

printf 関数と同様に、書式指定コードの前に # フラグを付けることができます。その場合、書式指定コードの意味は次のように変更されます。

書式指定コード	説明
%#a, %#A, %#b, %#B, %#p, %#X, %#z, %#Z, %#%	# フラグは無視されます。
%#c	現在のロケールに対応する、日付と時刻の長い表現。たとえば、"Tuesday, March 14, 1995, 12:41:29" となります。
%#x	現在のロケールに対応する、日付の長い表現。たとえば、"Tuesday, March 14, 1995" となります。
%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y	先行ゼロがあれば削除されます。