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

TimeUtils is a comprehensive date and time utility library for MQL5, providing over 150 self-explanatory functions organized into logical categories. It simplifies common calendar operations, eliminates boilerplate datetime code, and correctly handles leap years, varying month lengths, business days, and other calendar edge cases.

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

The library uses a very coherent vocabulary:

• DateFrom → construction
• Add → relative movement
• Difference → elapsed duration
• StartOf / EndOf → boundary
• Previous / Next → Adjuster
• With → field replacement
• Is → predicate

1. Core Date/Time

Fast access to individual calendar fields together with lightweight helpers for constructing and converting date/time values without manually populating an MqlDateTime structure.

//====================================================================
// Calendar Fields
//====================================================================
Year(datetime)                            Month(datetime)
Day(datetime)                             Hour(datetime)
Minute(datetime)                          Second(datetime)

DayOfWeek(datetime)                       DateOnly(time)
DayOfYear(datetime)                       TimeOnly(time)

2. Construction & Conversion

Create datetime values from calendar components or strings, and efficiently convert between datetime and MqlDateTime structures.

//====================================================================
// Construction & Conversion
//====================================================================
DateFrom(2026, 7, 20)
DateFromString("2026.07.20 14:30")

TimeToStructFast(datetime, MqlDateTime)
StructToTimeFast(MqlDateTime)

3. Calendar Indices & Positions

Retrieve absolute calendar indices or determine the position of a timestamp within a year, quarter, month, week or day.

//====================================================================
// Absolute Indices
//====================================================================
YearIndex(datetime)                       MonthIndex(datetime)
QuarterIndex(datetime)                    WeekIndex(datetime)
DayIndex(datetime)                        HourIndex(datetime)
MinuteIndex(datetime)

//====================================================================
// Position Within Calendar
//====================================================================
Quarter(datetime)

WeekOfYear(datetime)                      WeekOfMonth(datetime)

HourOfYear(datetime)                      MinuteOfYear(datetime)
HourOfQuarter(datetime)                   MinuteOfQuarter(datetime)
HourOfMonth(datetime)                     MinuteOfMonth(datetime)
HourOfWeek(datetime)                      MinuteOfWeek(datetime)
MinuteOfDay(datetime)

SecsElapsedOfYear(datetime)               SecsElapsedOfQuarter(datetime)
SecsElapsedOfMonth(datetime)              SecsElapsedOfWeek(datetime)
SecsElapsedOfDay(datetime)                SecsElapsedOfHour(datetime)
SecsElapsedOfMinute(datetime)             SecsElapsedOfEpoch(datetime)

SecondsSinceMidnight(datetime)

4. Navigation / Manipulation

Navigate through the calendar, snap timestamps to period boundaries, replace individual date/time fields, round to common intervals, and perform calendar-aware arithmetic.

//====================================================================
// Period Boundaries
//====================================================================
StartOfMinute(datetime)                   EndOfMinute(datetime)
StartOfHour(datetime)                     EndOfHour(datetime)
StartOfDay(datetime)                      EndOfDay(datetime)
StartOfWeek(datetime)                     EndOfWeek(datetime)
StartOfMonth(datetime)                    EndOfMonth(datetime)
StartOfQuarter(datetime)                  EndOfQuarter(datetime)
StartOfYear(datetime)                     EndOfYear(datetime)

StartOfToday()                            EndOfToday()
StartOfTomorrow()                         EndOfTomorrow()
StartOfYesterday()                        EndOfYesterday()

//====================================================================
// Calendar Navigation
//====================================================================
LastDayOfWeek(datetime)                   FirstWeekdayOfMonth(datetime, MONDAY)
LastDayOfMonth(datetime)                  LastWeekdayOfMonth(datetime, FRIDAY)
LastDayOfQuarter(datetime)                NthWeekdayOfYearMonth(2026, 11, Nth, FRIDAY)
LastDayOfYear(datetime)

NextDayOfWeek(datetime, MONDAY)           PreviousDayOfWeek(datetime, MONDAY)
NextOrSame(datetime, SUNDAY)              PreviousOrSame(datetime, SUNDAY)
NextSunday(datetime)                      PreviousSunday(datetime)
NextMonday(datetime)                      PreviousMonday(datetime)
NextTuesday(datetime)                     PreviousTuesday(datetime)
NextWednesday(datetime)                   PreviousWednesday(datetime)
NextThursday(datetime)                    PreviousThursday(datetime)
NextFriday(datetime)                      PreviousFriday(datetime)
NextSaturday(datetime)                    PreviousSaturday(datetime)

//====================================================================
// Rounding & Alignment
//====================================================================
RoundToMinute(datetime)                   CeilToMinute(datetime)
RoundToHour(datetime)                     CeilToHour(datetime)
RoundToDay(datetime)                      CeilToDay(datetime)
RoundToWeek(datetime)                     CeilToWeek(datetime)

//====================================================================
// Field Replacement
//====================================================================
WithSecond(datetime, 30)                  WithMonth(datetime, 12)
WithMinute(datetime, 45)                  WithYear(datetime, 2030)
WithHour(datetime, 14)                    WithTime(datetime, 14, 30, 0)
WithDay(datetime, 15)                     WithDate(datetime, 2026, 7, 20)
WithDayOfWeek(datetime, FRIDAY)

//====================================================================
// Arithmetic
//====================================================================
AddSeconds(datetime, 30)                  SubSeconds(datetime, 30)
AddMinutes(datetime, 15)                  SubMinutes(datetime, 15)
AddHours(datetime, 8)                     SubHours(datetime, 8)
AddDays(datetime, 5)                      SubDays(datetime, 5)
AddBusinessDays(datetime, 5)              SubBusinessDays(datetime, 5)
AddWeeks(datetime, 2)                     SubWeeks(datetime, 2)
AddMonths(datetime, 3)                    SubMonths(datetime, 3)
AddQuarters(datetime, 2)                  SubQuarters(datetime, 2)
AddYears(datetime, 10)                    SubYears(datetime, 10)

AddPeriod(datetime, MqlDateTime period)
SubPeriod(datetime, MqlDateTime period)

5. Difference & Duration

Calculate exact elapsed time or calendar-aware differences between two timestamps, including business days, calendar months and human-readable calendar periods.

//====================================================================
// Exact Time Durations
//====================================================================
DifferenceInSeconds(from, to)             DifferenceInBusinessDays(from, to)
DifferenceInMinutes(from, to)             DifferenceInWeekendDays(from, to)
DifferenceInHours(from, to)
DifferenceInDays(from, to)
DifferenceInWeeks(from, to)
DifferenceInMonths(from, to)
DifferenceInQuarters(from, to)
DifferenceInYears(from, to)

//====================================================================
// Calendar Differences
//====================================================================
DifferenceInCalendarDays(from, to)        DifferenceInCalendarWeeks(from, to)
DifferenceInCalendarMonths(from, to)      DifferenceInCalendarQuarters(from, to)
DifferenceInCalendarYears(from, to)

CalendarDifference(from, to, MqlDateTime period)
CalendarDifferenceToString(from, to)

6. Validation & Comparison

Convenience functions for validating dates, comparing timestamps, and checking whether a date belongs to the current calendar period.

//====================================================================
// Day Checks
//====================================================================
IsWeekday(datetime)                       IsWeekend(datetime)

IsSunday(datetime)                        IsThursday(datetime)
IsMonday(datetime)                        IsFriday(datetime)
IsTuesday(datetime)                       IsSaturday(datetime)
IsWednesday(datetime)

IsFirstDayOfMonth(datetime)               IsToday(datetime)
IsLastDayOfMonth(datetime)                IsTomorrow(datetime)
                                          IsYesterday(datetime)

//====================================================================
// Current Period
//====================================================================
IsCurrentMinute(datetime)                 IsCurrentMonth(datetime)
IsCurrentHour(datetime)                   IsCurrentQuarter(datetime)
IsCurrentWeek(datetime)                   IsCurrentYear(datetime)

//====================================================================
// Equality
//====================================================================
IsSameMinute(a, b)                        IsSameMonth(a, b)
IsSameHour(a, b)                          IsSameQuarter(a, b)
IsSameDay(a, b)                           IsSameYear(a, b)
IsSameWeek(a, b)

7. Calendar Information

Query calendar properties such as month lengths, week counts and leap years.

//====================================================================
// Calendar Information
//====================================================================
DaysInMonth(2026, 7)                      WeeksInMonth(2026, 7)
DaysInYear(2026)                          WeeksInYear(2026)

IsLeapYear(2028)

8. Formatting & Display

Format dates and durations using built-in helpers or customizable format strings for reports, logs and user interfaces.

//====================================================================
// Formatting
//====================================================================
string DayName(ENUM_DAY_OF_WEEK)
string MonthName(7)

string SecondsToString(3661)

string t2s(datetime, TIME_DATE | TIME_MINUTES)
string TimeFormat(datetime, "YYYY.MM.DD hh:mm")

List of all available time formats for TimeFormat():

//+------------------------------------------------------------------+
//| Get the formatted time according to the passed string of tokens. |
//| List of all available formats:                                   |
//| Format  Output            Description                            |
//| ------  ----------------  -------------------------------------  |
//| YY      18                Two-digit year                         |
//| YYYY    2018              Four-digit year                        |
//| M       1-12              The month, beginning at 1              |
//| MM      01-12             The month, 2-digits                    |
//| MMM     Jan-Dec           The abbreviated month name, 3-letters  |
//| MMMM    January-December  The full month name                    |
//| D       1-31              The day of the month                   |
//| DD      01-31             The day of the month, 2-digits         |
//| DDD     Sun-Sat           The short name of the day of the week  |
//| DDDD    Sunday-Saturday   The name of the day of the week        |
//| h       0-23              The hour                               |
//| hh      00-23             The hour, 2-digits                     |
//| H       1-12              The hour, 12-hour clock                |
//| HH      01-12             The hour, 12-hour clock, 2-digits      |
//| m       0-59              The minute                             |
//| mm      00-59             The minute, 2-digits                   |
//| s       0-59              The second                             |
//| ss      00-59             The second, 2-digits                   |
//| A       AM PM                                                    |
//| a       am pm                                                    |
//+------------------------------------------------------------------+
//| Sample formats:                                                  |
//| "YYYY.MM.DD hh:mm"           // "2024.12.08 22:05"  (default)    |
//| "DDD, YYYY.MM.DD hh:mm:ss"   // "Sun, 2024.12.08 22:05:21"       |
//| "D MMMM YYYY, HH:mm a"       // "8 December 2024, 10:05 pm"      |
//| "DD/MM/YYYY"                 // "08/12/2024"                     |
//+------------------------------------------------------------------+
string TimeFormat(const datetime t, const string format = "YYYY.MM.DD hh:mm");

//====================================================================
// Generic Daily Sessions                  Major FX Sessions
//====================================================================
IsInSession(8,0,17,0)                     IsInMarketSession(SESSION_LONDON)

IsInSession(time,                         IsInMarketSession(time,
            8,0,17,0)                                       SESSION_LONDON,
                                                            utcOffsetSeconds)

IsInSession("08:00",                      CurrentMarketSession()
            "17:00")

                                          CurrentMarketSession(time,
                                                               utcOffsetSeconds)

                                          MarketSessionName(CurrentMarketSession())

                                          IsSessionOverlap(SESSION_LONDON,
                                                           SESSION_NEW_YORK)

                                          IsSessionOverlap(time,
                                                           SESSION_LONDON,
                                                           SESSION_NEW_YORK,
                                                           utcOffsetSeconds)

//====================================================================
// News Checks                            Time Until News
//====================================================================
IsNearNews(checkTime,                     TimeUntilNews(from,
           eventTime,                                   events)
           before,
           after)

IsNearNews(checkTime,                     TimeUntilNews(from,
           before,                                      CALENDAR_IMPORTANCE_HIGH)
           after,
           CALENDAR_IMPORTANCE_HIGH)

2024.12.03 - v.1.10 : Initial release.

2024.12.05 - v1.15 : Added functions for business days and for Nth() weekday of the month. Optimized calculations in DaysInMonth() function.

2024.12.09 - v1.20 : Added TimeFormat() function to format the time according to the passed string of tokens.

2024.12.09 - v1.25 : Optimized calculations in TimeToStructFast() function.

2024.12.10 - v1.30 : Optimized TimeFormat(), StartOfYear() and EndOfYear() functions. Updated descriptions of some functions.

2024.12.15 - v1.35 : Optimized NthWeekdayOfYearMonth() function.

2024.12.18 - v1.40 : Added IsCurrentXXX(), IsToday(), IsTomorrow() and IsYesterday() functions.

2024.12.19 - v1.45 : Optimized AddMonths() and NthWeekdayOfYearMonth() functions.

2024.12.20 - v1.50 : More code clean-up.

2024.12.21 - v1.55 : Simplified calculations in AddMonths(): replaced the complex logic of adjusting months and years with a simpler total months calculation.

2026.06.22 - v1.60 : Optimized AddBusinessDays() and DifferenceInBusinessDays() functions. Added various IsXXX() check functions.

2026.07.06 - v2.00 : New March-based conversion routines derived from the Neri–Schneider calendar algorithm + validation script. Removed "performance" mode.

2026.07.07 - v2.10 : Added DaysInYear(), LastDayOf(), MinuteOf(), HourOf() and CalendarDifferenceToString() functions.

2026.07.10 - v2.30 : Added date construction, quarter, calendar difference, and relative-date helper functions. Introduced configurable week start and renamed several functions for a cleaner, more consistent API.

2026.07.12 - v2.35 : Updated CalendarDifferenceToString() to return the precise elapsed time, including hours, minutes, and seconds.

2026.07.14 - v2.40 : Redesigned the year/month decomposition in CalendarDifferenceToString() to correctly handle February 29 edge cases. Simplified and optimized the DifferenceInXXX() functions. Added epoch-based index functions.

2026.07.15 - v2.45 : Added CalendarDifference() to return the calendar difference between two dates, broken down into years, months, days, hours, minutes, and seconds.

2026.07.18 - v2.50 : Added AddPeriod() and SubPeriod() for calendar period arithmetic. Added WithXxx() functions for replacing individual date/time fields. Added IsInSession() for checking recurring daily sessions.

2026.07.20 - v2.55 : Optimized week-based functions. Added SessionOverlap() for calculating overlapping time intervals. Improved documentation and API comments.

2026.07.21 - v2.60 : Added comprehensive Trading Sessions and Economic Calendar utilities, including IsInSession(), IsInMarketSession(), IsSessionOverlap(), CurrentMarketSession(), MarketSessionName(), IsNearNews(), TimeUntilNews(), and NextOrSame()/PreviousOrSame() for inclusive weekday navigation. General code cleanup and documentation improvements.

2026.08.10 - v2.65 : Code cleanup and documentation improvements.