8 Functions and operators on durations

Operators are defined on the following type:

and on the two defined subtypes (see 8.1 Two totally ordered subtypes of duration):

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.

8.1 Two totally ordered subtypes of duration

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.

8.2 Comparison operators on durations

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.

8.2.1 op:yearMonthDuration-less-than

Summary

Returns true if $arg1 is a shorter duration than $arg2.

Operator Mapping

Defines the semantics of the "lt" operator when applied to two xs:yearMonthDuration values. Also used in the definition of the "ge" operator.

Signature
op:yearMonthDuration-less-than(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:yearMonthDuration
) as xs:boolean
Rules

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.

Notes

Either or both durations may be negative.

8.2.2 op:dayTimeDuration-less-than

Summary

Returns true if $arg1 is a shorter duration than $arg2.

Operator Mapping

Defines the semantics of the "lt" operator when applied to two xs:dayTimeDuration values. Also used in the definition of the "ge" operator.

Signature
op:dayTimeDuration-less-than(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:dayTimeDuration
) as xs:boolean
Rules

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.

Notes

Either or both durations may be negative

8.2.3 op:duration-equal

Summary

Returns true if $arg1 and $arg2 are durations of the same length.

Operator Mapping

Defines the semantics of the "eq" operators when applied to two xs:duration values. Also used in the definition of the "ne" operator.

Signature
op:duration-equal(
$arg1 as xs:duration,
$arg2 as xs:duration
) as xs:boolean
Rules

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.

Notes

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.

Examples

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().

8.3 Component extraction functions on durations

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.

8.3.1 fn:years-from-duration

Summary

Returns the number of years in a duration.

Signature
fn:years-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples

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.

8.3.2 fn:months-from-duration

Summary

Returns the number of months in a duration.

Signature
fn:months-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples

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.

8.3.3 fn:days-from-duration

Summary

Returns the number of days in a duration.

Signature
fn:days-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples

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.

8.3.4 fn:hours-from-duration

Summary

Returns the number of hours in a duration.

Signature
fn:hours-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples

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.

8.3.5 fn:minutes-from-duration

Summary

Returns the number of minutes in a duration.

Signature
fn:minutes-from-duration(
$value as xs:duration?
) as xs:integer?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples

The expression fn:minutes-from-duration(xs:dayTimeDuration("P3DT10H")) returns 0.

The expression fn:minutes-from-duration(xs:dayTimeDuration("-P5DT12H30M")) returns -30.

8.3.6 fn:seconds-from-duration

Summary

Returns the number of seconds in a duration.

Signature
fn:seconds-from-duration(
$value as xs:duration?
) as xs:decimal?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Examples

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.

8.4 Arithmetic operators on durations

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.

8.4.1 op:add-yearMonthDurations

Summary

Returns the result of adding two xs:yearMonthDuration values.

Operator Mapping

Defines the semantics of the "+" operator when applied to two xs:yearMonthDuration values.

Signature
op:add-yearMonthDurations(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:yearMonthDuration
) as xs:yearMonthDuration
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:add-yearMonthDurations(xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M")) returns xs:yearMonthDuration("P6Y2M").

8.4.2 op:subtract-yearMonthDurations

Summary

Returns the result of subtracting one xs:yearMonthDuration value from another.

Operator Mapping

Defines the semantics of the "-" operator when applied to two xs:yearMonthDuration values.

Signature
op:subtract-yearMonthDurations(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:yearMonthDuration
) as xs:yearMonthDuration
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:subtract-yearMonthDurations(xs:yearMonthDuration("P2Y11M"), xs:yearMonthDuration("P3Y3M")) returns xs:yearMonthDuration("-P4M").

8.4.3 op:multiply-yearMonthDuration

Summary

Returns the result of multiplying $arg1 by $arg2. The result is rounded to the nearest month.

Operator Mapping

Defines the semantics of the "*" operator when applied to an xs:yearMonthDuration and a numeric value.

Signature
op:multiply-yearMonthDuration(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:double
) as xs:yearMonthDuration
Rules

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.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:multiply-yearMonthDuration(xs:yearMonthDuration("P2Y11M"), 2.3) returns xs:yearMonthDuration("P6Y9M").

8.4.4 op:divide-yearMonthDuration

Summary

Returns the result of dividing $arg1 by $arg2. The result is rounded to the nearest month.

Operator Mapping

Defines the semantics of the "div" operator when applied to an xs:yearMonthDuration and a numeric value.

Signature
op:divide-yearMonthDuration(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:double
) as xs:yearMonthDuration
Rules

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.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either operand (and therefore the result) may be negative.

Examples

The expression op:divide-yearMonthDuration(xs:yearMonthDuration("P2Y11M"), 1.5) returns xs:yearMonthDuration("P1Y11M").

8.4.5 op:divide-yearMonthDuration-by-yearMonthDuration

Summary

Returns the ratio of two xs:yearMonthDuration values.

Operator Mapping

Defines the semantics of the "div" operator when applied to two xs:yearMonthDuration values.

Signature
op:divide-yearMonthDuration-by-yearMonthDuration(
$arg1 as xs:yearMonthDuration,
$arg2 as xs:yearMonthDuration
) as xs:decimal
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples

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.

8.4.6 op:add-dayTimeDurations

Summary

Returns the sum of two xs:dayTimeDuration values.

Operator Mapping

Defines the semantics of the "+" operator when applied to two xs:dayTimeDuration values.

Signature
op:add-dayTimeDurations(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:dayTimeDuration
) as xs:dayTimeDuration
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:add-dayTimeDurations(xs:dayTimeDuration("P2DT12H5M"), xs:dayTimeDuration("P5DT12H")) returns xs:dayTimeDuration('P8DT5M').

8.4.7 op:subtract-dayTimeDurations

Summary

Returns the result of subtracting one xs:dayTimeDuration from another.

Operator Mapping

Defines the semantics of the "-" operator when applied to two xs:dayTimeDuration values.

Signature
op:subtract-dayTimeDurations(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:dayTimeDuration
) as xs:dayTimeDuration
Rules

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.

Notes

Either duration (and therefore the result) may be negative.

Examples

The expression op:subtract-dayTimeDurations(xs:dayTimeDuration("P2DT12H"), xs:dayTimeDuration("P1DT10H30M")) returns xs:dayTimeDuration('P1DT1H30M').

8.4.8 op:multiply-dayTimeDuration

Summary

Returns the result of multiplying a xs:dayTimeDuration by a number.

Operator Mapping

Defines the semantics of the "*" operator when applied to an xs:dayTimeDuration and a numeric value.

Signature
op:multiply-dayTimeDuration(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:double
) as xs:dayTimeDuration
Rules

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.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either operand (and therefore the result) may be negative.

Examples

The expression op:multiply-dayTimeDuration(xs:dayTimeDuration("PT2H10M"), 2.1) returns xs:dayTimeDuration('PT4H33M').

8.4.9 op:divide-dayTimeDuration

Summary

Returns the result of multiplying a xs:dayTimeDuration by a number.

Operator Mapping

Defines the semantics of the "div" operator when applied to two xs:dayTimeDuration values.

Signature
op:divide-dayTimeDuration(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:double
) as xs:dayTimeDuration
Rules

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.

Error Conditions

A dynamic error is raised [err:FOCA0005] if $arg2 is NaN.

Notes

Either operand (and therefore the result) may be negative.

Examples

The expression op:divide-dayTimeDuration(xs:dayTimeDuration("P1DT2H30M10.5S"), 1.5) returns xs:duration("PT17H40M7S").

8.4.10 op:divide-dayTimeDuration-by-dayTimeDuration

Summary

Returns the ratio of two xs:dayTimeDuration values, as a decimal number.

Operator Mapping

Defines the semantics of the "div" operator when applied to two xs:dayTimeDuration values.

Signature
op:divide-dayTimeDuration-by-dayTimeDuration(
$arg1 as xs:dayTimeDuration,
$arg2 as xs:dayTimeDuration
) as xs:decimal
Rules

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.

Notes

Either operand (and therefore the result) may be negative.

Examples

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.