LocalizeDateTime (open)

Returns a string containing a formatted date and time.

Syntax

LOADLIB "wh::util/localization.whlib";

STRING FUNCTION LocalizeDateTime(STRING formatstring, DATETIME date, STRING locale, STRING timezone, BOOLEAN useexact)

Parameters

STRING formatstring

Specifies the way the DATETIME value should be formatted

DATETIME date

The DATETIME value to format

STRING locale

The language or locale to use (e.g. 'en', 'en-GB', 'nl' or 'zh-Hans-CN')

STRING timezone

The time zone to use when formatting the DATETIME (use only when the provided date is in UTC as the supplied date will be converted to this time zone)

BOOLEAN useexact

Return value

STRING

A string with the formatted date and time. If MAX_DATETIME or an invalid @italic date value was entered, the function returns an empty string

Description

This function returns a string, containing the given date and time in a user-specified format.

The most common format specifiers are:

Code Effect
eee Abbreviated weekday name
eeee Full weekday name
e One-digit day of week number, first day of the week is locale specific (1 - 7)
MMM Abbreviated month name
MMMM Full month name
dd Two-digit day of month (01 - 31)
d Two-digit day of month, remove any leading zeros
HH Hour of the day, 24 hour day
H Hour of the day, 24 hour day, remove any leading zeros
hh Two-digit hour, 12 hour day (01 - 12)
h Two-digit hour, 12 hour day, remove any leading zeros
jj Two-digit hour, 12 or 24 hour day, depending on locale
j Two-digit hour, 12 or 24 hour day, depending on locale, remove any leading zeros
D Three-digit day of year, remove any leading zeros
MM Two-digit month number (01 - 12)
M Two-digit month number, remove any leading zeros
mm Two-digit minute (00 - 59)
m Two-digit minute, remove leading any zeros
a am/pm marker, depending on hour
SSS Three-digit millisecond (000-999)
ss Two-digit second (00 - 59)
s Two-digit second, remove any leading zeros
ww Two-digit week number (00 - 52)
w Two-digit week number, remove any leading zeroes (0 - 52)
yy Two-digit year without century (00 to 99)
y Year with century
z Time zone
' Text within quotes is ignored
'' Single quote '

When specifying an hour display, the locale may change the display from 12 to 24 hour notation or vice versa if combined with other speficiers (e.g. 'z').

Note that all letter characters are interpreted as format specifiers, unless enclosed within single quotes. Non-letter characters and quoted text are ignored.

For a full description of the formatting string, see https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax

Examples

// The date and time in American English.
// example1 = "January 01, 2005"
STRING example1 := LocalizeDateTime("ddMMMMy", MakeDateTime(2005, 1, 1, 12, 34, 56), "en");

// The date and time in German.
// example2 = "01. Januar 2005"
STRING example2 := LocalizeDateTime("ddMMMMy", MakeDateTime(2005, 1, 1, 12, 34, 56), "de");

// The date and time in Dutch notation, in Amsterdam time zone.
// example3 := "1-1-2005 13:34:56 CET"
STRING example3 := LocalizeDateTime("HmszdMy", MakeDateTime(2005, 1, 1, 12, 34, 56), "nl", "Europe/Amsterdam");

// All text other than format specifiers is ignored (note that the time and date separators are ignored as well)
// example4 := "1.1., 13:34:56"
STRING example3 := LocalizeDateTime("H.m.s 'op' d/M", MakeDateTime(2005, 1, 1, 12, 34, 56), "de", "Europe/Amsterdam");