GetDateFormatEx 関数 (datetimeapi.h)

[アーティクル]
08/23/2023

名前で指定されたロケールの日付文字列として日付を書式設定します。関数は、指定された日付またはローカルシステムの日付を書式設定します。

メモアプリケーションは、Windows Vista 以降でのみ実行するように設計されている場合は、GetDateFormat よりも優先してこの関数を呼び出す必要があります。

メモこの関数は、たとえばカスタムロケールのためにリリース間で変更されるデータを書式設定できます。アプリケーションでデータを永続化または送信する必要がある場合は、「永続的なロケールデータの使用」を参照してください。

構文

int GetDateFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate,
  [in, optional]  LPCWSTR          lpCalendar
);

パラメーター

[in, optional] lpLocaleName

ロケール名へのポインター、または次の定義済みの値のいずれか。

[in] dwFlags

lpFormat が NULL に設定されている場合に設定できるさまざまな関数オプションを指定するフラグ。アプリケーションでは、次の値と LOCALE_USE_CP_ACP または LOCALE_NOUSEROVERRIDEの組み合わせを指定できます。

注意ユーザー設定が無効になっているため、LOCALE_NOUSEROVERRIDEの使用は強くお勧めしません。

値	意味
DATE_AUTOLAYOUT	Windows 7 以降: ロケールとカレンダー情報を使用して右から左および左から右への読み取りレイアウトの必要性を検出し、それに応じてマークを追加します。この値は、DATE_LTRREADINGまたはDATE_RTLREADINGでは使用できません。 DATE_AUTOLAYOUTは、ロケールとカレンダーを使用してマークの正しい追加を決定するため、DATE_LTRREADINGとDATE_RTLREADINGよりも優先されます。
DATE_LONGDATE	長い日付形式を使用します。この値は、DATE_MONTHDAY、DATE_SHORTDATE、またはDATE_YEARMONTHでは使用できません。
DATE_LTRREADING	左から右への読み取りレイアウトのマークを追加します。この値は、DATE_RTLREADINGでは使用できません。
DATE_RTLREADING	右から左への読み取りレイアウトのマークを追加します。この値は、DATE_LTRREADINGで使用できません
DATE_SHORTDATE	短い日付形式を使用します。既定値です。この値は、DATE_MONTHDAY、DATE_LONGDATE、またはDATE_YEARMONTHでは使用できません。
DATE_USE_ALT_CALENDAR	日付文字列の書式を設定するには、代替カレンダー (存在する場合) を使用します。このフラグが設定されている場合、関数は、ユーザーオーバーライドを使用するのではなく、その代替カレンダーの既定の形式を使用します。ユーザーのオーバーライドは、指定した代替カレンダーの既定の形式がない場合にのみ使用されます。
DATE_YEARMONTH	Windows Vista: 年/月形式を使用します。この値は、DATE_MONTHDAY、DATE_SHORTDATE、またはDATE_LONGDATEでは使用できません。
DATE_MONTHDAY	Windows 10: 指定したロケールに適した月形式と日形式の組み合わせを使用します。この値は、DATE_YEARMONTH、DATE_SHORTDATE、またはDATE_LONGDATEでは使用できません。

アプリケーションでDATE_YEARMONTH、DATE_MONTHDAY、DATE_SHORTDATE、またはDATE_LONGDATEを指定せず、 lpFormat が NULL に設定されている場合、DATE_SHORTDATEが既定値です。

[in, optional] lpDate

書式設定する日付情報を含む SYSTEMTIME 構造体へのポインター。関数が現在のローカルシステム日付を使用する場合、アプリケーションはこのパラメーターを NULL に設定できます。

[in, optional] lpFormat

日付の形成に使用される書式指定図文字列へのポインター。書式指定図の文字列に使用できる値は、Day、Month、Year、および Era Format Pictures で定義されます。

たとえば、日付文字列 "Wed, Aug 31 94" を取得するために、アプリケーションでは画像文字列 "ddd',' MMM dd yy" を使用します。

関数は、書式指定図文字列で指定されていない情報 (ロケールの日名や月名など) に対してのみ、指定されたロケールを使用します。アプリケーションでは、このパラメーターを NULL に設定して、指定したロケールの日付形式に従って文字列を書式設定できます。

[out, optional] lpDateStr

この関数が書式設定された日付文字列を取得するバッファーへのポインター。

[in] cchDate

lpDateStr バッファーのサイズ (文字単位)。アプリケーションでは、このパラメーターを 0 に設定して、書式設定された日付文字列を保持するために必要なバッファーサイズを返すことができます。この場合、 lpDateStr で示されるバッファーは使用されません。

[in, optional] lpCalendar

予約; は NULL に設定する必要があります。

戻り値

成功した場合に lpDateStr バッファーに書き込まれた文字数を返します。 cchDate パラメーターが 0 に設定されている場合、関数は、書式設定された日付文字列を保持するために必要な文字数 (終端の null 文字を含む) を返します。

成功しなかった場合、この関数は 0 を返します。拡張エラー情報を取得するために、アプリケーションは GetLastError を呼び出すことができます。これにより、次のいずれかのエラーコードが返されます。

ERROR_INSUFFICIENT_BUFFER。指定されたバッファーサイズが十分に大きくなかったか、 正しく NULL に設定されていませんでした。
ERROR_INVALID_FLAGS。フラグに指定された値が無効でした。
ERROR_INVALID_PARAMETER。パラメーター値のいずれかが無効です。

注釈

メモこの API は、2019 年 5 月の日本の時代変更をサポートするように更新されています。アプリケーションで日本語カレンダーがサポートされている場合は、新しい時代 (年号) が適切に処理されていることを検証する必要があります。詳細については、「日本の時代 (年号) の変更に合わせてアプリケーションを準備する」を参照してください。

この関数でサポートされている最も古い日付は、1601 年 1 月 1 日です。

曜日名、省略された日名、月名、および省略された月名はすべて、ロケール識別子に基づいてローカライズされます。

lpDate で示される構造体の日付値は有効である必要があります。関数は、年、月、日、曜日の各日付値をチェックします。曜日が正しくない場合、関数は正しい値を使用し、エラーを返しません。他の日付値のいずれかが正しい範囲外の場合、関数は失敗し、最後のエラーをERROR_INVALID_PARAMETERに設定します。

この関数は、lpDate で示される SYSTEMTIME 構造体の時間メンバーを無視します。これには、 wHour、 wMinute、 wSecond、 および wMilliseconds が含まれます。

lpFormat パラメーターに不適切な書式指定文字列が含まれている場合、関数はエラーを返しませんが、可能な限り最適な日付文字列を形成します。たとえば、有効な年の図は L"yyyy" と L"yy" のみです。ここで、"L" は Unicode (16 ビット文字) 文字列を示します。 L"y" が渡された場合、関数は L"yy" と見なされます。 L"yyy" が渡された場合、関数は L"yyyy" と見なします。 4 つ以上の日付 (L"dddd") または 4 か月 (L"MMMM") の画像が渡される場合、関数の既定値は L"dddd" または L"MMMM" になります。

アプリケーションは、日付書式図の単一引用符で囲んで、日付文字列内の正確な形式に残るテキストを囲む必要があります。単一引用符をエスケープ文字として使用して、単一引用符自体を日付文字列に表示することもできます。ただし、エスケープシーケンスは 2 つの単一引用符で囲む必要があります。たとえば、日付を "May '93" として表示する場合、書式指定文字列は L"MMMM '''yy" です。最初と最後の単一引用符は、外側の引用符です。 2 番目と 3 番目の単一引用符は、世紀の前に単一引用符を表示できるようにするためのエスケープシーケンスです。

日付図に日付の数値形式 (d または dd) と完全な月名 (MMMM) の両方が含まれている場合、月名の生成形式が日付文字列で取得されます。

実際の書式を実行せずに既定の短い日付形式と長い日付形式を取得するには、アプリケーションで GetLocaleInfoEx を LOCALE_SSHORTDATEまたはLOCALE_SLONGDATE 定数と共に使用する必要があります。別の予定表の日付形式を取得するために、アプリケーションでは GetLocaleInfoEx と LOCALE_IOPTIONALCALENDAR 定数を使用します。特定の予定表の日付形式を取得するために、アプリケーションは GetCalendarInfoEx を使用し、適切な予定表識別子を渡します。 EnumCalendarInfoEx または EnumDateFormatsEx を呼び出して、特定の予定表の日付形式を取得できます。

この関数は、カスタムロケールからデータを取得できます。データは、コンピューター間、またはアプリケーションの実行間で同じになることは保証されません。アプリケーションでデータを永続化または送信する必要がある場合は、「永続的なロケールデータの使用」を参照してください。

DATE_LONGDATE形式には、曜日を含むパターンと曜日を含まないパターンという 2 種類の日付パターンが含まれます。たとえば、"2016 年 10 月 18 日火曜日" や "2016 年 10 月 18 日" などです。アプリケーションで、他の種類ではなく、これらの種類のパターンの 1 つを日付で使用する必要がある場合は、アプリケーションで次のアクションを実行する必要があります。

EnumDateFormatsExEx 関数を呼び出して、DATE_LONGDATE形式のすべての日付形式を取得します。
EnumDateFormatsExEx に指定したコールバック関数に渡される最初の日付形式を探します。この形式は、要求された予定表識別子と一致し、アプリケーションの要件に一致する日付書式指定文字列を持ちます。たとえば、アプリケーションで日付に曜日のフルネームが含まれている必要がある場合は、"dddd" を含む最初の日付形式を探します。また、アプリケーションで日付に省略名と曜日の完全名を含める必要がある場合は、"ddd" も "dddd" も含む最初の日付形式を探します。
lpFormat パラメーターをコールバック関数の適切な形式として識別した日付書式指定文字列に設定して、GetDateFormatEx 関数を呼び出します。

長い日付形式の曜日の有無がアプリケーションにとって重要でない場合、アプリケーションは EnumDateFormatsExEx を呼び出すことによって、最初にすべての長い日付形式を列挙せずに GetDateFormatEx を直接呼び出すことができます。

Windows 8以降: アプリが Windows.Globalization 名前空間からこの関数に言語タグを渡す場合は、最初に ResolveLocaleName を呼び出してタグを変換する必要があります。

Windows 8以降: GetDateFormatEx は Datetimeapi.h で宣言されています。 Windows 8する前は、Winnls.h で宣言されていました。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	datetimeapi.h
Library	Kernel32.lib
[DLL]	Kernel32.dll

次の方法で共有

GetDateFormatEx 関数 (datetimeapi.h)

構文

パラメーター

戻り値

注釈

要件

関連項目

フィードバック

その他のリソース