parseDateTime
Parses the input string to create a datetime object.
Once you've converted a string to a datetime object, you can use the object with many other datetime functions. For example, you can display the object in a different format (formatDateTime), or calculate the duration between two objects (dateTimeDifference).
For more about datetime objects, see Working with datetime objects.
Parameters
DATETIME STRING (string)
The string to parse. The function automatically parses strings that are in an automatically recognized datetime pattern. If the string is in a non-recognized pattern, use the INPUT FORMAT parameter.
INPUT FORMAT (string)
Optional. The datetime format string. Specify a letter pattern defining how Studio should parse the string. A list of common letter patters is given below. Alternatively, you can enter a locale.
Default: The function tries to parse using automatically recognized datetime patterns.
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
EXAMPLES — DATE-ONLY STRINGS IN RECOGNIZED PATTERNS
When your string is date-only and in the automatically recognized datetime pattern (yyyy-MM-dd), the function can parse without requiring a format string. You can leave the second parameter unspecified.
ATL in Script | Result |
|---|---|
| Jan 12, 2021 |
| Dec 1, 2021 |
Important
The result is a datetime object. The Result column in the table above shows how the object is displayed as formatted text in your project output. You can change the display format by using the formatDateTime function.
EXAMPLES — DATE-ONLY STRINGS IN NON-RECOGNIZED PATTERNS
When your string is date-only and not in an automatically recognized datetime pattern, you must give a format string in the second parameter. Specify a letter pattern defining how Studio should parse the string.
ATL in Script | Result |
|---|---|
[[date = '6/2/21'; parseDateTime(date, 'd/M/yy')]] | Feb 6, 2021 |
[[date = '26-02-1982'; parseDateTime(date, 'dd-MM-yyyy')]] | Feb 26, 1982 |
[[date = '25-Dec-2021'; parseDateTime(date, 'dd-MMM-yyyy')]] | Dec 25, 2021 |
[[date = '25 December 2021'; parseDateTime(date, 'dd MMMM yyyy')]] | Dec 25, 2021 |
[[date = 'Sat 25 Dec 2021'; parseDateTime(date, 'E dd MMM yyyy')]] | Dec 25, 2021 |
Tip
SYNTAX TIP
The format string must use the same dividers — for example, the hyphens in 25-Dec-2021 — that appear in the input string. If the date, month, and year elements are separated by blank spaces, include these spaces in your format string.
EXAMPLES — TIME-ONLY STRINGS IN RECOGNIZED PATTERNS
When your string is time-only and in an automatically recognized datetime pattern (such as HH:mm or HH:mm:ss), the function can parse without requiring a format string. You can leave the second parameter unspecified.
ATL in Script | Result |
|---|---|
| 8:00:00 AM |
| 1:00:00 PM |
| 12:00:00 AM |
| 12:00:15 AM |
Tip
Note that these input strings use the 24-hour clock (strings using the 12-hour clock are not automatically recognized). Also, notice that '00:00' is used for midnight. The ATL [[parseDateTime('24:00')]] produces an error.
EXAMPLES — TIME-ONLY STRINGS IN NON-RECOGNIZED PATTERNS
ATL in Script | Result |
|---|---|
[[time = '8:00'; parseDateTime(time, 'H:mm')]] | 8:00:00 AM |
[[time = '0800'; parseDateTime(time, 'HHmm')]] | 8:00:00 AM |
[[time = '083015'; parseDateTime(time, 'HHmmss')]] | 8:30:15 AM |
[[time = '10.30 AM'; parseDateTime(time, 'h.mm a')]] | 10:30:00 AM |
Tip
If the time you are parsing uses the 12-hour clock, it must also have AM or PM (in capitals). Use h and a in your format pattern for parsing these, as shown above.
EXAMPLES — DATETIME STRINGS IN RECOGNIZED PATTERNS
When a string containing date AND time values is formatted in the automatically recognized datetime pattern (yyyy-MM-ddTHH:mm:ss), the function can parse the string without requiring a format string.
ATL in Script | Result |
|---|---|
[[dateTimeVal = '1982-02-26T00:00:00'; parseDateTime(dateTimeVal)]] | Feb 26, 1982 12:00:00 AM |
[[dateTimeVal = '2021-12-25T10:30:15'; parseDateTime(dateTimeVal)]] | Dec 25, 2021 10:30:15 AM |
EXAMPLES — DATETIME STRINGS IN NON-RECOGNIZED PATTERNS
ATL in Script | Result |
|---|---|
[[dateTimeVal = 'Feb 26, 1982 00:00:00'; parseDateTime(dateTimeVal, 'MMM dd, yyyy HH:mm:ss')]] | Feb 26, 1982 12:00:00 AM |
[[dateTimeVal = '25-Dec-2021T10:30:15'; parseDateTime(dateTimeVal, "dd-MMM-yyyy'T'HH:mm:ss")]] | Dec 25, 2021 10:30:15 AM |
[[dateTimeVal = '25-Dec-2021 T 20 past 10'; parseDateTime(dateTimeVal, "dd-MMM-yyyy 'T' mm 'past' HH")]] | Dec 25, 2021 10:20:00 AM |
Important
When your input string is in a non-recognized pattern that uses T as a date-time delimiter (see the example above), you must include the T in your format string and enclose it within single quotation marks. To avoid syntax errors, you must also enclose your entire format string within double quotation marks. The same requirement applies when your input string includes regular words or characters — for example, see the word past in the example above.
EXAMPLES — DATETIME STRINGS (WITH OFFSET) IN NON-RECOGNIZED PATTERNS
When the input string includes Z (zero-hour offset), you can parse using X or XXX.
ATL in Script | Result |
|---|---|
[[dateTimeVal = '03/01/2021T10:00Z'; parseDateTime(dateTimeVal, "dd/MM/yyyy'T'HH:mmX")]] | Jan 3, 2021 10:00:00 AM |
[[dateTimeVal = '03/01/2021T10:00Z'; parseDateTime(dateTimeVal, "dd/MM/yyyy'T'HH:mmXXX")]] | Jan 3, 2021 10:00:00 AM |
Use X when your offset is hours-only, and use XXX when the offset includes hours and minutes.
ATL in Script | Result |
|---|---|
[[dateTimeVal = '03/01/2021T10:00+06'; parseDateTime(dateTimeVal, "dd/MM/yyyy'T'HH:mmX")]] | Jan 3, 2021 10:00:00 AM |
[[dateTimeVal = '03/01/2021T10:00+06:00'; parseDateTime(dateTimeVal, "dd/MM/yyyy'T'HH:mmXXX")]] | Jan 3, 2021 10:00:00 AM |
[[dateTimeVal = '3 January 2021 T 10:00 +06:00'; parseDateTime(dateTimeVal, "d MMMM yyyy 'T' HH:mm XXX")]] | Jan 3, 2021 10:00:00 AM |
EXAMPLES — LOCALES
You can also parse a string by entering a locale in the second parameter.
ATL in Script | Result | Notes |
|---|---|---|
[[date = '27/03/19'; parseDateTime(date, 'en_GB')]] | Mar 27, 2019 | The input string is in the standard format for English speakers in the United Kingdom. Given this, the function can parse the string by using the |
[[date = '27.03.2019'; parseDateTime(date, 'de_CH')]] | Mar 27, 2019 | The input string is in the standard format for German speakers in Switzerland. Given, this, the function can parse the string by using the |
Tip
See Locales for the full list of locales that Studio supports.
