Tinderbox v9 Icon

Date-Type Attributes


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 Displayed Attributes (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 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()).

From v9.5.0, adding or subtracting Interval data from Date data whose value is "never", correctly returns "never".

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 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:

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())^).

Default/Empty value

The string "never" (no date set).

Sorting order

Ascending (later) date/time order; "never" always sorts last.

Date-type System Attributes

Built-in attributes of the date data type are listed below: