Operators are defined on the following type:
xs:duration
and on the two defined subtypes (see 8.1 Two totally ordered subtypes of duration):
xs:yearMonthDuration
xs:dayTimeDuration
No ordering relation is defined on xs:duration
values.
Two xs:duration
values may however be compared for equality.
Operations on durations (including equality comparison, casting to string, and extraction of components) all treat the duration as normalized. This means that the seconds and minutes components will always be less than 60, the hours component less than 24, and the months component less than 12. Thus, for example, a duration of 120 seconds always gives the same result as a duration of two minutes.
Conditions such as underflow and overflow may occur with arithmetic on durations: see 9.7.1 Limits and precision
Note:
This means that in practice, the information content of an xs:duration
value can be reduced to an xs:integer
number of months, and an xs:decimal
number of seconds. For the two defined subtypes this is further simplified so that one of these two
components is fixed at zero. Operations such as comparison of durations and arithmetic on durations
can be expressed in terms of numeric operations applied to these two components.
Two subtypes of xs:duration
, namely xs:yearMonthDuration
and xs:dayTimeDuration
, are defined in [Schema 1.1 Part 2]. These types must
be available in the data model whether or not the implementation supports other aspects of XSD 1.1.
The significance of these subtypes is that arithmetic and ordering become well defined; this is not the
case for xs:duration
values in general, because of the variable number of days in a month. For this reason, many of the functions
and operators on durations require the arguments/operands to belong to these two subtypes.
Function | Meaning |
---|---|
op:yearMonthDuration-less-than |
Returns true if $arg1 is a shorter duration than $arg2 . |
op:dayTimeDuration-less-than |
Returns true if $arg1 is a shorter duration than $arg2 . |
op:duration-equal |
Returns true if $arg1 and $arg2 are durations of the same
length. |
The following comparison operators are defined on the [XML Schema Part 2: Datatypes Second Edition]
duration datatypes. Each operator takes two operands of the same
type and returns an xs:boolean
result. As discussed in [XML Schema Part 2: Datatypes Second Edition], the
order relation on xs:duration
is a partial order rather than
a total order. For this reason, only equality is defined on xs:duration
.
A full complement of comparison and
arithmetic functions are defined on the two subtypes of duration described in
8.1 Two totally ordered subtypes of duration which do have a total order.
Returns true if $arg1
is a shorter duration than $arg2
.
Defines
the semantics of the "lt" operator when applied to two xs:yearMonthDuration
values. Also used in the definition of the "ge" operator.
op:yearMonthDuration-less-than ( |
||
$arg1 |
as xs:yearMonthDuration , |
|
$arg2 |
as xs:yearMonthDuration |
|
) as xs:boolean |
If the number of months in $arg1
is numerically less than the
number of months in $arg2
, the function returns true.
Otherwise, the function returns false.
Either or both durations may be negative.
Returns true if $arg1
is a shorter duration than $arg2
.
Defines the
semantics of the "lt" operator when applied to two xs:dayTimeDuration
values.
Also used in the definition of the "ge" operator.
op:dayTimeDuration-less-than ( |
||
$arg1 |
as xs:dayTimeDuration , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:boolean |
If the number of seconds in $arg1
is numerically less than the
number of seconds in $arg2
, the function returns true.
Otherwise, the function returns false.
Either or both durations may be negative
Returns true if $arg1
and $arg2
are durations of the same
length.
Defines the
semantics of the "eq" operators when applied to two xs:duration
values. Also
used in the definition of the "ne" operator.
op:duration-equal ( |
||
$arg1 |
as xs:duration , |
|
$arg2 |
as xs:duration |
|
) as xs:boolean |
If the xs:yearMonthDuration
components of $arg1
and
$arg2
are equal and the xs:dayTimeDuration
components of
$arg1
and $arg2
are equal, the function returns
true
.
Otherwise, the function returns false.
The semantics of this function are:
xs:yearMonthDuration($arg1) div xs:yearMonthDuration('P1M') eq xs:yearMonthDuration($arg2) div xs:yearMonthDuration('P1M') and xs:dayTimeDuration($arg1) div xs:dayTimeDuration('PT1S') eq xs:dayTimeDuration($arg2) div xs:dayTimeDuration('PT1S')
that is, the function returns true
if the months and seconds values of the
two durations are equal.
Note that this function, like any other, may be applied to arguments that are derived
from the types given in the function signature, including the two subtypes
xs:dayTimeDuration
and xs:yearMonthDuration
. With the
exception of the zero-length duration, no instance of xs:dayTimeDuration
can ever be equal to an instance of xs:yearMonthDuration
.
The expression op:duration-equal(xs:duration("P1Y"),
xs:duration("P12M"))
returns true()
.
The expression op:duration-equal(xs:duration("PT24H"),
xs:duration("P1D"))
returns true()
.
The expression op:duration-equal(xs:duration("P1Y"),
xs:duration("P365D"))
returns false()
.
The expression op:duration-equal(xs:yearMonthDuration("P0Y"),
xs:dayTimeDuration("P0D"))
returns true()
.
The expression op:duration-equal(xs:yearMonthDuration("P1Y"),
xs:dayTimeDuration("P365D"))
returns false()
.
The expression op:duration-equal(xs:yearMonthDuration("P2Y"),
xs:yearMonthDuration("P24M"))
returns true()
.
The expression op:duration-equal(xs:dayTimeDuration("P10D"),
xs:dayTimeDuration("PT240H"))
returns true()
.
The expression op:duration-equal(xs:duration("P2Y0M0DT0H0M0S"),
xs:yearMonthDuration("P24M"))
returns true()
.
The expression op:duration-equal(xs:duration("P0Y0M10D"),
xs:dayTimeDuration("PT240H"))
returns true()
.
The duration datatype may be considered to be a composite datatypes
in that it contains distinct properties or components. The extraction functions specified
below extract a single component from a duration value.
For xs:duration
and its subtypes, including the two subtypes xs:yearMonthDuration
and
xs:dayTimeDuration
, the components are normalized: this means that the seconds and minutes
components will always be less than 60, the hours component less than 24, and the months component less than 12.
Function | Meaning |
---|---|
fn:years-from-duration |
Returns the number of years in a duration. |
fn:months-from-duration |
Returns the number of months in a duration. |
fn:days-from-duration |
Returns the number of days in a duration. |
fn:hours-from-duration |
Returns the number of hours in a duration. |
fn:minutes-from-duration |
Returns the number of minutes in a duration. |
fn:seconds-from-duration |
Returns the number of seconds in a duration. |
Returns the number of years in a duration.
fn:years-from-duration ( |
||
$value |
as xs:duration? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the years
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($months idiv 12)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:dayTimeDuration
the function returns 0.
The expression fn:years-from-duration(xs:yearMonthDuration("P20Y15M"))
returns 21
.
The expression fn:years-from-duration(xs:yearMonthDuration("-P15M"))
returns -1
.
The expression fn:years-from-duration(xs:dayTimeDuration("-P2DT15H"))
returns 0
.
Returns the number of months in a duration.
fn:months-from-duration ( |
||
$value |
as xs:duration? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the months
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($months mod 12)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:dayTimeDuration
the function returns 0.
The expression fn:months-from-duration(xs:yearMonthDuration("P20Y15M"))
returns 3
.
The expression fn:months-from-duration(xs:yearMonthDuration("-P20Y18M"))
returns -6
.
The expression fn:months-from-duration(xs:dayTimeDuration("-P2DT15H0M0S"))
returns 0
.
Returns the number of days in a duration.
fn:days-from-duration ( |
||
$value |
as xs:duration? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the days
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is ($seconds idiv 86400)
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0.
The expression fn:days-from-duration(xs:dayTimeDuration("P3DT10H"))
returns 3
.
The expression fn:days-from-duration(xs:dayTimeDuration("P3DT55H"))
returns 5
.
The expression fn:days-from-duration(xs:yearMonthDuration("P3Y5M"))
returns 0
.
Returns the number of hours in a duration.
fn:hours-from-duration ( |
||
$value |
as xs:duration? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the hours
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 86400) idiv 3600
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0.
The expression fn:hours-from-duration(xs:dayTimeDuration("P3DT10H"))
returns 10
.
The expression fn:hours-from-duration(xs:dayTimeDuration("P3DT12H32M12S"))
returns 12
.
The expression fn:hours-from-duration(xs:dayTimeDuration("PT123H"))
returns 3
.
The expression fn:hours-from-duration(xs:dayTimeDuration("-P3DT10H"))
returns -10
.
Returns the number of minutes in a duration.
fn:minutes-from-duration ( |
||
$value |
as xs:duration? |
|
) as xs:integer? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:integer
representing the minutes
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 3600) idiv 60
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0.
The expression fn:minutes-from-duration(xs:dayTimeDuration("P3DT10H"))
returns 0
.
The expression fn:minutes-from-duration(xs:dayTimeDuration("-P5DT12H30M"))
returns -30
.
Returns the number of seconds in a duration.
fn:seconds-from-duration ( |
||
$value |
as xs:duration? |
|
) as xs:decimal? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns an xs:decimal
representing the seconds
component in $value
. Given that a duration
is a ($months, $seconds)
tuple, the result is the value of ($seconds mod 60)
as an xs:decimal
.
If $value
is a negative duration then the result will be negative.
If $value
is an xs:yearMonthDuration
the function returns 0.
The expression fn:seconds-from-duration(xs:dayTimeDuration("P3DT10H12.5S"))
returns 12.5
.
The expression fn:seconds-from-duration(xs:dayTimeDuration("-PT256S"))
returns -16.0
.
Function | Meaning |
---|---|
op:add-yearMonthDurations |
Returns the result of adding two xs:yearMonthDuration values. |
op:subtract-yearMonthDurations |
Returns the result of subtracting one xs:yearMonthDuration value from
another. |
op:multiply-yearMonthDuration |
Returns the result of multiplying $arg1 by $arg2 .
The result is rounded to the nearest month. |
op:divide-yearMonthDuration |
Returns the result of dividing $arg1 by $arg2 .
The result is rounded to the nearest month. |
op:divide-yearMonthDuration-by-yearMonthDuration |
Returns the ratio of two xs:yearMonthDuration values. |
op:add-dayTimeDurations |
Returns the sum of two xs:dayTimeDuration values. |
op:subtract-dayTimeDurations |
Returns the result of subtracting one xs:dayTimeDuration from another. |
op:multiply-dayTimeDuration |
Returns the result of multiplying a xs:dayTimeDuration by a number. |
op:divide-dayTimeDuration |
Returns the result of multiplying a xs:dayTimeDuration by a number. |
op:divide-dayTimeDuration-by-dayTimeDuration |
Returns the ratio of two xs:dayTimeDuration values, as a decimal
number. |
For operators that combine a duration and a date/time value, see 9.7 Arithmetic operators on durations, dates and times.
Returns the result of adding two xs:yearMonthDuration
values.
Defines the semantics of the
"+" operator when applied to two xs:yearMonthDuration
values.
op:add-yearMonthDurations ( |
||
$arg1 |
as xs:yearMonthDuration , |
|
$arg2 |
as xs:yearMonthDuration |
|
) as xs:yearMonthDuration |
The function returns the result of adding $arg1
to $arg2
.
The result will be an xs:yearMonthDuration
whose
length in months is equal to the length in months of $arg1
plus the length
in months of $arg2
.
For handling of overflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression op:add-yearMonthDurations(xs:yearMonthDuration("P2Y11M"),
xs:yearMonthDuration("P3Y3M"))
returns xs:yearMonthDuration("P6Y2M")
.
Returns the result of subtracting one xs:yearMonthDuration
value from
another.
Defines the semantics of the
"-" operator when applied to two xs:yearMonthDuration
values.
op:subtract-yearMonthDurations ( |
||
$arg1 |
as xs:yearMonthDuration , |
|
$arg2 |
as xs:yearMonthDuration |
|
) as xs:yearMonthDuration |
The function returns the result of subtracting $arg2
from
$arg1
. The result will be an xs:yearMonthDuration
whose length in months is equal to the length in months of $arg1
minus the
length in months of $arg2
.
For handling of overflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression op:subtract-yearMonthDurations(xs:yearMonthDuration("P2Y11M"),
xs:yearMonthDuration("P3Y3M"))
returns xs:yearMonthDuration("-P4M")
.
Returns the result of multiplying $arg1
by $arg2
.
The result is rounded to the nearest month.
Defines the semantics of the
"*" operator when applied to an xs:yearMonthDuration
and a numeric
value.
op:multiply-yearMonthDuration ( |
||
$arg1 |
as xs:yearMonthDuration , |
|
$arg2 |
as xs:double |
|
) as xs:yearMonthDuration |
The result is the xs:yearMonthDuration
whose length in months is equal to
the result of applying the fn:round
function to the value obtained by
multiplying the length in months of $arg1
by the value of
$arg2
.
If $arg2
is positive or negative zero, the result is a zero-length
duration. If $arg2
is positive or negative infinity, the result overflows
and is handled as described in 9.7.1 Limits and precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
Either duration (and therefore the result) may be negative.
The expression op:multiply-yearMonthDuration(xs:yearMonthDuration("P2Y11M"),
2.3)
returns xs:yearMonthDuration("P6Y9M")
.
Returns the result of dividing $arg1
by $arg2
.
The result is rounded to the nearest month.
Defines the semantics of the
"div" operator when applied to an xs:yearMonthDuration
and a numeric
value.
op:divide-yearMonthDuration ( |
||
$arg1 |
as xs:yearMonthDuration , |
|
$arg2 |
as xs:double |
|
) as xs:yearMonthDuration |
The result is the xs:yearMonthDuration
whose length in months is equal to
the result of applying the fn:round
function to the value obtained by
dividing the length in months of $arg1
by the value of
$arg2
.
If $arg2
is positive or negative infinity, the result is a zero-length
duration. If $arg2
is positive or negative zero, the result overflows and
is handled as described in 9.7.1 Limits and precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
The expression op:divide-yearMonthDuration(xs:yearMonthDuration("P2Y11M"),
1.5)
returns xs:yearMonthDuration("P1Y11M")
.
Returns the ratio of two xs:yearMonthDuration
values.
Defines the semantics of the
"div" operator when applied to two xs:yearMonthDuration
values.
op:divide-yearMonthDuration-by-yearMonthDuration ( |
||
$arg1 |
as xs:yearMonthDuration , |
|
$arg2 |
as xs:yearMonthDuration |
|
) as xs:decimal |
The function returns the result of dividing the length in months of $arg1
by the length in months of $arg2
, according to the rules of the
op:numeric-divide
function for integer operands.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression op:divide-yearMonthDuration-by-yearMonthDuration(xs:yearMonthDuration("P3Y4M"),
xs:yearMonthDuration("-P1Y4M"))
returns -2.5
.
The following example demonstrates how to calculate the length of an
xs:yearMonthDuration
value in months:
The expression op:divide-yearMonthDuration-by-yearMonthDuration(xs:yearMonthDuration("P3Y4M"),
xs:yearMonthDuration("P1M"))
returns 40
.
Returns the sum of two xs:dayTimeDuration
values.
Defines the semantics of the "+"
operator when applied to two xs:dayTimeDuration
values.
op:add-dayTimeDurations ( |
||
$arg1 |
as xs:dayTimeDuration , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:dayTimeDuration |
The function returns the result of adding $arg1
to
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the sum of the length in seconds of the two input durations.
For handling of overflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression op:add-dayTimeDurations(xs:dayTimeDuration("P2DT12H5M"),
xs:dayTimeDuration("P5DT12H"))
returns xs:dayTimeDuration('P8DT5M')
.
Returns the result of subtracting one xs:dayTimeDuration
from another.
Defines the semantics of the "-"
operator when applied to two xs:dayTimeDuration
values.
op:subtract-dayTimeDurations ( |
||
$arg1 |
as xs:dayTimeDuration , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:dayTimeDuration |
The function returns the result of subtracting $arg2
from
$arg1
. The result is the xs:dayTimeDuration
whose
length in seconds is equal to the length in seconds of $arg1
minus the
length in seconds of $arg2
.
For handling of overflow, see 9.7.1 Limits and precision.
Either duration (and therefore the result) may be negative.
The expression op:subtract-dayTimeDurations(xs:dayTimeDuration("P2DT12H"),
xs:dayTimeDuration("P1DT10H30M"))
returns xs:dayTimeDuration('P1DT1H30M')
.
Returns the result of multiplying a xs:dayTimeDuration
by a number.
Defines the semantics of the "*"
operator when applied to an xs:dayTimeDuration
and a numeric
value.
op:multiply-dayTimeDuration ( |
||
$arg1 |
as xs:dayTimeDuration , |
|
$arg2 |
as xs:double |
|
) as xs:dayTimeDuration |
The function returns the result of multiplying $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
multiplied by the
numeric value $arg2
.
If $arg2
is positive or negative zero, the result is a zero-length
duration. If $arg2
is positive or negative infinity, the result overflows
and is handled as described in 9.1.1 Limits and precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
The expression op:multiply-dayTimeDuration(xs:dayTimeDuration("PT2H10M"),
2.1)
returns xs:dayTimeDuration('PT4H33M')
.
Returns the result of multiplying a xs:dayTimeDuration
by a number.
Defines the semantics of the
"div" operator when applied to two xs:dayTimeDuration
values.
op:divide-dayTimeDuration ( |
||
$arg1 |
as xs:dayTimeDuration , |
|
$arg2 |
as xs:double |
|
) as xs:dayTimeDuration |
The function returns the result of dividing $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
divided by the numeric
value $arg2
.
If $arg2
is positive or negative infinity, the result is a zero-length
duration. If $arg2
is positive or negative zero, the result overflows and
is handled as described in 9.1.1 Limits and precision.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
A dynamic error is raised [err:FOCA0005] if $arg2
is
NaN
.
Either operand (and therefore the result) may be negative.
The expression op:divide-dayTimeDuration(xs:dayTimeDuration("P1DT2H30M10.5S"),
1.5)
returns xs:duration("PT17H40M7S")
.
Returns the ratio of two xs:dayTimeDuration
values, as a decimal
number.
Defines the semantics of the
"div" operator when applied to two xs:dayTimeDuration
values.
op:divide-dayTimeDuration-by-dayTimeDuration ( |
||
$arg1 |
as xs:dayTimeDuration , |
|
$arg2 |
as xs:dayTimeDuration |
|
) as xs:decimal |
The function returns the result of dividing $arg1
by
$arg2
. The result is the xs:dayTimeDuration
whose length in
seconds is equal to the length in seconds of $arg1
divided by the length in
seconds of $arg2
. The calculation is performed by applying
op:numeric-divide
to the two xs:decimal
operands.
For handling of overflow and underflow, see 9.7.1 Limits and precision.
Either operand (and therefore the result) may be negative.
The expression fn:round-half-to-even( op:divide-dayTimeDuration-by-dayTimeDuration(
xs:dayTimeDuration("P2DT53M11S"), xs:dayTimeDuration("P1DT10H")),
4)
returns 1.4378
.
This examples shows how to determine the number of seconds in a duration.
The expression op:divide-dayTimeDuration-by-dayTimeDuration(xs:dayTimeDuration("P2DT53M11S"),
xs:dayTimeDuration("PT1S"))
returns 175991.0
.