This version is out of date, covering development from v9.5.0 to v9.7.3. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon

Date Formats

Date Formats

Tinderbox offers numerous date formats. An example date Tue, 29 Apr 2003 14:32:18 - 0500 is used to show the following various format strings below. Note that from v5, seconds cannot be set (and are ignored for comparisons) and are always shown/exported as '00'.

Do remember that the individual codes can be defined in a format string. The codes below are thus like placeholders in a literal string:

$MyString = Today is " + date("today").format("W, d MM y") 

On 29 February 2012 on a UK-locale system this makes $MyString:

Today is Wednesday, 29 February 2012

Note above how the spaces and comma within the format string are retained.

Below, the colons after each (bolded) code are not part of that format code but just a divider from the text that follows it; codes are all one or two characters. In places, clarification is given, e.g. number zero versus letter o. Dates before 1 January 1904 (start of the macOS calendar) are supported: see more.

Important note: the examples here are for US & UK system settings so as to illustrate day/month and month days variations. The exact format you see on your system from the same format string may differ depending on your computer OS' local system settings (macOS, see System Preferences, Languages & Text, Formats). For reference, this TBX was authored on a system using UK settings, so generally you will see example dates use day/month order.

Time offset calculation: the time offset is always applied for the current time in the current locale as derived from the host macOS.

Keywords used in specifying dates

Although not related to _formatting_ dates, there also keywords, e.g. now, yesterday, etc., that can be used when _setting_ Date-type attributes.

Date/Time formatting codes

Specific complete formats:-

L  : local date/time, as in the 'long' format of the host system format settings. Examples:

US: April 29, 2003 

UK: 29 April 2003

l  : local date, in short format, using the system format settings (l is lowercase L, not numeral one). Examples:

US: 4-29-03 

UK: 29/01/03

*  : date/time in RFC 822 format. Example: Tue, Apr 29 2003 14:32:00 +0500 (see note above on time offsets)

=  : date in ISO 8601 format. Example: 2023-04-29T14:32:18+05:00 (see note above on time offsets)

==  : (new from v9.7.0) date in ISO 8601 format but with date only and no time element. Example: 2023-04-29 (see note above on time offsets).

U  : formats the data in Unix epoch time, i.e. the number of seconds before or since the beginning of 1 January 1970.

n (for "normal"), which displays the system medium date string and short time string. Example; 21 Jan 2020 at 17:12.

Formatting code for specific parts of date/time, combine as required for custom format strings:-

Formatting codes for the day part of a date:-

d  : day of the month, not zero-padded. Example: 9 (note, not '09')

D  : formats the date of the month as a two digit number, with a leading zero as required (01-31). Example: 29

o  : day of the month as an ordinal (lowercase 'o'). Example: 2nd, 10th, but conversion respects the current locale's abbreviations. (v9.5.0)

w  : abbreviation of weekday. Example: Tue 

W  : name of weekday. Example: Tuesday 

Formatting codes for the month part of a date:-

m  : number of month, not zero-padded. Example: 4 (note, not '04')

M0  : formats the month as a two digit number, with a leading zero as required: 01-12. Example: 04. Note the second format character is zero, i.e. the format code is 'em-zero' not 'em-oh'.

M  : abbreviation of month. Example: Apr 

MM  : name of month. Example: April 

Formatting codes for the year part of a date:-

y  : 4 digit year. Example: 2003. (On some countries' settings this may still be 2 digits.)

Y  : 2 digit year (last 2 digits of year). Example: 03 

Formatting codes for time:-

t  : time, in local format. Examples:

US: 2:32 PM 

UK: 00:32

a  : accepted as an input abbreviation for "am".

p  : accepted as an input abbreviation for "pm".

Formatting codes for the hour part of a time:-

h  : hour of the day on a 24-hour clock, zero-padded for single digits. Examples: 14 from 14:32/2:32 PM, 05 from 05:32/5:32 AM.

H  : hour of the day on a 12-hour clock. Example: 2 from 14:32/2:32 PM, 5 from 05:32/5:32 AM. Use with 'p' to show AM or PM suffix, e.g. "H:mm p" gives 2:32 PM.

p  : the A.Mr P.Mf the hour, always uppercase, with no periods. Example: AM 

Formatting codes for the minute part of a time:-

mm  : minute of the hour, zero-padded for single digits. Examples: 32 for 32 past or 05 for five minutes after the hour.

Formatting codes for the seconds part of a time:-

s  : second of minute, zero-padded for single digits. Examples: 02, 18.

Escaping any of above as literals:-

Prefacing any character with a backslash, \, includes the that character literally, even if it otherwise has a special meaning in the above list. Thus a format string of "\dd \mm \yY" gives the output d29 m4 y03. Any other character includes the character. Thus, the format string "Local time:- h:mm:s" gives output of Local time:- 14:32:00, except that the seconds are always zeroed (in v5+).