strftime、wcsftime、_strftime_l、_wcsftime_l

[アーティクル]
08/09/2011

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

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 より前に、のバージョンでは、ドキュメントの説明、formatパラメーターのwcsftimeのデータ型を持つconst wchar_t *の実際の実装は、format型であったconst char *。実装は、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 にコピーされます。LC_TIMEの現在のロケールのカテゴリに影響を与えるの出力書式strftime。（詳細についてLC_TIMEを参照してくださいsetlocale.)_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	現在のロケールに対応する、日付と時刻の長い表現。次に例を示します「1995 年 3 月 14日日火曜日 12」。
%#x	現在のロケールに対応する、日付の長い表現。次に例を示します「火曜日、3 月 14日日 1995」。
%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y	先行ゼロがあれば削除されます。