FormatDateTime Function

Action

Formats a DATETIME according to a format string consisting of one or more masks and returns the formatted value as a string.

Syntax

sDateTime = FormatDateTime(Datetime[, sFormat])
Variable Description
sDateTime The datetime value converted to a formatted string as specified. STRING.
Datetime The value that is to be formatted. DATETIME.
sFormat Optional The formatting string. If this argument is omitted, the function uses the default format. The date and time masks and the default format are listed below under Notes. STRING.

Notes

The function ignores any fields not identified by format masks. Thus you can use this function to format any subset of the specified DATETIME value.

Characters that are not in the following table are copied unchanged to the returned string—for example, the delimiter / (forward slash).

The following formatting masks are available:
Mask Description
d Display the day as a number without a leading zero (1-31).
dd Display the day as a number with a leading zero (01-31).
ddd Display the day as an abbreviation (Sun, Mon, Tue, Wed, Thu, Fri, or Sat).
dddd Display the day as a full name (Sunday-Saturday).
w Display the day of the week as a number (1 for Sunday through 7 for Saturday).
ww Display the week of the year as a number (1-53).
m Display the month as a number without a leading zero (1-12). If m immediately follows h or hh, the minute rather than the month is displayed.
mm Display the month as a number with a leading zero (01-12). If mm immediately follows h or hh, the minute is displayed.
mmm Display the month as an abbreviation (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec).
mmmm Display the month as a full name (January-December).
y Display the day of the year as a number (1-366).
yy Display the year as a 2-digit number (00-99).
yyyy Display the year as a 4-digit number (100-9999).
h Display the hour as a number without leading zeros (0-23).
hh Display the hour as a number with leading zeros (00-23).
n Display the minute as a number without leading zeros (0-59).
nn Display the minute as a number with leading zeros (00-59).
s Display the second as a number without leading zeros (0-59).
ss Display the second as a number with leading zeros (00-59)
fff Display the millisecond as a number with leading zeros (000000-999999).
AM/PM Use the 12-hour clock and display an uppercase AM with any hour before noon. Display an uppercase PM with any hour between noon and 11:59 P.M.
am/pm Use the 12-hour clock and display a lowercase AM with any hour before noon. Display a lowercase PM with any hour between noon and 11:59 P.M.
A/P Use the 12-hour clock and display an uppercase A with any hour before noon. Display an uppercase P with any hour between noon and 11:59 P.M.
a/p Use the 12-hour clock and display a lowercase A with any hour before noon. Display a lowercase P with any hour between noon and 11:59 P.M.
xxxx Use the date format for the current locale.
XXXX Use the time format for the current locale.
If you specify no format string, FormatDateTime uses the following default format:
"m/d/yy h:mm:ss AM/PM"

FormatDateTime will correctly compute years that have fewer than four digits.

The following are some examples of date formats you can use.
Format Matches These Date Strings
m/d/yy 9/18/05, 09/18/05
mm/dd/yy 09/18/05 (but not 9/18/05)
m-d-yy 9-18-05, 09-18-05
yy/m/d 05/9/18, 05/09/18
mmddyy 091805
mm/dd/yyyy 9/18/2006, 09/18/2006
yyyy/m/d 2006/9/18, 2006/09/18
mmm d, yyyy Sep 18, 2006

In addition to the date masks, date formats can include the following delimiters:

  • Space (matches one or more spaces)

  • / - : , . (forward slash, hyphen, colon, comma, or period)

Any other character in the format generates an error.

Example

STRING sTimeStamp = FormatDateTime(GetDateTime(), "hh:nn:ss AM/PM")
STRING sDateStamp = FormatDateTime(GetDateTime(), "mm/dd/yy")
Print("Script started at {sTimeStamp} on {sDateStamp}.")