Skip to main content
Version: 8.4

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 followings types.

If a value has a different type, the result is null.

First argumentSecond argumentResult
datedurationdate
timedays-time-durationtime
date-timedurationdate-time
durationdatedate
durationtimetime
durationdate-timedate-time
durationdurationduration
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 argumentSecond argumentResult
datedatedays-time-duration
datedurationdate
timetimedays-time-duration
timedays-time-durationtime
date-timedate-timedays-time-duration
date-timedurationdate-time
days-time-durationdays-time-durationdays-time-duration
years-months-durationyears-months-durationyears-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 argumentSecond argumentResult
days-time-durationnumberdays-time-duration
numberdays-time-durationdays-time-duration
years-months-durationnumberyears-months-duration
numberyears-months-durationyears-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 argumentSecond argumentResult
days-time-durationdays-time-durationnumber
days-time-durationnumberdays-time-duration
years-months-durationyears-months-durationnumber
years-months-durationnumberyears-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:

PropertyAvailable forDescription
yeardate, date-timethe year as number
monthdate, date-timethe month as number [1..12], where 1 is January
daydate, date-timethe day of the month as number [1..31]
weekdaydate, date-timethe day of the week as number [1..7], where 1 is Monday
hourtime, date-timethe hour of the day as number [0..23]
minutetime, date-timethe minute of the hour as number [0..59]
secondtime, date-timethe second of the minute as number [0..59]
time offsettime, date-timethe duration offset corresponding to the timezone or null
timezonetime, date-timethe timezone identifier or null
daysdays-time-durationthe normalized days component as number
hoursdays-time-durationthe normalized hours component as number [0..23]
minutesdays-time-durationthe normalized minutes component as number [0..59]
secondsdays-time-durationthe normalized seconds component as number [0..59]
yearsyears-months-durationthe normalized years component as number
monthsyears-months-durationthe 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