Formatting DATETIME values

Date-time values must be formatted when converted to strings.

When does DATETIME formatting take place?

Datetime formatting occurs when converting a DATETIME to a string, for example in a LET, DISPLAY or PRINT instruction, and when displaying datetime values in form fields.

By default, DATETIME values are formatted in the ISO format:

yyyy-mm-dd hh:mm:ss.fffff

A DATETIME value can be formatted with the util.Datetime.format() method:

IMPORT util
MAIN
  DEFINE dt DATETIME YEAR TO SECOND
  LET dt = CURRENT
  DISPLAY util.Datetime.format(dt, "%Y-%m-%d %H:%M:%S")
END MAIN

This code example produces the following output:

2015-12-23 11:45:33

Converting strings to DATETIME values

When a string represents a datetime value is ISO format, it can be directly converted to a DATETIME:

DEFINE dt DATETIME YEAR TO FRACTION(5)
LET dt = "2015-12-24 11:34:56.82373"

If you need to convert a string that does not follow the ISO format, use the util.Datetime.parse() method, by specifying a format string:

DEFINE dt DATETIME YEAR TO MINUTE
LET dt = util.Datetime.parse( "2014-12-24 23:45", "%Y-%m-%d %H:%M" )

Formatting symbols for DATETIME values

When formatting DATETIME values, the format-string of the util.Datetime.parse() and util.Datetime.format() methods consists of a set of place holders that represent the different parts of a datetime value (year, month, day, hour, minute, second and fraction).

Table 1 shows the formatting symbols for DATETIME expressions. Any character different from the placeholders described in this table is interpreted as a literal and will appear as-is in the resulting string.

The calendar used for date formatting is the Gregorian calendar.

Table 1. Format-string symbols for DATETIME values
Placeholder	Description
`%a`	The abbreviated name of the day of the week Note: When parsing a datetime string, `%a` and `%A` are equivalent to detect the name of the day of the week in abbreviated form or full day name.
`%A`	The full name of the day of the week
`%b` or `%h`	The abbreviated month name Note: When parsing a datetime string, `%b`/`%h` and `%B` are equivalent to detect the month name in abbreviated form or full month name.
`%B`	The full month name
`%c`	The date and time representation
`%C`	The century number (0-99)
`%D`	Equivalent to `%m/%d/%y`
`%d`	The day of month with 2 digits (01-31)
`%e`	The day of month with one or 2 digits (1-31)
`%F[n]`	The fractional part of a second (`1<n<5`, `%F=%F5`) Note: `%F[n]` includes the dot: In the format string, there is not need to preceed this placeholder with the dot.
`%H`	The hour with 2 digits (00-23)
`%I`	The hour on a 12-hour clock (1-12)
`%y`	The year on 2 digits (91)
`%Y`	The year on 4 digits (1991)
`%m`	The month as 2 digits (01-12)
`%M`	The minutes (00-59)
`%n`	A newline character
`%p`	The locale's equivalent of AM or PM
`%r`	The 12-hour clock time. In the POSIX locale equivalent to `%I:%M:%S %p`
`%R`	Equivalent to `%H:%M`
`%S`	The seconds (00-59)
`%t`	A tab character
`%T`	Equivalent to `%H:%M:%S`
`%x`	The date, using the locale's date format
`%X`	The time, using the locale's time format
`%w`	The ordinal number of the day of the week (0-6), with Sunday = 0
`%y`	The year within century (0-99)
`%Y`	The year, including the century (for example, 1991)

Table 2. Datetime formatting examples
Formatting string	Datetime value	Corresponding string
`%d/%m/%Y %H:%M:%S%F3`	`2011-10-24 11:23:45.98765`	`24/10/2011 11:23.45.987`
`%d/%m/%Y %H:%M`	`2011-10-24 11:23:45`	`24/10/2011 11:23`
`[%d %b %Y %H:%M:%S]`	`2011-10-24 11:23:45`	`[24 Oct 2011 11:23:45]`
`(%a.) %b. %d, %Y`	`1999-09-23`	`(Thu.) Sep. 23, 1999`