Temporal expressions
Literal
Creates a new temporal value. A value can be written in one of the following ways:
- using a temporal function (e.g.
date("2020-04-06")) - using the
@- notation (e.g.@"2020-04-06")
date("2020-04-06")
@"2020-04-06"
time("08:00:00")
time("08:00:00+02:00")
time("08:00:00@Europe/Berlin")
@"08:00:00"
@"08:00:00+02:00"
@"08:00:00@Europe/Berlin"
date and time("2020-04-06T08:00:00")
date and time("2020-04-06T08:00:00+02:00")
date and time("2020-04-06T08:00:00@Europe/Berlin")
@"2020-04-06T08:00:00"
@"2020-04-06T08:00:00+02:00"
@"2020-04-06T08:00:00@Europe/Berlin"
duration("P5D")
duration("PT6H")
@"P5D"
@"PT6H"
duration("P1Y6M")
duration("P3M")
@"P1Y6M"
@"P3M"
The value is null if a date or date-time literal doesn't represent a valid calendar date. For example, @"2024-06-31" is invalid because June has only 30 days.
Addition
Adds a value to another value. The operator is defined for the following types.
If a value has a different type, the result is null.
| First argument | Second argument | Result |
|---|---|---|
| date | duration | date |
| time | days-time-duration | time |
| date-time | duration | date-time |
| duration | date | date |
| duration | time | time |
| duration | date-time | date-time |
| duration | duration | duration |
date("2020-04-06") + duration("P1D")
// date("2020-04-07")
time("08:00:00") + duration("PT1H")
// time("09:00:00")
date and time("2020-04-06T08:00:00") + duration("P7D")
// date and time("2020-04-13T08:00:00")
duration("P2D") + duration("P5D")
// duration("P7D")
Subtraction
Subtracts a value from another value. The operator is defined for the followings types.
If a value has a different type, the result is null.
If one value has a timezone or time-offset, the other value must have a timezone or time-offset too.
Otherwise, the result is null.
| First argument | Second argument | Result |
|---|---|---|
| date | date | days-time-duration |
| date | duration | date |
| time | time | days-time-duration |
| time | days-time-duration | time |
| date-time | date-time | days-time-duration |
| date-time | duration | date-time |
| days-time-duration | days-time-duration | days-time-duration |
| years-months-duration | years-months-duration | years-months-duration |
date("2020-04-06") - date("2020-04-01")
// duration("P5D")
date("2020-04-06") - duration("P5D")
// date("2020-04-01")
time("08:00:00") - time("06:00:00")
// duration("PT2H")
time("08:00:00") - duration("PT2H")
// time("06:00:00")
duration("P7D") - duration("P2D")
// duration("P5D")
duration("P1Y") - duration("P3M")
// duration("P9M")
Multiplication
Multiplies a value by another value. The operator is defined for the followings types.
If a value has a different type, the result is null.
| First argument | Second argument | Result |
|---|---|---|
| days-time-duration | number | days-time-duration |
| number | days-time-duration | days-time-duration |
| years-months-duration | number | years-months-duration |
| number | years-months-duration | years-months-duration |
duration("P1D") * 5
// duration("P5D")
duration("P1M") * 6
// duration("P6M")
Division
Divides a value by another value. The operator is defined for the followings types.
If a value has a different type, the result is null.
| First argument | Second argument | Result |
|---|---|---|
| days-time-duration | days-time-duration | number |
| days-time-duration | number | days-time-duration |
| years-months-duration | years-months-duration | number |
| years-months-duration | number | years-months-duration |
duration("P5D") / duration("P1D")
// 5
duration("P5D") / 5
// duration("P1D")
duration("P1Y") / duration("P1M")
// 12
duration("P1Y") / 12
// duration("P1M")
Properties
A temporal value has multiple properties for its components. The following properties are available for the given types:
| Property | Available for | Description |
|---|---|---|
| year | date, date-time | the year as number |
| month | date, date-time | the month as number [1..12], where 1 is January |
| day | date, date-time | the day of the month as number [1..31] |
| weekday | date, date-time | the day of the week as number [1..7], where 1 is Monday |
| hour | time, date-time | the hour of the day as number [0..23] |
| minute | time, date-time | the minute of the hour as number [0..59] |
| second | time, date-time | the second of the minute as number [0..59] |
| time offset | time, date-time | the duration offset corresponding to the timezone or null |
| timezone | time, date-time | the timezone identifier or null |
| days | days-time-duration | the normalized days component as number |
| hours | days-time-duration | the normalized hours component as number [0..23] |
| minutes | days-time-duration | the normalized minutes component as number [0..59] |
| seconds | days-time-duration | the normalized seconds component as number [0..59] |
| years | years-months-duration | the normalized years component as number |
| months | years-months-duration | the normalized months component as number [0..11] |
date("2020-04-06").year
// 2020
date("2020-04-06").month
// 4
date("2020-04-06").weekday
// 1
time("08:00:00").hour
// 8
date and time("2020-04-06T08:00:00+02:00").time offset
// duration("PT2H")
date and time("2020-04-06T08:00:00@Europe/Berlin").timezone
// "Europe/Berlin"
duration("PT2H30M").hours
// 2
duration("PT2H30M").minutes
// 30
duration("P6M").months
// 6