GetDateFormatEx 関数 (datetimeapi.h)

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

構文

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

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

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[in] dwFlags

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

アプリケーションで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。 パラメーター値のいずれかが無効です。

注釈

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

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 つを日付で使用する必要がある場合は、アプリケーションで次のアクションを実行する必要があります。

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

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

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

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

要件

関連項目

日、月、年、および時代 (年) 形式の画像

EnumDateFormatsExEx

GetCalendarInfoEx

GetDateFormat

NLS: 名前ベースの API サンプル

各国語サポート

各国語サポート関数