|
パラメータ
Locale
日付の書式化に使うべきロケールを指定する。
lpFormat パラメータで NULL を指定した場合、この関数はこのロケールに対応する日付フォーマットに従って、日付文字列を作成する。
lpFormat パラメータで NULL 以外の値を指定した場合、lpFormat パラメータの書式制御文字列で指定されていない情報に関しての
み、ロケールの情報を利用する（たとえば、ロケールの曜日名や月名）。
MAKELCID マクロを使って作成したロケール識別子、またはあらかじめ定義されている次の値のいずれかを指定する。
|
値
|
意味
|
|
LOCALE_SYSTEM_DEFAULT |
システムの既定のロケール |
|
LOCALE_USER_DEFAULT |
現在のユーザーの既定のロケール |
dwFlags
関数のさまざまなオプションを指定する。
lpFormat パラメータで NULL 以外の値を指定した場合、dwFlags パラメータで 0 を指定しなければならない。
lpFormat パラメータで NULL を指定した場合、次のフラグを組み合わせて指定する。
|
値
|
意味
|
|
LOCALE_NOUSEROVERRIDE |
指定したロケールに対応する、システムの既定の日付フォーマットに従って、日付文字列をフォーマット |
|
|
する。このフラグを指定しなかった場合、この関数はユーザーが指定したすべての書式制御文字列 |
|
|
を使って、指定されたロケールの既定の日付フォーマットを作成する。 |
|
LOCALE_USE_CP_ACP |
文字の書式化を行う際に、指定されたロケールのコードページではなく、システムの ANSI コードペー |
|
|
ジを使う。 |
|
DATE_SHORTDATE |
短い日付フォーマットを使う。このフラグは既定の値である。DATE_LONGDATE または |
|
|
DATE_YEARMONTH とは同時に指定できない。 |
|
DATE_LONGDATE |
長い日付フォーマットを使う。DATE_SHORTDATE または DATE_YEARMONTH とは同時に指定 |
|
|
できない。 |
|
DATE_YEARMONTH |
月/年のフォーマットを使う。DATE_SHORTDATE または DATE_LONGDATE とは同時に指定でき |
|
|
ない。 |
|
DATE_USE_ALT_CALENDAR |
代替カレンダーが存在する場合、そのカレンダーを使って、日付文字列を作成する。このフラグを指 |
|
|
定した場合、この関数は、ユーザーが指定した書式制御文字列ではなく代替カレンダーの既定の書 |
|
|
式を使う。指定された代替カレンダーに既定の書式がない場合に限って、ユーザーが指定した書式制 |
|
|
御文字列を使う。 |
|
DATE_LTRREADING |
左から右へ向かって表示することを指示するマークを追加する。DATE_RTLREADING とは同時に指 |
|
|
定できない。 |
|
DATE_RTLREADING |
右から右へ向かって表示することを指示するマークを追加する。DATE_LTRREADING とは同時に指 |
|
|
定できない。 |
このパラメータで、DATE_YEARMONTH、DATE_SHORTDATE、DATE_LONGDATE
のいずれも指定せず、lpFormat パラメータで
NULL を指定した場合は、DATE_SHORTDATE が既定として使われる。
lpDate
書式化するべき日付情報を保持している、1 個の
SYSTEMTIME 構造体へのポインタを指定する。NULL
を指定すると、この関数は、
現時点でのローカルのシステム日付を使う。
lpFormat
日付文字列の作成に使うべき書式制御文字列へのポインタを指定する。
NULL を指定すると、この関数は、指定したロケールに対応する日付フォーマットを使う。
書式制御文字列は、次の要素を組み合わせて構築する。制御文字列の中で半角スペースを使って複数の要素を区切った場合、それら
の半角スペースは、出力文字列の中で同じ場所に表示される。各要素は、表で示したのと同じ形式で大文字と小文字を表記しなければ
ならない（たとえば、表に "MM" と記載されている場合、"mm" とは入力できない）。制御文字列内で特定の文字を引用符（'）で囲む
と、その文字は出力文字列にそのまま表示される。
|
制御文字
|
意味
|
|
d |
年月日の日。1 桁の場合でも、先頭に 0 は付かない。 |
|
dd |
年月日の日。 1 桁の場合、先頭に 0 が付く。 |
|
ddd |
英語環境などでは、曜日の 3 文字の略称。日本語環境では (日)、(月) などになる。指定されたロケールに対応する |
|
|
LOCALE_SABBREVDAYNAME が使われる。 |
|
dddd |
英語環境などでは、曜日の完全な名前。日本語環境では (日曜日)、(月曜日) などになる。指定されたロケールに対応する
|
|
|
LOCALE_SDAYNAME が使われる。 |
|
M |
月を表す数字。1 桁の場合でも、先頭に 0 は付かない。 |
|
MM |
月を表す数字。1 桁の場合、先頭に 0 が付く。 |
|
MMM |
英語環境などでは、月名の 3 文字の略称。日本語環境では、1 月、2 月などになる。指定されたロケールに対応する |
|
|
LOCALE_SABBREVMONTHNAME が使われる。 |
|
MMMM |
英語環境などでは、月名の完全な名前が返る。日本語環境では、1 月、2 月などになる。指定されたロケールに対応する |
|
|
LOCALE_SMONTHNAME が使われる。 |
|
y |
西暦の年の下 2 桁が返る。1 桁の場合でも、先頭に 0 は付かない。 |
|
yy |
西暦の年の下 2 桁が返る。1 桁の場合、先頭に 0 が付く。 |
|
yyyy |
西暦の年が 4 桁で返る。 |
|
gg |
王朝や元号を表す文字列。日本語環境では、「昭和」、「平成」などの元号が返る。指定されたロケールに対応する |
|
|
CAL_SERASTRING が使われる。 |
|
|
書式化対象の日付に王朝や元号などの情報が記録されていない場合、gg は無視される。 |
たとえば、英語と日本語それぞれの環境で次の文字列を取得するには、
"Wed, Aug 31 94" 1994 年 8 月 31 日 (水曜日)
それぞれ次の制御文字列を指定する。
"ddd',' MMM dd yy" "yyyy' 年 'M' 月 'd' 日 ('dddd')'"
lpDateStr
1 個のバッファへのポインタを指定する。関数から制御が返ると、このバッファに、書式化された日付文字列が格納される。
cchDate
lpDateStr バッファのサイズを TCHAR 単位で指定する。
0 を指定すると、この関数は、書式化された日付文字列を格納するために必要なバイト数または文字数を返す。
このとき、lpDateStr バッファは使用されない。
戻り値
関数が成功すると、lpDateStr バッファに格納された文字列の長さが TCHAR 単位で返る。
ただし、cchDate パラメータで 0 を指定した場合、書式化された日付文字列を格納するために必要なバイト数または文字数が返る。
この長さには、最後の NULL が含まれている。
関数が失敗すると、0 が返る。拡張エラー情報を取得するには、GetLastError 関数を使う。GetLastError
は、次のエラーコードのいず
れかを返すことがある。
ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER
解説
この関数で指定できる最古の日付は、西暦 1600 年 1 月 1 日である。
曜日の完全な名前、曜日の略称、月の完全な名前、月の略称は、いずれもロケールの識別子に基づいてローカライズされる。
lpDate パラメータが指す SYSTEMTIME 構造体の中の日付は、有効な値でなければならない。
この関数は、日付の各値、つまり年、月、日、曜日をチェックする。曜日の指定が間違っている場合、この関数は年月日に基づいて
正しい曜日を使い、エラーを返さない。日付の他の値が適切な範囲に収まっていない場合、この関数は失敗し、GetLastError 関数は
ERROR_INVALID_PARAMETER を返すようになる。 |