GetTimeFormat

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 GetTimeFormat(
  LCID Locale,              // ロケール
  DWORD dwFlags,            // オプション
  CONST SYSTEMTIME *lpTime, // 時刻
  LPCTSTR lpFormat,         // 時刻の書式を指定する文字列
  LPTSTR lpTimeStr,         // 書式化済みの文字列を受け取るバッファ
  int cchTime               // 文字列バッファのサイズ
);

パラメータ

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

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

意味
LOCALE_SYSTEM_DEFAULTシステムの既定のロケール
LOCALE_USER_DEFAULT現在のユーザーの既定のロケール

dwFlags
関数のさまざまなオプションを指定します。次のフラグを組み合わせて指定します。
意味
LOCALE_NOUSEROVERRIDE指定したロケールに対応する、システムの既定の時刻フォーマットに従って、時刻文字列をフォーマットします。このフラグを指定しなかった場合、この関数はユーザーが指定したすべての書式制御文字列を使って、指定されたロケールの既定の時刻フォーマットを作成します。このフラグを指定できるのは、lpFormat パラメータで NULL を指定した場合のみです。
LOCALE_USE_CP_ACP文字の書式化を行う際に、指定されたロケールのコードページではなく、システムの ANSI コードページを使います。
TIME_NOMINUTESORSECONDS分と秒を使いません。
TIME_NOSECONDS秒を使いません。
TIME_NOTIMEMARKER時刻マーカーを使いません。
TIME_FORCE24HOURFORMAT必ず 24 時間制で表記します。

lpTime
書式化するべき時刻情報を保持している、1 個の 構造体へのポインタを指定します。NULL を指定すると、この関数は、現時点でのローカルのシステム時刻を使います。
lpFormat
時刻文字列の作成に使うべき書式制御文字列へのポインタを指定します。NULL を指定すると、この関数は、指定したロケールに対応する時刻フォーマットを使います。

書式制御文字列は、次の要素を組み合わせて構築します。制御文字列の中で半角スペースを使って複数の要素を区切った場合、それらの半角スペースは、出力文字列の中で同じ場所に表示されます。各要素は、表で示したのと同じ形式で大文字と小文字を表記しなければなりません(たとえば、表に "ss" と記載されている場合、"SS" とは入力できません)。制御文字列内で特定の文字を引用符(')で囲むと、その文字は出力文字列にそのまま表示されます。

Picture 制御文字意味
h12 時間制の時間。1 桁の場合でも、先頭に 0 は付きません。
hh12 時間制の時間。1 桁の場合、先頭に 0 が付きます。
H24 時間制の時間。1 桁の場合でも、先頭に 0 は付きません。
HH24 時間制の時間。1 桁の場合、先頭に 0 が付きます。
m分。1 桁の場合でも、先頭に 0 は付きません。
mm分。1 桁の場合、先頭に 0 が付きます。
s秒。1 桁の場合でも、先頭に 0 は付きません。
ss秒。1 桁の場合、先頭に 0 が付きます。
t1 文字の時刻マーカー。「A」「P」など。
tt複数文字の時刻マーカー。「AM」「PM」「午前」「午後」など。

たとえば、次の文字列を取得するには、

"11:29:40 PM"

次の制御文字列を指定します。

"hh':'mm':'ss tt"

lpTimeStr
1 個のバッファへのポインタを指定します。関数から制御が返ると、このバッファに、書式化された時刻文字列が格納されます。
cchTime
lpTimeStr バッファのサイズを、TCHAR 単位で指定します。0 を指定すると、この関数は、書式化された時刻文字列を格納するために必要なバッファのバイト数または文字数を返します。このとき、lpTimeStr バッファは使用されません。

戻り値

関数が成功すると、lpTimeStr バッファに格納された文字列の長さが TCHAR 単位で返ります。ただし、cchTime パラメータで 0 を指定した場合、書式化された時刻文字列を格納するために必要なバイト数または文字数が返ります。この長さには、最後の NULL が含まれています。

関数が失敗すると、0 が返ります。拡張エラー情報を取得するには、 関数を使います。GetLastError は、次のエラーコードのいずれかを返すことがあります。

•ERROR_INSUFFICIENT_BUFFER

•ERROR_INVALID_FLAGS

•ERROR_INVALID_PARAMETER

解説

時刻マーカーが存在し、TIME_NOTIMEMARKER フラグが指定されていない場合、この関数は指定されたロケール識別子に基づいて、時刻マーカーをローカライズします。たとえば、US English では時刻マーカーは "AM" と "PM"、日本語では「午前」と「午後」です。

lpTime パラメータが指す 構造体の中の時刻は、有効な値でなければなりません。この関数は、時刻の各値をチェックし、適切な範囲に収まっているかどうかを判断します。いずれかの値が適切な範囲に収まっていない場合、この関数は失敗し、GetLastError 関数は ERROR_INVALID_PARAMETER を返すようになります。

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

TIME_NOMINUTESORSECONDS または TIME_NOSECONDS を指定した場合、この関数は、分の直前の区切り記号以降、または秒の直前の区切り記号以降のすべての文字を削除します。

TIME_NOTIMEMARKER を指定すると、この関数は、時刻マーカーとその直前や直後の区切り記号を削除します。

TIME_FORCE24HOURFORMAT を指定した場合、ほかに TIME_NOTIMEMARKER フラグが指定されていない限り、この関数は時刻マーカーを表示します。

この関数は、書式化された時刻文字列にミリ秒(ms)を含めません。

LOCALE_NOUSEROVERRIDE を指定した場合、lpFormat パラメータで NULL を指定しなければなりません。

lpFormat パラメータで誤った制御文字列を指定した場合、エラーは返りません。この関数は単純に、可能な中で最善と思われる時刻文字列を作成します。時間、分、秒、時刻のそれぞれを表す制御文字が 2 文字より長い場合、この関数は既定の長さである 2 を想定します。たとえば、時刻マーカーを表すための有効な制御文字列は、L"t" と L"tt" だけです(ここで、'L' は Unicode 文字列;2 バイト文字の文字列を意味します)。lpFormat パラメータで L'ttt' という制御文字列を指定すると、この関数は L"tt" を想定します。

実際に書式化を行うことなく、時刻書式を取得するには、GetLocaleInfo 関数の LCType パラメータで、LOCALE_STIMEFORMAT の値を指定します。

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

地球の自転周期に基づく時間系には変動があるため、セシウム原子の周期に基づく時間系(原子時計)に合わせてときどき調整が加えられることがあります。たとえば、1997 年 7 月 1 日、午前 9 時 0 分 0 秒(日本時間)の直前に、うるう秒が挿入されました。通常は、59 秒の次が 00 秒になりますが、この場合は 59 秒の次が 60 秒(うるう秒)になり、その次が 00 秒になります。1996 年 1 月 1 日も同様でした。この関数は、SYSTEMTIME 構造体の日付メンバを無視するので、うるう秒をサポートしていません。1997 年 7 月 1 日、午前 8 時 59 分 60 秒を指定してもエラーになることに注意してください。

対応情報

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

参照

GetDateFormat, GetLocaleInfo,

表示: