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.
Date includes a time element even if not displayed
If a date is specified but not a time, time always defaults to current system time except the seconds are not shown in Displayed Attributes (visual format may vary by locale, e.g. on the use of the colon delimiter).
The element in Date comparisons
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 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()).
Considering date vs. date-time in queries is discussed here.
Date keywords
Tinderbox recognises date keywords such as today, now, yesterday, tomorrow, day, week, month, year, hour and minute as date-defining placeholders when working in action code (see date keywords link 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". See more on the syntax for setting/adjusting dates using date keyword strings.
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 Date 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.
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 European 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.
Use of negative (BCE) dates
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.
From v9.7.2, there is improved handling of ancient dates. Dates before the common era now appear in displayed attributes as "BCE", and may be edited. Date strings such as "44 BCE" are now handled appropriately. "BCE" is added to BCE dates in OS short format as well as medium format.
Miscellanea about Date-type data
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())^).
From v9.6.0, the Date conversion of integers has been modified for better handling of prehistoric dates. When integers are converted to dates, the conversion is as follows:
- -35000 to +2500: refers to a year between 35,000 BCE and 2500 CE.
- otherwise: refers to the number of seconds before or after midnight UTC on 1 Jan 1970.
Default/Empty value
The string "never" (no date set).
Sorting order
Ascending (later) date/time order; the default value "never" always sorts last. When sorting lists of Data-type data always use .sort and not .nsort (the latter gives an incorrect sort result).
Storing date/time durations
This is done using the Interval data type. The maximum unit size in an Interval is a day and it can work for up to 30 days. But generally it is for periods of a day or or less thought of in hours, minutes and seconds.
Doing date/time calculations with Date and Interval types
This is described in discussion of the Interval data type and here.
From v9.5.0, adding or subtracting Interval data from Date data whose value is "never", correctly returns "never".
Date-type System Attributes
Built-in attributes of the date data type are listed below: