Date number after applying offset.
Syntax: @dateadd(d, offset, u[, f])
d: date number, series, vector
offset: integer, series, vector
u: time unit string
f: (optional) number
Return: date number, series, vector
Returns the date number given by d offset by offset time units as specified by the time unit string u. The optional parameter f controls handling of business days.
• The valid time unit string values are: “A” or “Y” (annual), “S” (semi-annual), “Q” (quarters), “MM” (months), “WW” (weeks), “DD” (days), “B” (business days), “HH” (hours), “MI” (minutes), “SS” (seconds).
• When the time unit u is business days (“B”), the optional control flag parameter f controls how a non-business day date number d is handled. When f is absent or equal to zero, the date number d is automatically advanced to the next business day before offset is applied. Otherwise, when f is non-zero automatic advancement is suppressed. Consequently, when f is non-zero and offset is 0 the function returns the original date number d (a non-business day).
Examples
Suppose that the value of d is 730088.0 (midnight, December 1, 1999).
Then we can add and subtract 10 days from the date by using the functions
@dateadd(730088.0, 10, "dd")
@dateadd(730088.0, -10, "dd")
which return 730098.0 (December 11, 1999) and (730078.0) (November 21, 1999). Note that these results could have been obtained by taking the original numeric value plus or minus 10.
To add 5 weeks to the existing date, simply specify “WW” as the time unit string:
@dateadd(730088.0, 5, "ww")
returns 730123.0 (January 5, 2000).
To find the date 3 months prior to the existing date, specify “MM” as the time unit string:
@dateadd(730088.0, -3, "mm")
The function may usefully be combined with other date functions. To find the day of the week 4 months from DD:
@datestr(@dateadd(dd, 4, "mm"), "Wdy")
Business day adjustments are slightly more complex. Suppose that the value of DD is 730091.0 (midnight, December 4, 1999), which is a Saturday:
730091.0
Then the previous business day, may be obtained by
@dateadd(dd, -1, "b")
@dateadd(dd, -1, "b", 1)
which both return 730090.0 (December 3, 1999), the preceding Friday.
A business day offset of 0 with a zero (or omitted) control flag f, automatically advances to the next business day
@dateadd(dd, 0, "b")
returns 730093.0 (December 6, 1999), the following Monday.
A business day offset of 0 with a non-zero control flag f, does not advance from the original day, so that
@dateadd(dd, 0, "b", 1)
returns 730091.0 (December 4, 1999), the original Saturday.
Automatic business day adjustments are performed prior to applying the offset parameter, so that
@dateadd(dd, 1, "b")
returns 730094.0 (December 7, 1999), the following Tuesday, while
@dateadd(dd, 1, "b", 1)
returns 730093.0 (December 6, 1999), the following Monday.
If DSER is a series containing date numbers,
series dser1 = @dateadd(dser, 3, "mm")
produces the 3-month date number offsets associated for each observation for DSER in the workfile sample. You may use “@date” in place of DSER to obtain results using the built-in dates in the workfile structure.
If DVEC is an vector containing date numbers,
vector avec = @dateadd(dvec, 3, "mm")
produces the 3-month date number offsets for elements of the vector.
Cross-references
See
“Dates” and
“Date Formats” for additional details on date numbers and date format strings.