# Date and Time Functions

This section explains how to work with functions that operate on dates and times. Functions include the ability to input a date as a parameter, and extract certain parts of the date, such as month.

## Date

Usage

`DATE(YEAR,[MONTH,[DAY,[HOUR,[MINUTE,[SECOND]]]]])`
year
The year as a 4 digit number.
month
A value between 1 and 12. Defaults to 1 if not given.
day
A value between 1 and 31. Defaults to 1 if not given.
hour
A value between 0 and 23. Defaults to 0 if not given.
minute
A value between 0 and 59. Defaults to 0 if not given.
second
A value between 0 and 59. Defaults to 0 if not given.

Description

Returns a date value given the year, month, day, hour, minute, and secondspecified. If second, minute, or hour are not specified, 0 will be used. If monthor day are not specified, 1 will be used.

The result can then be used in other functions that require a date value, such as OnOrSkipped.

A comparison of three easily confused date functions is as follows:
Date returns a date value of a specifically defined year, month, day.
Now returns the date value of the bar BullScript is currently processing.
SystemDate returns a date value (date and time) according to your computers clock. That is, today.

Example

d := date(2004,12,1);
stop := if(onorskipped(d), Low-ATR(14), prev(undefined));
stop;

Usage

`DATEADD([UNITS,]AMOUNT,DATEVALUE)`
units
The type of units to add. One of Y,M,W,D,H,N,S. Days are used by default.
amount
The number of units to add.
datevalue
The starting date to add to.

Description

Calculates a new date that is amount units after datevalue. If amount is negative then counts that many units before datevalue. All calculations are performed in calendar days and time.

Unit Code Unit
Y Years
M Months
W Weeks
D Days
H Hours
N Minutes
S Seconds

Take care to not confuse months (M) and minutes (N).

Example

dateadd(“d”, 1, date(2004,12,31)) returns 1/1/2005.
dateadd(“d”, -1, date(2004,12,31)) returns 30/12/2004.
dateadd(“y”, 1, now) adds one year to the current bars date.
dateadd(1, now) returns tomorrows date.

## DateDiff

Usage

`DATEDIFF([UNITS,]DATE1,DATE2)`
units
The type of units to count. One of Y,M,W,D,H,N,S. Days are used by default.
date1
The older date
date2

Description

Returns the number of units between two date values, date1 and date2. If date1 is before date2 then the result is positive. Otherwise it is negative. All calculations are performed in calendar days and time.

Unit Code Unit
W Weeks
D Days
H Hours
N Minutes
S Seconds

Note: There is no standardised way to calculate a precise difference in years or months due to the varying number of days in each month. N is still used for minutes to be consistent with DateAdd.

Example

bday := inputdate(“Birthday”);
[name=”Age in days”; dp=0]
datediff(bday, now);
[name=”Approx age in seconds”; dp=0]
datediff(“s”, bday, now);

## DayOfMonth

Usage

`DAYOFMONTH([DATEVALUE])`
datevalue
The date that will be evaluated.

Description

Returns the day of the month of the given date value, or of the current bar if datevalue is not specified.

Example

DayOfMonth(Now) will return 10 for the bar on the 10th of Feb 2006.

## DayOfWeek

Usage

`DAYOFWEEK([DATEVALUE])`
datevalue
The date that will be evaluated.

Description

Given a dateDayOfWeek returns the day of the week as a number. If datevalue is not specified then the date of the current bar is used.

Table of Results

Result Meaning
0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

## Hour

Usage

`HOUR([DATEVALUE])`
datevalue
The date that will be evaluated.

Description

Returns the hour of the given date value, or of the current bar if datevalue is not specified.

Example

Hour(Now) will return 13 for the 1pm bar on an hourly chart.
Hour(Now) will return 10 for the 10:55-11:00 bar on a 5 minute chart.
Hour(Now) will return 11 for the 11:00-11:05 bar on a 5 minute chart.
if(Hour<hist(Hour,1),a,b) will return aon the first bar of each day in an intraday chart, and can be used to signal a new day. Other bars return b. It works because this is the only time that the hour number decreases (because it is reset).

## InputDate

Usage

`INPUTDATE([MESSAGE,[DEFAULT]])`
message
A description for the input parameter.
default
The default date value for this parameter.

Description

Allows input of a date from the user or another formula using this formula. Will display message as a prompt to the user. Default will be used by default, or if default is not specified then todays date will be used by default. If the chart being viewed is an intraday chart, then the time can also be set.

The result is not a number, but a special date value, which can be used in other date and time functions.

Example

{without a default}
d1 := inputdate(“Trade Date”);
{with a default}
d2 := inputdate(“Trade Date”, Date(2004,11,30));

## Minute

Usage

`MINUTE([DATEVALUE])`
datevalue
The date that will be evaluated.

Description

Returns the minute of the given date value, or of the current bar if datevalue is not specified.

Example

Minute(Now) will return 27 for the 11:27 bar on a minutely chart.
Minute(Now) will return 10 for the 13:10-13:12 bar on a 2 minute chart.
if(Minute<hist(Minute,1),a,b) will return aon the first bar of each hour in a chart with a period less than one hour, and can be used to signal a new hour. Other bars return b. It works because this is the only time that the hour number decreases (because it is reset).

## Month

Usage

`MONTH([DATEVALUE])`
datevalue
The date that will be evaluated.

Description

Returns the month of the given date value, or of the current bar if datevalue is not specified. 1 for January, 2 for February, and so forth.

## Now

Usage

`NOW()`

Description

Returns the date value of the current bar. A date value contains information for a year, month, day, hour, minute second. To extract individual parts of a date value, use the Year, Month, DayOfMonth functions, and so on.

A comparison of three easily confused date functions is as follows:
Date returns a date value of a specifically defined year, month, day.
Now returns the date value of the bar BullScript is currently processing.
SystemDate returns a date value (date and time) according to your computers clock. That is, today.

## OnOrSkipped

Usage

`OnOrSkipped(DATEVALUE)`
datevalue
The date to be compared against the current bar.

Description

Returns 1 (true) if the date (and time if applicable) of the current bar is equal to the specified date. Also returns 1 if the specified date was just skipped over. That is, if the current bar is past the specified date, but the previous bar was before it. Also returns 1 on the first bar of the chart if the specified date is before the date of the first bar. Returns 0 (false) at all other times.

This function is useful in setting up indicators that relate to a trade date, such as a trailing stop as it allows the date to be reliably identified. It is roughly equivalentto datevalue=now, except that if a date is accidentally specified that does not exist (eg a public holiday or weekend) then datevalue=now will completely fail to notice that the date has been passed, whereas OnOrSkipped will notice it.

Example

d := inputdate(“Trade Date”);
stop := if(onorskipped(d), Low-ATR(14), prev(undefined));
stop;

## Second

Usage

`SECOND([DATEVALUE])`
datevalue
The date that will be evaluated.

Description

Returns the second of the given date value, or of the current bar if datevalue is not specified.

Example

Second(SystemDate) will return 12 if the time according to your computer is 9:45:12.

## Year

Usage

`YEAR([DATEVALUE])`
datevalue
The date that will be evaluated.

Description

Returns the year of the given date value, or of the current bar if datevalue is not specified.

Example

Year(Now) will return 1997 for the bar on 11th November 1997.
if(Year>hist(Year,1),a,b) will return aon the first bar of each year, and can be used to signal a new year. Other bars return b. It works because this is the only time that the year number increases.

## System Date

Usage

`SYSTEMDATE()`

Description

Returns the current date/time according to your computer’s clock. That is, today’s date. This is returned as a date value, which contains information for a year, month, day, hour, minute second. To extract individual parts of a date value, use the Year, Month, DayOfMonthfunctions, and so on.

A comparison of three easily confused date functions is as follows:
Date returns a date value of a specifically defined year, month, day.
Now returns the date value of the bar BullScript is currently processing.
SystemDate returns a date value (date and time) according to your computers clock. That is, today.