Date functions

Analytica User GuideText, Date, Math, and Financial FunctionsDate functions

These functions work with date and time numbers — that is, the integer portion is number of days since the date origin, usually Jan 1, 1904, and the fractional portion is the fraction of a day elapsed since midnight. See Date numbers and the date origin. A date number displays as a date if you select a date format using the Number format dialog from the Result menu.

MakeDate() generates a date number from the year, month, and day. DatePart() extracts the year, month, day, or other information from a date number. DateAdd() adds a number of days, weeks, months, or years to a date. Today() returns today’s date.

MakeDate(year, month, day)

Gives the date value for the date with given «year», «month», and «day». If omitted, «month» and «day» default to 1. Parameters must be positive integers.

MakeTime(h, m, s)

Gives the fraction of a day elapsed since midnight for the given hour, minute and second. The hour, «h», is typically between 0 and 23 inclusive (but can be greater than 23 when encoding a duration of more than one day). Minutes «m» and seconds «s» must be between 0 and 59 inclusive.

DatePart(date, part)

Given a date-time value «date», DatePart() returns the year, month, day, hour, minute, or seconds as a number, according to the value of «part», which must be an uppercase character:

Y gives the four digit year as a number, such as 2006.
Q gives the quarter as a number between 1 and 4.
M gives the month as a number between 1 and 12.
D gives the day as number between 1 and 31.
W gives the day of the week as a number from 1 (Sunday) to 7 (Saturday).
H gives the hour on a 24-hour clock (0 to 23).
h gives the hour on a 12-hour close (1 to 12).
m gives the minutes (0 to 59).
s gives the seconds (0 to 59.99).

Other date options for «part» are: YY → '06', MM →'01', MMM → 'Jan', MMMM → 'January', DD → '09', ddd → '1st', dddd → 'first', Dddd → 'First', www → 'Mon', wwww → 'Monday', and q → 1 to 4 for number of quarter of the year.

Other time options for «part» are: HH → '15', hh → '03', mm →'05', and ss →'00'.

DatePart() can also weeks or weekdays elapsed since the date origin or in the current year.

wd (or wd+) gives the number of weekdays since the date origin including the indicated day.
wd- gives the number of weekdays since the date origin not including the indicated day.
#d gives the day number in the current year
#w gives the week number in the current year (the week starting on Sunday)
#wm gives the week number in the current year (the week starting on Monday)

The #w and #wm options consider the week containing Jan 1 to be week 1. Options e#w and e#wm return the European standard in which week1 is the first week containing at least 3 days.

Examples:

DatePart(MakeDate(2006, 2, 28), 'D') → 28

This makes a sequence of all weekdays between Date1 and Date2:

Index J := Date1 .. Date2;

Subset(DatePart(J, "W") >= 2 AND DatePart(J, "W") <= 6)

This computes the number of weekdays between two dates, including both endpoints:

DatePart(date2, 'wd+') - DatePart(date1, 'wd-')

Library: Special Functions

DateAdd(date, n, unit)

Given a date value «date», it returns a date value offset by «n» years, months, days, weekdays, hours, minutes or seconds, according to whether «unit» is Y, Q, M, D, WD, h, m, or s. If «n» is negative, it subtracts units from the date.

Examples:

DateAdd() is especially useful for generating a sequence of dates, e.g., weeks, months, or quarters, for a time index:

DateAdd(MakeDate(2006, 1, 1), 0 .. 12, "M") → ["1 Jan 2006", "1 Feb 2006", "1 Mar 2006", ... "1 Jan 2007"]

If an offset would appear to go past the end of a month, it returns the last day of the month:

DateAdd(MakeDate(2004, 2, 29), 1, 'Y' ) → 2005-Feb-28

DateAdd(MakeDate(2006, 10, 31), 1, 'M' ) → 2006-Nov-30

Since the dates 2005-Feb-29 and 2006-Nov-31 don’t exist, it gives the last day of the preceding month.

Adding a day offset, DateAdd(date, n, "D"), is equivalent to date + n. DateAdd(date, n, "WD") adds the specified number of weekdays to the first weekday equal to or falling after date.

Library: Special Functions

Today(withTime, utc)

Returns the current date (or optionally date and time) as a date number — the number of days since the date origin, usually Jan 1, 1904. Unlike other functions, it gives a different value depending on what day (and time) it is evaluated. It is most often called with no parameters, Today(), in which case the result is an integer representing the date in your local time zone. Including the optional parameter «withTime», Today(withTime: True) returns the current time of day in the fractional part. Today(withTime: true, utc: True) with the optional «utc» parameter, turns the coordinated universal date-time rather than the local date-time.

Since variables usually cache (retain) their value after computing it, the date could become out of date if the Analytica session extends over midnight. But, it will be correct again when you restart the model.

Library: Special Functions

ParseDate(date, badVal)

ParseDate() parses a textual date or time into a numeric value representing the number of days elapsed since the date origin. The parsing occurs independent of the number format setting for the variable being evaluated. The second optional parameter, «badVal», specifies the return value when «date» is not textual or cannot be parsed as a date. When omitted, «badVal» defaults to Null.

ParseDate("July 22, 2009") → 2009-Jul-22 {38554}

ParseDate("38554") → «null»

ParseDate("3:00 pm") → 0.625

ParseDate("7/22/2009 15:00:00") → 2009-Jul-22 3:00pm {38554.625}

Var x := ["hello", "7-22-2009"] Do ParseDate(x, x) → ["hello", 38554]

Note: The results in this example assume the default date origin of 1-Jan-1904 and that Windows is set to United States regional settings.

Sequence(start, end, dateUnit, step)

The Sequence function can be used to create a sequence of dates or date-times. A date or time sequence is created when «start» and «end» are date-time numbers, or when the «dateUnit» parameter is specified. The «dateUnit» parameter can be any of "Y", "Q", "M", "D", "WD", "h", "m", or "s". Note that options "Y", "Q", "M", and "WD" result in increments that have date-aware spacings, but in which the increment measured in days actually varies, due to variations in the lengths of months, the positions of weekends, and the presence of leap years.

Sequence(9-Aug-2012, 15-Aug-2012, dateUnit: "WD") → [9-Aug-2012, 10-Aug-2012, 13-Aug-2012, 14-Aug-2012, 15-Aug-2012]

Sequence(1-Jan-2012, 1-Jan-2013, dateUnit: "Q") → [1-Jan-2012, 1-Apr-2012, 1-Jul-2012, 1-Oct-2012, 1-Jan-2013]

Sequence(1-Jan-2012, 1-May-2012, dateUnit: "M") → [1-Jan-2012, 1-Feb-2012, 1-Mar-2012, 1-Apr-2012, 1-May-2013]

The «step» parameter can also be specified, for example, to step in increments of 2 months. When specified with a «dateUnit» increment, «step» must be an integer value. If it is not an integer, it is rounded down.

Ceil(x, dateUnit:...), Floor(x, dateUnit:...), Round(x, dateUnit:...)

These rounding functions (described in Math functions) can be used to round dates or times to the nearest date unit (i.e., nearest year, month, day, weekday, hour, minute or second) by specifying the optional «dateUnit» parameter. The date unit can be one of the following values: "Y", "Q", "M", "D", "WD", "h", "m", or "s". To specify «dateUnit», you should use a named-parameter syntax.

Ceil(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2013, 1-Oct-2012, 1-Sep-2012, 13-Aug-2012]

Floor(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2012, 1-Jul-2012, 1-Aug-2012, 10-Aug-2012]

Round(11-Aug-2012, dateUnit: ["Y", "Q", "WD", "Q"]) → [1-Jan-2013, 1-Jul-2012, 1-Aug-2012, 10-Aug-2012]

See more at Ceil(), Floor() and Round().

Sleep( seconds, untilTime )

(New in Analytica 5.0) Pauses the computation either for «seconds» seconds, or until the date-time «untilTime» is reached, or both. Also forces pending redraw events to be processed when the function is called. See Sleep for details and examples.

Date functions

Contents

MakeDate(year, month, day)

MakeTime(h, m, s)

DatePart(date, part)

DateAdd(date, n, unit)

Today(withTime, utc)

ParseDate(date, badVal)

Sequence(start, end, dateUnit, step)

Ceil(x, dateUnit:...), Floor(x, dateUnit:...), Round(x, dateUnit:...)

Sleep( seconds, untilTime )

See Also