【MQL5】TimeToStruct関数について

TimeToStruct関数の働き・役割
TimeToStruct関数の引数について
TimeToStruct関数の戻り値について
TimeToStruct関数を使う際の注意点
TimeToStruct関数を使ったサンプルコード

TimeToStruct関数の働き・役割

TimeToStruct関数は、特定の日時を表すdatetime型の値をより詳細な成分に分解する役割を持っています。

具体的には、年、月、日、時間、分、秒などの個別の日時情報を取り出し、MqlDateTime構造体型のインスタンスに格納する事ができるようになります。

※構造体についての詳細は↓の記事をご参照ください

※MqlDateTime構造体についての詳細は↓の記事をご参照ください

※インスタンスについての詳細は↓の記事をご参照ください

【広告↓】

TimeToStruct関数の引数について

TimeToStruct関数は二つの引数を取ります。

bool  TimeToStruct(
  datetime      dt,            // 日付と時刻
  MqlDateTime&  dt_struct      // 値を採用するための構造体
  );

一つ目の引数dtは変換したいdatetime型値です。

これは通常、1970年1月1日からの秒数で表されるUNIXタイムの整数値です。

※UNIXタイムについての詳細は↓の記事をご参照ください

二つ目の引数dt_structは、結果を格納するためのMqlDateTime構造体型のインスタンスです。

第1引数で指定されたdatetime型の値が、MqlDateTime構造体型の情報に分解・変換されて、参照渡しにて格納されます。

※参照渡しについての詳細は↓の記事をご参照ください

TimeToStruct関数の戻り値について

TimeToStruct関数は、操作の成功を表すbool型の値（trueまたはfalse）を戻り値として返します。

もし変換が成功した場合、第２引数には分解された日時情報がMqlDateTime構造体の各メンバに格納されます。

失敗した場合は、falseが返されます。

エラー情報はGetLastError関数で取得することができます。

TimeToStruct関数を使う際の注意点

TimeToStruct関数を使用する際の注意点は以下の通りです。

第1引数には正しいdateTime値を渡す必要があります。無効な日時を渡すと、TimeToStruct関数はfalseを返し、エラーを生成します。
第2引数に記述するMqlDateTime構造体「dt_struct」は正しく初期化されている必要があります。不適切な初期化は誤った結果やエラーを招く可能性があります。
タイムゾーンの違いを考慮する必要があります。TimeToStruct関数はタイムゾーンの変換を行わないため、サーバー時間とローカル時間の違いを自分で処理する必要があります。

※地球を24の区域に分け、それぞれの区域で同じ時間が使われるようにした、いわば「時間の世界地図」のようなものです。タイムゾーンの詳細については↓の記事をご参照ください

TimeToStruct関数を使ったサンプルコード

以下はTimeToStruct関数を使ったサンプルコードです。

void OnStart() 
{
  // 'TimeCurrent()' 関数を使用して現在のサーバー時間を取得
  datetime current_time = TimeCurrent(); 

  // 'MqlDateTime' 構造体の変数を宣言
  MqlDateTime mt_time;

  // 'TimeToStruct()' 関数を使用して 'datetime' 型の 'current_time' を
  // 'MqlDateTime' 型の 'mt_time' 構造体に変換
  // これにより年月日時分秒などの個別の情報に分けることができる
  TimeToStruct(current_time, mt_time); 

  // 分解した年月日時分秒などの情報を 'Print()' 関数で出力
  Print("Year: ", mt_time.year);            // 現在の年
  Print("Month: ", mt_time.mon);            // 現在の月
  Print("Day: ", mt_time.day);              // 現在の日
  Print("Hour: ", mt_time.hour);            // 現在の時間（時）
  Print("Minute: ", mt_time.min);           // 現在の時間（分）
  Print("Second: ", mt_time.sec);           // 現在の時間（秒）
  // 'day_of_week' は曜日を整数で表し、日曜日が0、月曜日が1...となる
  Print("Day of the Week: ", mt_time.day_of_week); 
  // 'day_of_year' は年始からの経過日数を表す
  Print("Day of the Year: ", mt_time.day_of_year);
}

TimeCurrent関数を利用して、現在のサーバー時間を取得し、その情報をMqlDateTime構造体の各メンバに振り分け、その後振り分けた各メンバのデータをPrint関数で出力される・・・という挙動になっています。

MqlDateTime構造体の各メンバに振り分け処理を行っているのがTimeToStruct関数、という事になります。