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;
See Also
Year | Month | Date data type | DayOfMonth | DayOfWeek | Hour | Minute | Second| Now | SystemDate
DateAdd
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.
See Also
Date | Date data type | DateDiff
DateDiff
Usage
DATEDIFF([UNITS,]DATE1,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);
See Also
Date | DateAdd | Date data type
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.
See Also
Date | DayOfWeek | Year | Month | Hour | Minute | Second | Date data type
DayOfWeek
Usage
DAYOFWEEK([DATEVALUE])
- datevalue
- The date that will be evaluated.
Description
Given a date, DayOfWeek 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 |
See Also
Date | DayOfMonth | Year | Month | Hour | Minute | Second | Date data type
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).
See Also
Date | Year | Month | DayOfMonth | DayOfWeek | Minute | Second | Date data type
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));
See Also
Date | Date data type | OnOrSkipped
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).
See Also
Date | Year | Month | DayOfMonth | DayOfWeek | Hour | Second | Date data type
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.
See Also
Date | Year | DayOfMonth | DayOfWeek | Hour | Minute | Second | Date data type
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.
See Also
Year | Month | DayOfMonth | DayOfWeek | Hour | Minute | Second| Date | SystemDate | Date data type
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;
See Also
InputDate | Date | Date data type
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.
See Also
Date | Year | Month | DayOfMonth | DayOfWeek | Hour | Minute | Date data type
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.
See Also
Date | Month | DayOfMonth | DayOfWeek | Hour | Minute | Second | Date data type
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.
See Also
Year | Month | DayOfMonth | DayOfWeek | Hour | Minute | Second| Date | Now | Date data type