Notes C API探訪: TIME(データ型)

TIME型は、前回のTIMEDATE型でも紹介しました。以下に定義を再掲しておきます。

#include <misc.h>
typedef struct {
	int year;					/* 1-32767 */
	int month;					/* 1-12 */
	int day;					/* 1-31 */
	int weekday;				/* 1-7, Sunday is 1 */
	int hour;					/* 0-23 */
	int minute;					/* 0-59 */
	int second;					/* 0-59 */
	int hundredth;				/* 0-99 */
	int dst;					/* FALSE or TRUE */
	int zone;					/* Typically -12 to +12, but can include minutes. If this is the  */
								/* case, the two digit minutes are first, followed by the hour.   */
								/* E.g., GMT-04:30 would be 3004, while GMT+05:30 would be -3005. */
	TIMEDATE GM;
} TIME;

TIME型の用途としては、先の記事でも紹介した、TIMEDATE型の日時要素をエキスポートしたり、インポートしたりして日時データを活用することにありました。今回はもう1つ、指定した日時を他のタイムゾーン時間に変換する機能を紹介します。

TimeGMToLocalZone関数

BOOL LNPUBLIC TimeGMToLocalZone (TIME far *Time);

TimeGMToLocalZone関数は、TIMEデータを受け取り、メンバ変数GM内の日時を、メンバ変数zoneとdstに基づいて、残りのメンバ変数に日時要素を割り当てます。例えば、日本時間で7月6日午前7時台のデータを、ニューヨークの現地時間にしたい場合、次のようにします。

TIME time;
// time.GM <= 2021/7/6 7:23:00 JST(UTC+09:00)
time.zone = 5; // 米国東部の標準時差-5時間を正負逆に設定
time.dst = 1; // 米国東部は夏時間なので1
if (TimeGMToLocalZone(&time) != 0) { return; /* ERROR */ }
// time.day = 5;
// time.hour = 18;
// time.minute = 23;

このように、変換すると前日の18時台の時間として算出されます。

時差変換

このとき、TIME型のメンバ変数GMには元の日本時間データが残っています。なので、このままTimeLocalToGM関数にかけると、ニューヨーク時間に変換されたTIMEDATE型のデータとして取得できます。

if (TimeLocalToGM(&time) != 0) { return; /* ERROR */ }
// time.GM = 2021/7/5 18:23:00 EDT(UTC-04:00)

メンバ変数zone

なお、TIME型のメンバ変数zoneは、通常-12〜+12(+12:00〜-12:00)の値を取りますが、時差に分単位指定が必要な地域では、4桁の数値が返ってきます。時差に「30分差」が含まれる場合、30分が上位2桁、時間が下位2桁で表現されます。例えばイランの標準時は+3.5時間ですが、その場合zoneは「-3003」となります。分単位の時差を持つ主な地域とzoneの値を一覧します。

・テヘラン -3003 (UTC+03:30)
・カブール -3004 (UTC+04:30)
・デリー -3005 (UTC+05:30)
・カトマンズ -4505 (UTC+05:45)
・ヤンゴン -3006 (UTC+06:30)
・アデレード -3009 (UTC+09:30)
・ユークラ -4508 (UTC+08:45)
・カラカス +3004 (UTC-04:30)
・ニューファンドランド +3003 (UTC-03:30)

ユークラというオーストラリアの地域は日本より15分だけ時差がある・・・って、マジか。

まとめ

そんなわけで、TIME型を通して時差計算を見てきました。注意したいのは、以下の3点です。

1. 関数の戻り値は0が成功、1が失敗
2. 一般的に標準時でプラスの地域はマイナス値、マイナス地域はプラス値になる
3. 分単位の時差がある地域は、zone値は上位2桁が分、下位2桁が時になる

注意: コードの利用においてチブル・システムズは一切の責任を負いません。自己責任でご利用をお願いいたします。