Mastering Time in Mql4: How to Use TimeToStruct() and StructToTime() for Precise Date Calculations

How can I easily break down a date and time value into its components like year, month, day, and hour, modify them, and then convert it back?

In MQL4, the most efficient and robust way to manipulate date and time components is by using the MqlDateTime structure along with the TimeToStruct() and StructToTime() functions.

This approach allows you to access specific parts of a date (Year, Month, Day, Hour, Minute, Second) as integer variables, modify them directly, and then reassemble them into a valid datetime timestamp.

MQL4 Script: Date Decomposition and Modification

Here is a complete script demonstrating how to break down the current server time, modify the year and hour, and convert it back.

//+------------------------------------------------------------------+
//|                                            DateManipulation.mq4  |
//|                        Copyright 2023, MetaQuotes Software Corp. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#property copyright "Copyright 2023, MetaQuotes Software Corp."
#property link      "https://www.mql5.com"
#property version   "1.00"
#property strict
#property script_show_inputs

//+------------------------------------------------------------------+
//| Script program start function                                    |
//+------------------------------------------------------------------+
void OnStart()
{
   // 1. Get the initial time (e.g., Current Server Time)
   datetime originalTime = TimeCurrent();
   
   // 2. Declare the structure to hold the components
   MqlDateTime timeStruct;
   
   // 3. Break down the datetime into the structure
   TimeToStruct(originalTime, timeStruct);
   
   // Output original components
   Print("Original Time: ", TimeToString(originalTime, TIME_DATE|TIME_MINUTES));
   PrintFormat("Components -> Year: %d, Month: %d, Day: %d, Hour: %d", 
               timeStruct.year, timeStruct.mon, timeStruct.day, timeStruct.hour);
   
   // 4. Modify the components
   // Example: Change year to 2025 and set time to 08:00 AM
   timeStruct.year = 2025;
   timeStruct.hour = 8;
   timeStruct.min  = 0;
   timeStruct.sec  = 0;
   
   // Example: Move forward by 1 month (Logic handled automatically by StructToTime)
   timeStruct.mon = timeStruct.mon + 1; 
   
   // 5. Convert the structure back to a datetime value
   datetime modifiedTime = StructToTime(timeStruct);
   
   // Output modified result
   Print("--------------------------------------------------");
   Print("Modified Time: ", TimeToString(modifiedTime, TIME_DATE|TIME_MINUTES));
   Print("Raw Datetime Value: ", (long)modifiedTime);
}
//+------------------------------------------------------------------+

Key Functions Explained

1. MqlDateTime Structure:
   This is a predefined structure in MQL4 that contains the following integer fields:

   • year: The year (e.g., 2023).
   • mon: The month (1-12).
   • day: The day of the month (1-31).
   • hour: The hour (0-23).
   • min: The minute (0-59).
   • sec: The second (0-59).
   • day_of_week: Day of the week (0-Sunday, 1-Monday, ... 6-Saturday).
   • day_of_year: Day number of the year (0-365).

2. TimeToStruct(datetime, MqlDateTime&):
   Takes a standard datetime (number of seconds since Jan 1, 1970) and populates the MqlDateTime structure passed by reference.

3. StructToTime(MqlDateTime&):
   Takes a populated MqlDateTime structure and converts it back into a datetime value.

   • Auto-Correction: This function is very smart. If you set the month to 13, it will automatically roll over to January of the following year. If you set the hour to 25, it rolls to the next day.

Q&A: Date and Time Manipulation in MQL4

Q: What happens if I modify the day_of_week field in the structure?
A: When using StructToTime(), the day_of_week and day_of_year fields are ignored as inputs. The function calculates the timestamp based on Year, Month, Day, Hour, Min, and Sec. After calling StructToTime(), if you call TimeToStruct() again on the result, the day_of_week will be recalculated correctly based on the new date.

Q: Can I use this to calculate the expiration time for a pending order?
A: Yes. You can get TimeCurrent(), convert it to a structure, add exactly 4 hours to timeStruct.hour, convert it back using StructToTime(), and pass that result to OrderSend().

Q: Is there a way to just get the Year or Month without declaring a structure?
A: Yes, you can use the specific getter functions if you only need to read data, not modify and reconstruct it.

• TimeYear(datetime time)
• TimeMonth(datetime time)
• TimeDay(datetime time)
• TimeHour(datetime time)
  However, for modifying and rebuilding a date, the Structure approach is significantly cleaner than doing math on seconds.