Format date/time string

Syntax

s.timeformat([frm] [time] [locale] [dateFlags] [timeFlags])

 

Parameters

s - str variable.

frm - format-control string.

time - variable of type DATE, SYSTEMTIME or FILETIME, containing date and/or time.

locale - locale identifier. See table. If omitted, or 0, uses LOCALE_USER_DEFAULT. Read more later in this topic.

dateFlags - GetDateFormat flags.

timeFlags - GetTimeFormat flags.

 

Remarks

Added in QM 2.3.1. In older QM versions can be used str.time.

 

The function copies frm to s, replacing parts enclosed in {} to date or time. Certain characters in enclosed parts control the date/time format. The characters must match case.

 

In frm can be used parts of several types:

 

{D} short date, like "08/09/2009".
{DD} long date, like "August 9, 2009".
{T} time without seconds, like "15:59" or "3:59 PM".
{TT} time with seconds, like "15:59:30" or "3:59:30 PM".

 

For custom date format can be used the following character sequences. They must be in frm parts enclosed in { }. They are the same as with GetDateFormat.

 

  Inserts Example
d Day of month as digits. 5
dd Day of month as digits with leading zero for single-digit days. 05
ddd Day of week as its abbreviated name. Sun
dddd Day of week as its full name. Sunday
M Month as digits. 4
MM Month as digits with leading zero for single-digit months. 04
MMM Month as its abbreviated name. Apr
MMMM Month as its full name. April
y Year as last two digits, but with no leading zero for years less than 10. 9
yy Year as last two digits, but with leading zero for years less than 10. 09
yyyy Full year. 2009
gg Period/era string. A.D.

 

For custom time format can be used the following character sequences. They must be in frm parts enclosed in { }. They are the same as with GetTimeFormat.

 

  Inserts
h Hours with no leading zero for single-digit hours; 12-hour clock.
hh Hours with leading zero for single-digit hours; 12-hour clock.
H Hours with no leading zero for single-digit hours; 24-hour clock.
HH Hours with leading zero for single-digit hours; 24-hour clock.
m Minutes with no leading zero for single-digit minutes.
mm Minutes with leading zero for single-digit minutes.
s Seconds with no leading zero for single-digit seconds.
ss Seconds with leading zero for single-digit seconds.
t One character time-marker string, such as A or P.
tt Multicharacter time-marker string, such as AM or PM.

 

This function cannot format milliseconds. For this you can use class DateTime or Windows API functions, such as GetTickCount, timeGetTime, GetLocalTime. See example.

 

If you have a DateTime variable, you can instead call its function ToStr or ToStrFormat (supports milliseconds etc).

 

By default, this function uses the date/time format and language from Control Panel -> Regional. Use locale only if you need some other language/format. A locale identifier is a number that includes primary language and sublanguage constants, like in this example:

 

out _s.timeformat("{DD} {TT}" 0 WINAPI.LANG_FRENCH|(WINAPI.SUBLANG_FRENCH_CANADIAN<<10))

 

This function does not generate errors. If some part or sequence in frm is incorrect, tries to find the nearest match (eg yyy -> yyyy), or leaves the part unchanged. If locale is unsupported, uses current locale (LOCALE_USER_DEFAULT). If replacing some enclosed part fails for other reasons, for example an incorrect argument value, the enclosed part will be empty, and the function sets _hresult to 1. Sets it to 0 if all parts were successfully replaced.

 

To create code for this function, you can use the Text dialog from the floating toolbar.

 

With F string, use {{ } for date/time parts, because { } are used for variables. See example.

 

Examples

str s
s.timeformat ;;same as s.timeformat("{D} {T}")
s.timeformat("{D} {TT}")
s.timeformat("Current date is {DD}")
s.timeformat("Current date is {MMM dd yyyy}, {HH 'hours and' mm} minutes")
s.timeformat("" 0 WINAPI.LANG_ENGLISH|WINAPI.SUBLANG_ENGLISH_US)

DATE d.getclock ;;get current time
d=d+1 ;;add 1 day
s.timeformat("{DD} {TT}" d)

SYSTEMTIME st
GetLocalTime &st
s.format("%02i:%02i:%02i.%03i" st.wHour st.wMinute st.wSecond st.wMilliseconds)

int var=5
s.timeformat(F"{var}. {{DD}") ;;with F string use {{} for date/time parts