formatDateTime
Formats a datetime object using a format pattern or locale.
Parameters
DATETIME (datetime or string)
A datetime object, or a string in an automatically recognized datetime pattern.
OUTPUT FORMAT (string)
Optional. The format string. Specify a letter pattern defining how to format the datetime object. A list of common letter patters is given below. Alternatively, you can enter a locale.
Default: MMM d, yyyy hh:mm:ss a
Common letter patterns
yy or yyyy for year M or MM for month (number) MMM or MMMM for month (text) d or dd for day of the month (number) D or DDD for day of the year (number) E or EEE or EEEE for day of the week (text) hh or h for hours (12-hour clock) HH or H for hours (24-hour clock) mm for minutes ss for seconds SSSSSSSSS for fractions of seconds a for AM or PM w for week of the year (number) W for week of the month (number) F for day of aligned week in the month (number) VV for timezone ID X for time offset with hours only XXX for time offset with hours and minutes (Use X or XXX for a time offset of Z (zero-hour offset) |
Note
For more about pattern letters, see the section Patterns for Formatting and Parsing on Oracle’s documentation site. We refer you to that section only; we don't support predefined formatters such as those defined elsewhere on that page.
Examples
All examples below use a string in an automatically recognized datetime pattern.
Alternatively, the input could be a datetime object created using the parseDateTime function.
Formatting time-only values
These examples use time-only strings in an automatically recognized datetime pattern (HH:mm:ss.SSSSSSSSS).
If you don't give a format pattern, the default pattern is MMM d, yyyy hh:mm:ss a.
ATL in Script | Result | Notes |
|---|---|---|
| 8:00:00 AM | The function applies the default format pattern. |
| 12:00:00 PM | The default format pattern marks noon as 12:00:00 PM. |
| 1:00:00 PM | The default format pattern uses the 12-hour clock. |
| 12:00:00 AM | Use |
| 11:59:59 PM | The default pattern doesn't display fractional seconds. |
To override the default formatting, give a pattern in the second parameter.
ATL in Script | Result |
|---|---|
| 10 AM |
| 10:00AM |
| 10.00 AM |
| 20 past 10 |
Tip
SYNTAX TIP
To include a word like "past" in the format string, use backslashed quotes ( \' ) before and after the word.
Formatting date-only values
These examples use date-only strings in an automatically recognized datetime pattern (yyyy-MM-dd).
If you don't give a format pattern, the default pattern is MMM d, yyyy hh:mm:ss a.
ATL in Script | Result |
|---|---|
| Feb 26, 1982 |
| Dec 25, 2021 |
To override the default formatting, give a pattern in the second parameter.
ATL in Script | Result |
|---|---|
| 25/12/21 |
| 25 Dec 21 |
| Sat 25 Dec 2021 |
| Saturday 25 December |
Formatting date + time values
These examples use date + time strings in an automatically recognized datetime pattern (yyyy-MM-ddTHH:mm:ss).
If you don't give a format pattern, the default pattern is MMM d, yyyy hh:mm:ss a.
ATL in Script | Result |
|---|---|
[[dateTimeValue = '1982-02-26T07:30:00'; formatDateTime(dateTimeValue)]] | Feb 26, 1982 7:30:00 AM |
To override the default formatting, give a pattern in the second parameter.
ATL in Script | Result |
|---|---|
[[dateTimeValue = '1982-02-26T07:30:00'; formatDateTime(dateTimeValue, 'dd-MM-yyyy\' @\' h.mma')]] | 26-02-1982 @ 7:30AM |
[[dateTimeValue = '1982-02-26T07:30:00'; formatDateTime(dateTimeValue, 'd MMM yyyy\' at\' HH:mm:ss a')]] | 26 Feb 1982 at 07:30:00 AM |
[[dateTimeValue = '1982-02-26T07:30:00'; formatDateTime(dateTimeValue, 'HH:mm:ss a\' on\' dd MMMM yyyy')]] | 07:30:00 AM on 26 February 1982 |
Tip
SYNTAX TIP
To include a regular word like "on" in the format string, use backslashed quotes ( \' ) before and after the word.
Formatting dates with ordinals
You can format a date with ordinals (e.g. 1st, 22nd, or 99th) by adding the @ character.
We support the following ordinals:
Day of the Month: d@ or dd@ Month of the Year: M@ or MM@ Week of the Year: w@ Week of the Month: F@ or W@ Day of the Year: D@
ATL in Script | Result |
|---|---|
[[dateValue = '2021-11-05'; formatDateTime(dateValue, 'd@ MMMM yyyy')]] | 5th November 2021 |
[[dateValue = '2021-11-05'; formatDateTime(dateValue, "'the 'MM@ 'month of' yyyy")]] | The 11th month of 2021 |
[[dateValue = '2021-11-05'; formatDateTime(dateValue, "'the' w@ 'week of' YYYY")]] | The 45th week of 2021 |
[[dateValue = '2021-11-05'; formatDateTime(dateValue, "'the' D@ 'day of' YYYY")]] | the 309th day of 2021 |
[[dateValue = '2021-11-05'; formatDateTime(dateValue, "'the' W@ 'week of the' M@ 'month'")]] | The 1st week of the 11th month |
Tip
SYNTAX TIP
When you include regular words or phrases — such as 'week of the' — in the format string, you must enclose these in single quotation marks. To avoid syntax errors, you must also enclose the whole format string in double quotation marks.
Formatting datetimes with locales
The second parameter can take a locale instead of format pattern. A locale is a code representing a language and country — for example, en_AU is the code for English, Australia. Entering the locale en_AU is a quick and easy way to tell Studio to use the format pattern favored by most English speakers in Australia.
ATL in Script | Result | Locale |
|---|---|---|
| 25/12/2021 10:00:00 AM | English, Australia |
| 25-Dec-2021 10:00:00 AM | English, Canada |
| 25 déc. 2021 10:00:00 | French, France |
| 2021-12-25 10:00:00 | French, Canada |
| 25 दिसंबर, 2021 10:00:00 पूर्वाह्न | Hindi, India |
| ডিসেম্বর 25, 2021 10:00:00 AM | Bangla, India |
Tip
See Locales for the full list of locales that Studio supports.
