This version is out of date, covering development from v5.0.0 to v5.12.2. It is maintained here only for inbound reference links from elsewhere.

Jump to the current version of aTbRef.

Tinderbox 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 can't be set (and are ignored for comparisons) and are always shown/exported as '00'.

Do remember that the individual codes an be defined in a sting 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 Mac OS 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 (OS X, see System Preferences - Languages & Text -Formats; in OS 10.5.x and earlier use System Preferences - International - 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.

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. 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: 2003-04-29T14:32:18+05:00 (see note above on time offsets)

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 

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

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.M. or P.M. of 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.  (From v5 Tinderbox doesn't store/use seconds data, so seconds are always '00')

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+).

Possible relevant notes (via "Similar Notes" feature):

A Tinderbox Reference File : Import/Export/Formatting : Date Formats