Date Formats

IMPORTANT: an explanatory note re formats. The examples here are for US & UK system settings so as to illustrate day/month and month days variations. The exact styled out any user sees on their own Mac from the same format string may differ depending on their computer's OS' local settings (macOS, see System Settings ▸ General ▸ Language & Region—also see Locale (below). For reference, this TBX was authored on a system using UK settings, so generally expect to see example dates use day/month order where only one example is given.

Example date/time for this article. An example date Tue, 29 Apr 2003 14:32:18 +0500 is used to show the following various format strings below.

OS Date/Time variants. Although no longer explicitly labelled in macOS System Settings app's UI, short/medium/long variants still exist.

Tinderbox offers numerous date formats, for some internationally recognised standard formats, e.g. ISO 8601, and codes do allow assembly of custom date format from individual date and/or time elements. The latter codes 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.

Locale. Date display and formatting is aware of locale and by default this is the locale set in the host macOS. For most users this means date layout, month/day order, etc. will look as they would expect. Occasionally, some user may need to see data date as for a different locale and this can be effected via the locale() action code operator.

Time offset calculation: the time offset is always applied for the current time in the current locale as derived from the host macOS. If using this TBX with different locale settings to the author's Mac, expect differences in the offsets reported.

Keywords used in specifying dates

Although not related to formatting dates, there also date/time-specific keywords, e.g. now, yesterday, etc., that can be used when setting Date-type attributes.

Escaping date/time code characters as literals

Prefacing any character with a backslash, \, includes 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.

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)

== : 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') : 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.

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 AM/PM of the hour, always uppercase, with no periods. Example: AM

Formatting codes for the minutes 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, always zero-padded for single digits. Examples: 02, 18.

See also—notes linking to here: