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 are not 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. From v9.3.0, seconds are acknowledged in comparisons, except those excluding all time elements of a date/time (Previously, seconds were not used and/or are always considered to be 00. To use exact equality tests on full date-time data use interval()).
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. If number is supplied without a date placeholder, e.g. "today + 1", then 'day' is assumed as a default unit value, i.e. as if the input was "today +1 week".
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.
Initialising a Data attribute without time information
Beware the use of only date placeholders, without time indicators, 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 Displayed 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. If current time is 17:03:24 (5 PM, 3 minutes and 24 seconds):
$StartTime = date("27/03/2022") gives a time of 17:03:24 on 27 March 2002 (US users only, reverse day/month order)
$StartTime = date("27/03/2022 00:00:00") gives a time of 00:00:00 on 27 March 2002 (US users only, reverse day/month order)
Similarly if initialising a Date attribute by typing in a Displayed Attributes or Get Info value, you must explicitly include the h/m/s time unless you wish to use the default (system) time.
Date Comparisons
Considering date vs. date-time in queries is discussed here.
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 Displayed Attribute input.
Users should check the Formats pane of the International pane (Formats tab) of their macOS 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.
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 Displayed Attribute box or in display expressions to display the fact that a date is negative.
- Negative dates cannot be tested for using greater than/less than comparisons.
- Negative dates cannot easily be set via a Displayed 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 will 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 Displayed 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())^).
Sorting order
Ascending (later) date/time order; "never" always sorts last.
Date-type Attributes