Date
A date and time string. It should always be enclosed in double quotes (legacy code without these may cease to work as expected). Dates can be added/subtracted/compared in mathematical fashion, as per number data types. The resulting 'string' can be formatted by means of date format codes. If no default value is specified, a Date type defaults to a value of never. If a date is specified but not a time, time always defaults to current system time except the seconds aren't shown in KeyAttributes (visual format may vary by locale - e.g. in the use of the colon delimiter).
Time is used in date comparisons except when the == or != operators are used. Also see Basic Comparison Operators and date comparisons; the same rules hold true for data comparisons in action code expressions. Seconds are not used and/or are always considered to be 00.
Tinderbox recognises today, now, yesterday, tomorrow, day, week, month, year, hour and minute as date placeholders (see date designators for a full list). Constructions like "yesterday + 1 week" , "tomorrow + 1 year" or "tomorrow - 2 hours" are also possible; note how the whole expression is placed in one set of double quotes. The 'now' placeholder can be used as an alternate for 'today'. As both the latter use the current system clock time for their time element, note that it is possible to set an explicit time alongside designators (only use 24-hour clock time: "today 16:00" or "tomorrow - 2 days 23:59". See more on setting times.
Use of date placeholders to initially set a Date attribute will result in the time portion (hours:minutes) being set to the users local OS system time. Entering a time-less date into a key attribute value box, e.g. "21 Aug 2001" will also result in the time portion being set from the OS local time. Using a date designator to alter an existing date never alters the time part of the date attribute value. The time part of a date can be altered either by manually (re-)setting it or by use of time-related action codes.
Effects of OS locale. Tinderbox will assume a manually supplied version uses the same day/month order as the user's current locale settings. In other words, if working on a US system using month/day order enter 6 July 2001 as "7/6/2011" whereas on a British system using day/month order use "6/7/2011", and so on for other locales. Dates that use slashes "1/7/05" and the Continental format with periods, e.g. "1.7.05" are both recognised.
For years with only one or two digits, e.g. 10CE, you should always enter the year part of the dates as 4 digits (e.g. 0010) when setting dates via code or key attribute input.
Users should check the Formats pane of the International pane (Formats tab) of their Mac OS System Preferences and ensure the 'short' format uses four-digit year numbers. To do this (for a region), on the Formats tab, click the the 'Customize…' button to the right of the example dates. The 'Show' pop-up is most likely set to 'Short' - leave it as that. In the white text box below click on to year; you will see a drop-down menu that will allow you to choose either 2-digit or 4-digit dates, select the four-digit date. US users should note the default US setting for "short" date formats is to display 2-digit years, i.e. 10/3/65 (for 1765, 1865, etc.). All numeric reverse-order dates like '20090130' can be used though do test the exact desired format before committing to extensive use.
From v5.7.0, Tinderbox will allow negative dates to allow analysis of data either side of the CE/BCE (AD/BC) boundary. Negative integers from -1 to -2500, when coerced to dates, are interpreted as years BCE (BC). Some current limitations re 'negative' dates:
- Currently, there is no way in a key attribute box or in display expressions to display the fact that a date is negative.
- Negative dates can't be tested for using greater than/less than comparisons.
- Negative dates cannot easily be set via a key attribute input. The easiest method is to make a stamp with code like this:
$StartDate.year = ($StartDate.year-(2*$StartDate.year)-1). That code will flip a positive date to a negative one. Given the first limitation above re displaying BCE dates, you'll need to check out that the result is correct. - Date.year always returns a positive number - even from a negative date.
- There are no date-format strings that will show the epoch.
Tinderbox XML documents store dates using ISO 8601 format. Tinderbox also recognises date strings entered as key attributes or converted from strings in actions when in the ISO 8601 format (e.g. 2008-11-20 16:55:00).
Two dates may be subtracted with a result in days even if the result is a string. This helps with tasks like setting DisplayExpression.
Tinderbox offers numerous date formats to allow non-default representations of date/time both in internal action code (use with format()) or for export (use with ^value(format())^).