GetDateFormat

https://msdn.microsoft.com/ja-jp/library/ms776310.aspx https://msdn.microsoft.com/ja-jp/library/ms724950.aspx https://msdn.microsoft.com/ja-jp/library/cc428944.aspx https://msdn.microsoft.com/ja-jp/library/ms724950.aspx https://msdn.microsoft.com/ja-jp/library/ms776324.aspx https://msdn.microsoft.com/ja-jp/library/ms724950.aspx

日付を書式化して、指定されたローケルに対応する日付文字列を作成します。この関数は、指定された日付、またはローカルのシステム日付を書式化します。

int GetDateFormat(
  LCID Locale,               // ロケール
  DWORD dwFlags,             // オプション
  CONST SYSTEMTIME *lpDate,  // 日付
  LPCTSTR lpFormat,          // 日付の書式
  LPTSTR lpDateStr,          // 書式化済みの文字列を受け取るバッファ
  int cchDate                // バッファのサイズ
);

パラメータ

Locale
日付の書式化に使うべきロケールを指定します。lpFormat パラメータで NULL を指定した場合、この関数はこのロケールに対応する日付フォーマットに従って、日付文字列を作成します。lpFormat パラメータで NULL 以外の値を指定した場合、lpFormat パラメータの書式制御文字列で指定されていない情報に関してのみ、ロケールの情報を利用します(たとえば、ロケールの曜日名や月名)。

マクロを使って作成したロケール識別子、またはあらかじめ定義されている次の値のいずれかを指定します。

意味
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 個の 構造体へのポインタを指定します。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 は、次のエラーコードのいずれかを返すことがあります。

•ERROR_INSUFFICIENT_BUFFER

•ERROR_INVALID_FLAGS

•ERROR_INVALID_PARAMETER

解説

この関数で指定できる最古の日付は、西暦 1600 年 1 月 1 日です。

曜日の完全な名前、曜日の略称、月の完全な名前、月の略称は、いずれもロケールの識別子に基づいてローカライズされます。

lpDate パラメータが指す 構造体の中の日付は、有効な値でなければなりません。この関数は、日付の各値、つまり年、月、日、曜日をチェックします。曜日の指定が間違っている場合、この関数は年月日に基づいて正しい曜日を使い、エラーを返しません。日付の他の値が適切な範囲に収まっていない場合、この関数は失敗し、GetLastError 関数は ERROR_INVALID_PARAMETER を返すようになります。

この関数は、lpDate パラメータが指す SYSTEMTIME 構造体の日付メンバ、つまり wHourwMinutewSecondwMilliseconds を無視します。

lpFormat パラメータで誤った制御文字列を指定した場合、エラーは返りません。この関数は単純に、可能な中で最善と思われる日付文字列を作成します。たとえば、年を表すための有効な制御文字列は、L"yyyy" と L"yy" だけです(ここで、'L' は Unicode 文字列;2 バイト文字の文字列を意味します)。lpFormat パラメータで L'y' という制御文字列を指定すると、この関数は L"yy" を想定します。同様に、L"yyy" を指定すると、この関数は L"yyyy" を想定します。日を表す有効な制御文字列は L"dddd" だけ、月を表す有効な制御文字列は L"MMMM" だけですが、4 桁より長い制御文字列を指定すると、この関数は既定の L"dddd" または L"MMMM" を想定します。

書式化された日付文字列の中に、特定の文字をそのままの形で残す必要がある場合、日付制御文字列の中でその文字を引用符(')で囲んで記述してください。書式化後の日付文字列の中で引用符そのものを表示する場合は、引用符を 2 回('')入力してください。その上、その 2 つの引用符の前後をさらに引用符で囲む必要があります。たとえば、書式化された文字列で "May '93" という表記を得るには、L"MMMM ''''yy" という日付制御文字列を指定します。ここで、4 つの引用符が連続していますが、最初と最後の引用符は、特定の文字を囲む役割を果たします。2 番目と 3 番目の引用符は、1 つの引用符へ変換され、西暦の年を 2 桁で表示する場合の省略記号を意味します。

日付制御文字列で、月の完全な名前(MMMM)の後に、日の数値表示(d または dd)を指定すると、書式化された日付文字列の中には、月名の属格形(genitive form)が格納されます。この概念はロシア語やポーランド語に固有のもので、日/月と表記する場合と、月/日と表記する場合とで、月の表記が変化することを意味します。属格形とは後者を意味します。たとえば、ロシア語の 1 月は、前者はянваръ(yanvar;ъは子音の音価を表すだけで、アクセント記号に近い役割なので、翻字の対象になりません)、後者はянваря(yanvarya)です。ロシア語の月名はラテン語に由来しているので、これは英語の January(ヤヌスの月)に比較的似ています。

実際に書式化を行うことなく、既定の短い日付書式と既定の長い日付書式を取得するには、GetLocaleInfo 関数の LCType パラメータで、LOCALE_SSHORTDATE または LOCALE_SLONGDATE の値を指定します。代替カレンダーの日付の書式を取得するには GetLocaleInfo 関数の LCType パラメータで、LOCALE_IOPTIONALCALENDAR の値を指定します。特定のカレンダーの日付書式を取得するには、GetCalendarInfo 関数を使います。さらに、特定のカレンダーで利用できるすべての日付書式を取得するには、EnumCalendarInfo または EnumDateFormatsEx 関数を使います。

Windows 2000:Unicode 専用の LCID(ロケール識別子)を指定した場合、この関数の ANSI 版は失敗します。詳細については、MSDN ライブラリの「」を参照してください。

日本は江戸時代まで太陰太陽暦を使っていて、太陽暦を採用したのは明治 6 年 1 月 1 日(西暦 1873 年 1 月 1 日)でした。その前日は明治 5 年 12 月 2 日(西暦 1872 年 12 月 31 日)でした。太陰太陽暦とは、太陰暦の 1 か月(28 日または 29 日)を 1 年につき 12 回設けることを基本とし、太陽暦の 1 年の長さ 365.2425 日に合わせて、うるう月(日本では 6 月の後に閏 6 月)を適宜追加するものです。このような事情から、西暦 1872 年以前の日付を元号表記へ変換するのはそれほど簡単なことではなく、代替カレンダーを用意する必要があります。ユダヤ暦やイスラムのヒジュラ(hijrah または hegira)も類似の状況です。どうしてもこのような変換を行う必要がある場合、Web サイトで " 太陰暦 "、" 和暦 "、" 天文方 " などのキーワードを指定して検索をするか、適切な文献を参照してください。

対応情報

Windows NT/2000:Windows NT 3.5 以降
Windows 95/98:Windows 95 以降
ヘッダー:Winnls.h 内で宣言、Windows.h をインクルード
インポートライブラリ:Kernel32.lib を使用
Unicode:Windows NT/2000 は Unicode 版と ANSI 版を実装

参照

EnumCalendarInfo, EnumDateFormatsEx, GetCalendarInfo, GetLocaleInfo, GetTimeFormat,

表示: