You can parse, format, and process the date and time within an expression. Dates use the ISO 8601 format in UTC.
Examples of valid dates:
- 2023-01-01T23:59:59Z
- 2023-01-01T23:59:59.123Z
- 2023-01-01T23:59:59.123456Z
- 2023-01-01T23:59:59+800
Default output formats are in UTC:
- 2023-01-01T23:59:59.001Z
- 2023-01-01Z
- 23:59:59Z
If you input the ISO 8601 format incorrectly, the system returns null.
This library accepts DateTime with millisecond precision greater than 3, but the output always truncates to millisecond precision of 3.
Additional input formats not documented above are not officially supported and subject to change without notice.
| String | Description | Input | Output |
|---|---|---|---|
String addDays(String
<inputDate>, int
<days>)where:
|
Adds a number of days to the date represented by a supported ISO 8601 string
representation and returns the new date in the default ISO 8601
output format. Returns null if
|
|
|
String addMonths(String
<inputDate>, int
<months>)where:
|
Adds a number of months to the date represented by a supported ISO 8601 string
representation and returns the new date in the default ISO 8601
output format. Returns null if
|
|
|
String addYears(String
<inputDate>, int
<years>)where:
|
Adds a number of years to the date represented by a supported ISO 8601 string
representation and returns the new date in the default ISO 8601
output format. Returns null if
|
#datetime.addYears('2021-01-31T01:01:01Z',
1) |
2022-01-31T01:01:01.000Z |
String addHours(String
<inputDate>, int
<hours>)where:
|
Adds a number of hours to the date represented by a supported ISO 8601 string
representation and returns the new date in the default ISO 8601
output format. Returns null if
|
#datetime.addHours('2020-12-31T23:59:59.001Z',
3) |
2021-01-01T02:59:59.001Z |
String addMinutes(String
<inputDate>, int
<minutes>)where:
|
Adds a number of minutes to the date represented by a supported ISO 8601 string
representation and returns the new date in the default ISO 8601
output format. Returns null if
|
#datetime.addMinutes('2021-01-31T23:59:59Z',
10) |
2021-02-01T00:09:59.000Z |
String addSeconds(String
<inputDate>, int
<seconds>)where:
|
Adds a number of seconds to the date represented by a supported ISO 8601 string
representation and returns the new date in the default ISO 8601
output format. Returns null if
|
#datetime.addSeconds('2021-02-28Z', 1) |
2021-02-28T00:00:01.000Z |
int getDayOfMonth(String
<inputDate>)where
|
Returns day-of-month, a value from 1 to 31 for valid input
or -1 if
|
#datetime.getDayOfMonth('2021-01-31T23:59:59Z') |
31 |
int getMonth(String <inputDate>)where
|
Returns the month from 1 to 12 for valid input or
-1 if
|
#datetime.getMonth('2021-02-28Z') |
2 |
int getYear(String <inputDate>)where
|
Returns value for the year for valid input or -1 if
|
#datetime.getYear('2021-01-31T23:59:59Z') |
2021 |
int getHour(String <inputDate>)where
|
Returns the hour of the day as a value between 0 and 23 for
valid input or -1 if
|
#datetime.getHour('2021-01-31T23:59:59Z') |
23 |
int getMinute(String <inputDate>)where
|
Returns the minute of the hour as a value between 0 to 59
for valid input or -1 if
|
#datetime.getMinute('2021-01-31T23:59:59Z') |
59 |
int getSecond(String
<inputDate>)where
|
Returns the second of the minute as a value between 0 to 59
for valid input or -1 if
|
#datetime.getSecond('2020-12-30T23:59:59.001Z') |
59 |
String now() |
Obtains the current date-time in default ISO 8601 output format. |
#datetime.now() |
<Current date and time in default ISO 8601 format> |
String toDateTime(int <year>,
int <month>, int
<dayOfMonth>, int
<hour>, int
<minute>, int
<second>)where:
|
Obtains the date and time from the provided year, month, day, hour, minute, and second and returns valid date and time in default ISO 8601 output format. Returns null if the value for any field is incorrect or out of range, such as day-of-month being invalid for the provided month or year. |
#datetime.toDateTime(2021, 1, 31, 10, 15,
0) |
2021-01-31T10:15:00.000Z |
String toDate(String <inputDate>)where
|
Transforms the date and time in a supported ISO 8601 format to a UTC date in the format
|
#datetime.toDate('2021-02-28Z') |
2021-02-28Z |
String toTime(String <inputDate>)where
|
Transforms the date and time in a supported ISO 8601 format to a UTC time in the format
|
#datetime.toTime('2021-01-31T23:59:59Z') |
23:59:59Z |
String format(String
<inputDate>, String
<pattern>)where:
|
Transforms the date and time in a supported ISO 8601 format to the date and time in the
specified format. Returns null if the input
|
|
|
int compare(String
<inputDateTime1>, String
<inputDateTime2>)where:
Note:
Both values are treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Compares this date and time to another date and time, including
the chronology. Returns |
|
|
Number daysBetween(String
<inputDateTime1>, String
<inputDateTime2>, Number
<defaultIfNotDate>)where:
Note:
<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Calculates the number of days between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned. |
|
|
Number weeksBetween(String
<inputDateTime1>, String
<inputDateTime2>, Number
<defaultIfNotDate>)where:
Note:
<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Calculates the number of weeks between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned. |
|
|
Number monthsBetween(String
<inputDateTime1>, String
<inputDateTime2>, Number
<defaultIfNotDate>)where:
Note:
<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Calculates the number of months between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned. |
|
|
Number yearsBetween(String
<inputDateTime1>, String
<inputDateTime2>, Number
<defaultIfNotDate>)where:
Note:
<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Calculates the number of years between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a supported ISO 8601 format, the value provided for <defaultIfNotDate> is returned. |
|
|
String periodBetween(String
<inputDateTime1>, String
<inputDateTime2>, String
<defaultIfNotDate>)where:
Note:
<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Calculates the period between input dates represented as amount of time in years, months,
and days using ISO 8601 period format
The letter A zero period is represented as zero days, or The period is calculated by removing complete months, then calculating the remaining number of days, adjusting to ensure that both have the same sign. The number of months is then split into years and months based on a 12 month year. |
|
|
String toUnixTimestamp(String
<inputDateTime>)where <inputDateTime> is the date-time in a supported ISO 8601 format. Note:
<inputDateTime> is treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Transforms the date-time in a supported ISO 8601 format to the number of seconds from the epoch of 1970-01-01T00:00:00Z. This returns null if <inputDateTime> is null, empty, blank, or not a supported ISO 8601 format. |
|
|
String fromUnixTimestamp(Number
<epochSeconds>)where <epochSeconds> is the number of seconds from the epoch of 1970-01-01T00:00:00Z. |
Builds date-time using the number of seconds from the epoch of 1970-01-01T00:00:00Z to a UTC date-time in default ISO 8601 format. Returns null if <epochSeconds> is null. |
#datetime.fromUnixTimestamp(1609459199) |
2020-12-31T23:59:59.000Z |
String parse(String
<inputDateTime>, String
<format>, Object
<options>)where:
Note:
<inputDateTime> is treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Parses <inputDateTime> in a format other than ISO 8601 as specified by <format>, and uses any default values specified in <options> if required to transform it to a date-time in ISO 8601 format. Will return null if <inputDateTime>:
|
|
|
String toDateTimeInTimezone(String
<inputDateTime>, String
<timezone>, String
<pattern>)where:
Note:
<inputDateTime> is treated as null if null, empty, blank, or not a supported ISO 8601 format. |
Transforms the date-time in a supported ISO 8601 format to date-time in the specified
timezone in the required format if specified, or the default
format Will return null if:
|
|
|