High-Performance Time Functions (TimeUtils) – library MetaTrader 5

This library contains more than 80 different functions to deal with time variables. The primary aim of is to provide high-performance time functions. The performance mode (which can be controlled at a compile time via a #define) is disabled by default. This mode is not a requirement to include the library into your projects, as it can be included normally without it.

TIMEUTILS_PERFORMANCE_MODE

Optionally, performance-mode can be switched on at compile time via #defines before #include:

// enable performance mode for library
#define TIMEUTILS_PERFORMANCE_MODE
#include "TimeUtils.mqh"

This will redirect all calls to MQL’s built-in TimeToStruct and StructToTime functions to more efficient alternatives.

You can compile the script “performance_mode.mq5” with/without TIMEUTILS_PERFORMANCE_MODE to check for the difference in speed on you machine. This will be beneficial to high performance programs performing heavy or many time related tasks (e.g., scanning all the quotes historty for H1-bars of the start of trading weeks or collecting other statisitcs).

The function names should be self-explanatory, also you can find a short description for a specific function in TimeUtils.mqh file.

Listing of all functions in the library:

//+==================================================================+
//| Create datetime From Components                                  |
//+==================================================================+
datetime CreateDateTime(
   const int year,           // Year
   const int mon,            // Month
   const int day,            // Day
   const int hour = 0,       // Hour
   const int min = 0,        // Minutes
   const int sec = 0         // Seconds
   )
datetime CreateDateTime(MqlDateTime&  dt_struct);  // fast alternative to StructToTime()


//+==================================================================+
//| Break datetime To Components                                     |
//+==================================================================+
bool TimeToStructFast(
   datetime      dt,         // Date value to convert
   MqlDateTime&  dt_struct   // structure for the adoption of values
   )

//+==================================================================+
//| Extract Components of datetime: Sunday, yyyy.mm.dd hh:mm:ss      |
//| Get() Units                                                      |
//+==================================================================+
int GetSecond(datetime t)
int GetMinute(datetime t)
int GetHour(datetime t)
int GetDay(datetime t)
int GetMonth(datetime t)
int GetYear(datetime t)

//+==================================================================+
//| Day() Number                                                     |
//+==================================================================+
int DayOfWeek(datetime t)
int DayOfYear(datetime t)
int DayIndex(datetime t)

//+==================================================================+
//| Week() Number                                                    |
//+==================================================================+
int WeekOfMonth(const datetime t, bool StartsOnMonday = false)
int WeekOfYear(const datetime t, bool StartsOnMonday = false)
int WeekIndex(datetime t, bool StartsOnMonday = false)

//+==================================================================+
//| StartOf() Units                                                  |
//+==================================================================+
datetime StartOfMinute(datetime t)
datetime StartOfHour(datetime t)
datetime StartOfDay(datetime t)
datetime StartOfWeek(datetime t, bool StartsOnMonday = false)
datetime StartOfMonth(datetime t)
datetime StartOfYear(datetime t)

//+==================================================================+
//| EndOf() Units                                                    |
//+==================================================================+
datetime EndOfMinute(datetime t)
datetime EndOfHour(datetime t)
datetime EndOfDay(datetime t)
datetime EndOfWeek(datetime t, bool StartsOnMonday = false)
datetime EndOfMonth(datetime t)
datetime EndOfYear(datetime t)

//+==================================================================+
//| SecsElapsedOf() Units                                            |
//+==================================================================+
int SecsElapsedOfMinute(datetime t)
int SecsElapsedOfHour(datetime t)
int SecsElapsedOfDay(datetime t)
int SecsElapsedOfWeek(datetime t, bool StartsOnMonday = false)
int SecsElapsedOfMonth(datetime t)
int SecsElapsedOfYear(datetime t)

//+==================================================================+
//| RoundTo() / Nearest() Units                                      |
//+==================================================================+
datetime RoundToMinute(datetime t)
datetime RoundToHour(datetime t)
datetime RoundToDay(datetime t)
datetime RoundToWeek(datetime t, bool StartsOnMonday = false)

//+==================================================================+
//| CeilTo() / Next() Units                                          |
//+==================================================================+
datetime CeilToMinute(datetime t)
datetime CeilToHour(datetime t)
datetime CeilToDay(datetime t)
datetime CeilToWeek(datetime t, bool StartsOnMonday = false)

//+==================================================================+
//| Next() Weekday                                                   |
//+==================================================================+
datetime NextDay(datetime t, ENUM_DAY_OF_WEEK day)
datetime NextSaturday(datetime t)
datetime NextSunday(datetime t)
datetime NextMonday(datetime t)
datetime NextTuesday(datetime t)
datetime NextWednesday(datetime t)
datetime NextThursday(datetime t)
datetime NextFriday(datetime t)

//+==================================================================+
//| Previous() Weekday                                               |
//+==================================================================+
datetime PreviousDay(datetime t, ENUM_DAY_OF_WEEK day)
datetime PreviousSaturday(datetime t)
datetime PreviousSunday(datetime t)
datetime PreviousMonday(datetime t)
datetime PreviousTuesday(datetime t)
datetime PreviousWednesday(datetime t)
datetime PreviousThursday(datetime t)
datetime PreviousFriday(datetime t)

//+==================================================================+
//| Add() Units                                                      |
//+==================================================================+
datetime AddSeconds(datetime t, int amount)
datetime AddMinutes(datetime t, int amount)
datetime AddHours(datetime t, int amount)
datetime AddDays(datetime t, int amount)
datetime AddWeeks(datetime t, int amount)
datetime AddMonths(datetime t, int amount)
datetime AddYears(datetime t, int amount)

//+==================================================================+
//| Sub() Units                                                      |
//+==================================================================+
datetime SubSeconds(datetime t, int amount)
datetime SubMinutes(datetime t, int amount)
datetime SubHours(datetime t, int amount)
datetime SubDays(datetime t, int amount)
datetime SubWeeks(datetime t, int amount)
datetime SubMonths(datetime t, int amount)
datetime SubYears(datetime t, int amount)

//+==================================================================+
//| DifferenceIn() Units                                             |
//+==================================================================+
int DifferenceInCalendarDays(datetime beginTime, datetime endTime)
int DifferenceInCalendarWeeks(datetime beginTime, datetime endTime, bool StartsOnMonday = false)
int DifferenceInCalendarMonths(datetime beginTime, datetime endTime)

//+==================================================================+
//| IsSame() Units                                                   |
//+==================================================================+
bool IsSameMinute(datetime t1, datetime t2)
bool IsSameHour(datetime t1, datetime t2)
bool IsSameDay(datetime t1, datetime t2)
bool IsSameWeek(datetime t1, datetime t2, bool StartsOnMonday = false)
bool IsSameMonth(datetime t1, datetime t2)
bool IsSameYear(datetime t1, datetime t2)

//+==================================================================+
//| Misc                                                             |
//+==================================================================+
bool IsLeapYear(int year)
int  DaysInMonth(int year, int month)
datetime GetNthWeekday(iYear, iMonth, Nth, Weekday = SUNDAY)
datetime GetNthSunday(iYear, iMonth, Nth)

//+==================================================================+
//| Formating Time to String                                         |
//+==================================================================+
string t2s(datetime t, const int mode = TIME_DATE | TIME_MINUTES)

The two attached scripts “basic.mq5” and “advanced.mq5” shows the basic and advanced usage examples.