Special Handling of Date Values
| Release: |
• 4.6 • 5.0 • 5.1 • 5.2 • 5.3 • 5.4 • 6.0 • 6.1 • 6.2 • 6.3 • 6.4 • 6.5 • • 6.6 • 7.0 • 7.1 • 7.2 |
|---|
Analytica includes a set of Date Functions that let you create and manipulate date values and time values. Date values represent the number of days since Jan 1, 1900. A date value can also represent hours, minutes, seconds, and smaller units as a fraction of a day (digits after the decimal point). For example,
DateValue 0 is 1-Jan-1900DateValue 1 is 2-Jan-1900DateValue 1.5 2-Jan-1900:12:00:00
Common rounding functions and Sequence take an optional «dateUnit» parameter to work with dates:
- Floor(x, dateUnit): Rounds «x» down to the nearest integer equal or below «x», if «dateUnit» is omitted. Or you can specify «dateUni»t to round down to the nearest (preceding or same date) that starts the year (Jan 1), quarter, or other time unit as shown below.
- Ceil(x, dateUnit): Rounds «x» up to the nearest integer equal or above «x», if «dateUnit» is omitted. Or you can specify a «dateUnit» to round up to the nearest specified time unit.
- Round(x, dateUnit): Rounds «x» down to the nearest integer to «x», if «dateUnit» is omitted. Or you can specify «dateUnit» to the units to which you
- Sequence(startD, endD, dateUnit): Generates a sequence of dates (or date-time) from «startD» to «endD», using increments of «dateUnit».
- DateAdd(d, offset, unit): Returns a date-time by adding «offset» (in specified «unit»s) to date «d».
«dateUnit» can be any of these text values:
'Y'for Year'Q'for Quarter'M'for Month'WD'for Weekday'D'for Day (default if «dateUnit» is omitted)'h'for Hour'm'for minute's'for second
Note that Month is upper case 'M' and minute is lower case 'm'.
- Examples
Round up to the next year:
Ceil(MakeDate(2014, 12,17), dateUnit: 'Y') → 1-Jan-2015
Round to the nearest top of the minute:
Round(Today(withTime: 1), dateUnit: 'm') → 17-Dec-2014 11:32:00 AM
List the next 5 Groundhog Days:
Sequence(MakeDate(2015, 2, 2), MakeDate(2019, 2, 2), dateUnit: 'Y') →[2-Feb-2015, 2-Feb-2016, 2-Feb-2017, 2-Feb-2018, 2-Feb-2019]
or equivalently,
DateAdd(2-Feb-2015, 0..4, unit:'Y') →[2-Feb-2015, 2-Feb-2016, 2-Feb-2017, 2-Feb-2018, 2-Feb-2019]
Creating Dates
It is possible to create a date value without help from any function. A value will be recognized as a date if it follows the syntax dd-EEE-yyyy
Where:
ddis one or two digits for day of monthEEEis a three character text code for the month in the default language set in the OS. (English in the example below)yyyyis four digits for the year
- Example
04-DEC-2015
The bare date syntax must be used on its own. It cannot be embedded within an expression.
New to Analytica 7.2: the ISO 8601 form yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss (two-digit month and day) can be used anywhere in an expression, optionally followed directly by a UTC offset such as Z or +00:00, which is converted into the model's time zone (Sys_TimeZone). See Date and Time Values.
To explicity define a date you can use either ParseDate() or MakeDate().
Importing Dates
DbQuery() and SpreadsheetRange() can import date values into Analytica. Both recognize date type values in the source data.
By default, DbQuery does not convert these to dates when importing but you can change this preference using the «datesAsText» parameter. More details here.
SpreadsheetRange() always preserves date values when they are imported. There are no optional parameters to think about in this case.
ParseDate and ParseCSV read ISO 8601 / RFC 3339 timestamps with a UTC offset, such as those returned by web APIs, converting them into the model's time zone or the zone given by their «timeZone» parameter (new to Analytica 7.2).
Dedicated Date Functions
The section above summarized special handling of dates using multi-purpose functions. Dedicated date functions are documented on the Date Functions page.