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. Holidays are not accounted for.
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).
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. hour() 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. minute() 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.
wdate (int offset): var
Date and time of the given bar in Windows DATE format. 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)).
wdateBar (int n): var
Date and time of the bar with the given number (0...NumBars-1) in DATE format.
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 (for details see Weekend).
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.
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.
dmy (int YYYYMMDD): var
ymd (var Date): int
Convert a date in the YYYYMMDD format to the Windows DATE
format and vice versa.
strdate (string Format, int offset): string
strdate (string Format, var Date): string
Returns a temporary string with the date and time of the given bar offset or DATE variable, to be used f.i. in printf statements.
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.
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 |
Optional bar number, or NOW for
the current time (see remarks). |
Date |
Date/time in DATE format, as returned from wdate(). |
DateTime |
Date/time string in various formats. |
Usage:
printf("\nTime: %s",strdate("%Y-%m-%d %H:%M:%S")); prints the current bar time in year-month-day hour:minute:second 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:
- If not stated otherwise, all dates and times are UTC (Greenwich mean time without daylight saving time).
- Date and time functions return 0 at the initial run of the strategy when the bars are not set up yet.
- When offset is omitted, the time of the current bar is returned. When offset is set to NOW, the current time is returned.
When the Now time variable is set to a valid DATE
value, it replaces the current time.
- The offset parameter is affected by TimeFrame. F.i. when TimeFrame is 6 and offset is 3, the time of 3*6 = 18 bars ago is returned.
- The time functions require a LookBack period of at least the highest used or returned offset.
- Most date and time functions return int, but some return var - take care of that when using the functions in a printf statement (see example).
- In live trading the time reflects the server time. Rounding errors must be
considered. For instance, the weekday (dow()) exactly at midnight
can return two different values depending won whether the server time is a second slower than
the PC time. So a tick can have a 23:59:59 time stamp, while the PC clock has already the next day at 00:00:00. When using daily bars, check the whole time and not only the day, or set the bar offset so that the bars do not change exactly at midnight.
- The Windows COleDateTime class has a bug that causes minutes and seconds
in time strings to be inaccurate by about half a second. This bug is worked
around in the minute and second functions
that are accurate, but it affects the strdate function.
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