Time and Calendar Functions

year (int offset): int

Year number of the given bar, f.i. 2011.

month (int offset): int

Month number of the given bar, 1..12.

week (int offset): int

Week number of the given bar, 1..52, aligned to Thursday.

day (int offset): int

Day of month of the given bar, 1..31.

dom (int offset): int

Number of days of the month of the given bar, 28..31.

tdm (int offset): int

Trading day of the month of the given bar, 1..23. Weekends (see Weekend) are skipped when counting trading days.

tom (int offset): int

Number of trading days of the month of the given bar, 20..23. (tom(offset)-tdm(offset)) gives the days until the last trading day of the month. Holidays are not accounted for. 

dow (int offset): int

Day of week of the given bar, MONDAY (1), TUESDAY (2) ... SUNDAY (7).

ndow (int offset): int

Number of the current day of week in the current month; to be used f.i. for finding the first Monday (1), the third Friday (3), etc.

ldow (int zone,int offset): int

Local day of week of the given bar in the given time zone (see timeOffset below), considering daylight saving time (see dst below). If BarZone is set to the local zone, ldow() is identical to dow().

hour (int offset): int

Closing hour of the given bar, 0..23, with 1 second precision. hour(0) gives the current hour and can be used to apply different trade tactics in the US, European, or Asia-Pacific session.

lhour (int zone, int offset): int

Closing local hour of the given bar in the given time zone (see timeOffset below), considering daylight saving time (see dst below). F.i. lhour(EST) returns the current hour at the New York Stock Exchange. If BarZone is set to the local zone, lhour() is identical to hour().

minute (int offset): int

Closing minute of the given bar, 0..59, with 1 ms precision. minute(0) gives the current minute.

tod (int offset): int

Time of day of the given bar in the form hhmm, f.i. 2107 for 9:07 pm.

ltod (int zone, int offset): int

Local time of day of the given bar in the form hhmm.

tow (int offset): int

Time of week of the given bar in the form dhhmm. d is the weekday number starting with Monday(1), f.i. 52107 = Friday 9:07 pm. See also StartWeek, EndWeek.

ltow (int zone, int offset): int

Local time of week of the given bar in the form dhhmm.

second (): var

Closing second of the current bar. The decimals give the fraction of the second with 1 ms precision.

second (var Time): var

Second of the given Time value in Windows DATE format. The decimals give the fraction of the second with 1 ms precision. The returned value can be different to the seconds printed by strdate, which are rounded to the next full second. 
 

minutesAgo (int offset): int

Total number of minutes between the end of the bar with the given offset and the end of the current bar.

minutesWithin (int offset): var

Total number of minutes from start to end of the bar with the given offset. Normally identical to BarPeriod, but can be different due to weekends, holidays, daylight saving time, gaps due to lack of price quotes, or when called from an intrabar function.
 

workday (int offset): bool

Returns true when the end of the given bar is not within a holiday or a weekend determined by StartWeek and EndWeek.

market (int zone, int offset): bool

Returns true when the end of the given bar is within market hours given by StartMarket and EndMarket (see also suspended()).

dst (int zone, int offset): int

Returns 1 when daylight saving time is active at the end of the given bar, otherwise 0. A simplified daylight saving schedule is used, based on US east coast daylight saving periods for all time zones in America, Sydney daylight saving periods for Australian and Pacific time zones, and European daylight saving periods for all other time zones. UTC and JST time zones have no daylight saving time. For years between 2000 and 2024 the real historical time switching dates are used, for all other years estimated dates from an average of the historical dates.
 

Parameters:

offset Optional offset of the bar for which the date or time is returned, to the current bar; or 0 for the current bar; or NOW for the current PC time; or when > 30000, a particular date in DATE format. When multiple time frames are used, the bar number offset is multiplied with TimeFrame.
zone UTC for UTC time (GMT+0), WET for London, CET for Frankfurt, EST for New York, CST for Chicago, JST for Tokyo, AEST for Sydney, or a number giving the zone offset in hours to UTC. Daylight saving time is considered in non-UTC zones for all years from 2000 to 2024.

Usage:

hour(1) returns the hour of the previous bar.

 

wdate (int offset): var

Returns date and time of the given bar offset in Windows DATE format. 

wdateBar (int n): var

Returns date and time of the bar with the given bar number (0...NumBars-1) in DATE format.

wdatef (string Format, string DateTime): var

Returns date and time of the given DateTime string in Windows DATE format, like wdate(). Can be used to parse date/time fields in CSV files in various formats. Zorro 1.51 or above.

strdate (string Format, int offset): string

strdate (string Format, var Date): string

Returns a temporary string in the given Format with the date and time of the given bar offset or DATE variable, to be used f.i. in printf statements. F.i. strdate(YMD,0) returns a string with the date of the current bar.

dmy (int YYYYMMDD): var

ymd (var Date): int

Convert a date in the YYYYMMDD format to the Windows DATE format and vice versa.

utm (var Date): int

Convert a date in Windows DATE format to Unix time (seconds since 1-1-1970).

Parameters:

Format

Format string, see format codes. Some often used format strings are predefined in variables.h: YMD = "%Y%m%d";   HMS = "%H:%M:%S";    YMDHMS = "%y%m%d %H:%M:%S".

offset Bar offset, f.i. 1 for the previous bar, or NOW for the current time (see remarks).
YYYYMMDD Date as integer, f.i. 20180403 for April 3, 2018.
Date Date/time in Windows DATE format, as returned from wdate(). Days are represented by whole number increments starting with 30 December 1899, midnight UTC. The time of the day is represented in the fractional part of the number. This format allows easy and precise date comparison down to a microsecond (= 0.000001/(24*60*60)).
DateTime Date/time string in various formats, see format codes.

Usage:

printf("\nDate: %s",strdate(YMD,0)); prints the current bar date in YYYYMMDD format. wdatef("%d.%m.%y","15.9.16") returns the DATE value of September 15, 2016.

 

timeOffset (int zone, int days, int hour, int minute): int

Returns the offset (in bars) of the bar closing at the given time, or 0 if the time lies within the current bar (including the weekend), or -1 if the time lies in the future.

Parameters:

zone UTC for UTC time, ET for New York, WET for London, CET for Frankfurt, AEST for Sydney, JST for Tokyo, or a number giving the zone offset in hours to UTC. Daylight saving time is considered in non-UTC zones from 2000 to 2024.
days Number of days in the past, or 0 for the day of the current bar.
hour Hour of the day, 0..23. If above 23, days is adjusted accordingly.
minute Minute of the hour, 0..59. If above 59, hour is adjusted accordingly.

Usage:

timeOffset(ET,1,16,0) returns the bar offset of yesterday's NYSE closing time. timeOffset(ET,0,9,30) returns 0 when the NYSE is just opening.

 

Remarks:

Examples:

// buy at UTC midday at the last day of the month, 
// sell 2 trading days later
function run()
{
  BarPeriod = 60;
  algo("Monthly");
  if(NumOpenLong == 0) { // not yet bought this month
    if((tom(0) == tdm(0)) && hour() >= 12)
      enterLong();
  } else if(tdm(0) >= 2)
      exitLong();
}

// helper function in default.c for printing the date
string datetime()
{
return strf("%02d.%02d.%02d %02d:%02d:%02d",
day(),month(),year()-2000,hour(),minute(),(int)second());
}

See also:

bar, dayHigh, timer, BarZone, Weekend, format codes

► latest version online