【MQL5】MqlCalendarValue構造体について

MqlCalendarValue構造体とは

struct MqlCalendarValue
 {
  ulong                               id;                   // 値ID
  ulong                               event_id;             // イベントID
  datetime                           time;                 // イベントの日時
  datetime                           period;               // イベント報告期間
  int                                 revision;             // 報告期間に関連して発表された指標の改訂
  long                               actual_value;         // ppmでの実際の値(設定されていない場合はLONG_MIN)
  long                               prev_value;           // ppmでの前の値(設定されていない場合はLONG_MIN)
  long                               revised_prev_value;   // ppmでの改訂された前の値(設定されていない場合はLONG_MIN)
  long                               forecast_value;       // ppmでの予測値(設定されていない場合はLONG_MIN)
  ENUM_CALENDAR_EVENT_IMPACT         impact_type;           // 為替レートへの潜在的影響
  //--- 値を確認する関数
  bool                         HasActualValue(void) const;   // actual_valueが設定されている場合はtrueを返す
  bool                         HasPreviousValue(void) const; // prev_valueが設定されている場合はtrueを返す
  bool                         HasRevisedValue(void) const;  // revised_prev_valueが設定されている場合はtrueを返す
  bool                         HasForecastValue(void) const; // forecast_valueが設定されている場合はtrueを返す
  //--- 値を受け取る関数
  double                       GetActualValue(void) const;   // actual_valueを返す(値が設定されていない場合はnan)
  double                       GetPreviousValue(void) const; // prev_valueを返す(値が設定されていない場合はnan)
  double                       GetRevisedValue(void) const;  // revised_prev_valueを返す(値が設定されていない場合はnan)
  double                       GetForecastValue(void) const; // forecast_valueを返す(値が設定されていない場合はnan)
 };

MqlCalendarValue構造体は、MQL5において経済イベントの情報を保持するための構造体です。この構造体には、イベントの日時や実際の数値、予測値、改訂値、影響度など、経済指標に関する詳細な情報が格納されます。CalendarValueById関数やCalendarValueHistory関数といった関数を通じて取得され、経済データ分析や取引の自動化に役立てることができます。

idメンバについて

idメンバは、データ型がulong型で、経済イベントの個別の値を識別するための一意（１つしか存在しない）なIDを保持します。

MqlCalendarValue構造体におけるidメンバは、各イベントの具体的な値を特定する役割を果たし、CalendarValueById関数などの経済データを取得する際に利用されます。このIDを用いることで、特定のイベント値にアクセスしたり、他のイベント値と区別したりすることが可能です。

event_idメンバについて

event_idメンバは、データ型がulong型で、経済イベントそのものを識別するためのIDを保持します。このIDは、特定のイベント（たとえばGDP発表や失業率の報告など）を一意に識別するために使用され、複数の関連する値（実際の値や予測値など）が同じevent_idのもとにまとめられることがあります。event_idを活用することで、同じイベントに関連する異なるデータポイントを追跡しやすくなります。

timeメンバについて

timeメンバは、データ型がdateTime型で、イベントが発表される日時を保持します。このメンバには、経済イベントが公表された正確な日時が記録されており、取引タイミングや分析において重要な情報です。CalendarValueById関数やCalendarValueHistory関数を使って取得されたデータでは、すべての時刻が取引サーバーの時間で設定されています。

periodメンバについて

periodメンバは、データ型がdateTime型で、経済イベントが報告対象とする期間を示します。たとえば、四半期ごとのGDP成長率であれば、その四半期の開始日や終了日がperiodとして設定されます。これは、特定のイベントがどの期間に関するものであるかを判断するために役立ち、分析時にデータの時系列を正確に理解するために重要です。

revisionメンバについて

revisionメンバは、データ型がint型で、イベント発表後に行われたデータの改訂回数を示します。多くの経済指標は、初回発表後に数回にわたって修正されることがあり、revisionはその修正の段階数を表します。たとえば、revisionが1の場合、そのデータは一度改訂されたことを意味します。

actual_valueメンバについて

actual_valueメンバは、データ型がlong型で、発表された経済指標の「実際の値」を保持します。この値は、実際に発表されたデータを100万倍して格納しています。データが存在しない場合、actual_valueにはLONG_MIN（-9223372036854775808）が格納されます。このメンバを使用する際は、データが有効かを確認し、必要に応じて100万で除算して実際の値を取得します。

prev_valueメンバについて

prev_valueメンバは、データ型がlong型で、経済イベントの「前回の値」を保持します。この値もactual_valueと同様に100万倍されて格納されています。過去の発表データを参照する際に役立つ情報で、データが存在しない場合にはLONG_MIN（-9223372036854775808）が格納されます。このメンバを使用する際は、値が有効かを確認し、必要に応じて100万で除算して実際の値を取得します。

revised_prev_valueメンバについて

revised_prev_valueメンバは、データ型がlong型で、改訂された「前回の値」を保持します。
多くの経済指標は後から修正されることがあり、このメンバには、その修正後のデータが格納されます。値は100万倍されており、データが存在しない場合にはLONG_MIN（-9223372036854775808）が格納されています。このメンバを使用する際も、値が有効かを確認し、100万で除算して実際の値を取得する必要があります。

forecast_valueメンバについて

forecast_valueメンバは、データ型がlong型で、経済イベントにおける「予測値」を保持します。これは実際の発表前に予測された数値で、経済指標の事前予想として使われます。値は100万倍されており、データが存在しない場合にはLONG_MIN（-9223372036854775808）が格納されています。使用する際は、予測値が有効であるかを確認し、必要に応じて100万で除算して実際の予測値を取得します。

impact_typeメンバについて

impact_typeメンバは、データ型がENUM_CALENDAR_EVENT_IMPACT型で、経済イベントが通貨に与える可能性のある影響度を示します。
このメンバは、通貨レートに対するイベントの潜在的な影響を識別し、取引判断に役立つ情報を提供します。影響度の設定は、ENUM_CALENDAR_EVENT_IMPACTという列挙型を用いて行われ、影響の種類によって異なる識別子が設定されます。

ENUM_CALENDAR_EVENT_IMPACTについて

ENUM_CALENDAR_EVENT_IMPACTは、経済イベントが通貨レートに与える可能性のある影響度を示す列挙型です。
この列挙型は、イベントの影響を示す識別子のリストを提供し、影響がポジティブであるかネガティブであるか、または影響が設定されていないかを識別します。

CALENDAR_IMPACT_NA

CALENDAR_IMPACT_NAは、影響が設定されていない、または不明であることを示します。この識別子は、イベントが通貨レートに対して特定の影響を持たない、もしくは影響が判断できない場合に使用されます。

CALENDAR_IMPACT_POSITIVE

CALENDAR_IMPACT_POSITIVEは、イベントが通貨レートにポジティブな影響を与えることを示します。この識別子が設定されている場合、イベントは通常通貨の価値を上昇させる要因と見なされます。

CALENDAR_IMPACT_NEGATIVE

CALENDAR_IMPACT_NEGATIVEは、イベントが通貨レートにネガティブな影響を与えることを示します。この識別子が設定されている場合、イベントは通常通貨の価値を低下させる要因と見なされます。

HasActualValueメソッドについて

HasActualValueメソッドは、MqlCalendarValue構造体のメソッドで、実際の値（actual_value）が設定されているかどうかを確認する役割を持ちます。このメソッドは、値が設定されている場合にtrueを返し、設定されていない場合にはfalseを返します。

MQL5では、このメソッドはMqlCalendarValue構造体の一部として提供されていますが、具体的な処理内容（内部の実装）は公開されていません。
そのため、ユーザーからは「組み込み関数」のように扱われますが、MQL5ライブラリ内で構造体に含まれるメソッドの一部として設計されています。このため、利用者側はHasActualValueメソッドを直接呼び出して確認を行うだけで、処理の詳細を意識する必要はありません。

経済イベントの実際の値は、データが存在しない場合には特殊な値（LONG_MIN）が設定されるため、このメソッドを使うことでデータの有無を効率的に判断できます。取引や分析の際、データが有効かどうかを事前に確認したい場合に便利です。

(void) constという表記について

(void) constという表記は、MQL5の文法において以下の2つの意味を持ちます。

引数がないことを示す (void)
関数のパラメータリストに(void)と記述することで、「この関数は引数を受け取らない」という意味を表します。引数がない場合には単に()と書くこともありますが、(void)とすることで「何も引数を受け取らないこと」を明確に示すことができます。
関数がconst メソッドであることを示す const
constキーワードをメソッドの定義に付加すると、そのメソッドが「構造体やクラスのメンバを変更しないこと」を示します。たとえば、HasActualValue(void) constというメソッドでは、メソッドが構造体やクラスのメンバを読み取ることはできますが、メンバの値を変更することはできません。

このため、(void) constという表記は、「引数を取らず、メンバを変更しない関数」を表しています。この文法により、安全に読み取り専用のメソッドとして定義できます。

HasPreviousValueメソッドについて

HasPreviousValueメソッドは、MqlCalendarValue構造体のメソッドで、前回の値（prev_value）が設定されているかどうかを確認する役割を持ちます。このメソッドは、prev_valueが設定されている場合にtrueを返し、設定されていない場合にはfalseを返します。

前回の値が設定されていない場合には、prev_valueには特殊な値（LONG_MIN）が格納されているため、このメソッドを使うことでデータの有無を確認できます。経済指標の前回の発表値が必要な場面で、データが有効かどうかを判断できます。

HasRevisedValueメソッドについて

HasRevisedValueメソッドは、MqlCalendarValue構造体のメソッドで、改訂された前回の値（revised_prev_value）が設定されているかどうかを確認する役割を持ちます。このメソッドは、revised_prev_valueが設定されている場合にtrueを返し、設定されていない場合にはfalseを返します。

経済指標のデータは初回発表後に修正されることが多く、改訂値が重要な場合にこのメソッドが役立ちます。revised_prev_valueにデータがない場合は、LONG_MINが格納されるため、データの有無を確認する際に便利です。

HasForecastValueメソッドについて

HasForecastValueメソッドは、MqlCalendarValue構造体のメソッドで、経済イベントの予測値（forecast_value）が設定されているかどうかを確認する役割を持ちます。このメソッドは、forecast_valueが設定されている場合にtrueを返し、設定されていない場合にはfalseを返します。

予測値は、経済イベントに関する市場の期待を示す重要なデータであり、予測値がない場合にはforecast_valueにはLONG_MINが格納されます。データが有効かどうかを事前に確認したい際に、このメソッドが役立ちます。

GetActualValueメソッドについて

GetActualValueメソッドは、MqlCalendarValue構造体のメソッドで、実際の値（actual_value）を取得する役割を持ちます。このメソッドは、実際の値が設定されている場合はその値を返し、設定されていない場合には「NaN」（非数）を返します。

取得される値は100万倍されて格納されているため、実際の数値として利用する場合には100万で除算する必要があります。これにより、経済指標の発表された実際の値を安全に取り出すことが可能です。

GetPreviousValueメソッドについて

GetPreviousValueメソッドは、MqlCalendarValue構造体のメソッドで、前回の値（prev_value）を取得する役割を持ちます。このメソッドも、前回の値が設定されている場合はその値を返し、設定されていない場合には「NaN」を返します。

前回の値も100万倍されているため、使用する際は100万で除算して実際の数値として取り扱います。これにより、経済指標の過去の発表値を取得することができます。

GetRevisedValueメソッドについて

GetRevisedValueメソッドは、MqlCalendarValue構造体のメソッドで、改訂された前回の値（revised_prev_value）を取得する役割を持ちます。値が設定されている場合はその値を返し、設定されていない場合は「NaN」を返します。

改訂された前回の値も100万倍されて格納されています。使用する際には100万で除算してから実際の値として扱う必要があります。改訂値が重要な場合、このメソッドによって安全に取得することが可能です。

GetForecastValueメソッドについて

GetForecastValueメソッドは、MqlCalendarValue構造体のメソッドで、予測値（forecast_value）を取得する役割を持ちます。値が設定されている場合はその値を返し、設定されていない場合は「NaN」を返します。

予測値も100万倍されて格納されています。取引や分析で使用する際には100万で除算して実際の予測値を取得する必要があります。このメソッドを利用することで、事前に予測された経済イベントの数値を安全に参照することができます。