Comparison Operators on Duration, Date and Time Values
| Operator |
Meaning |
op:yearMonthDuration-less-than
|
Less-than comparison on xs:yearMonthDuration values |
op:yearMonthDuration-greater-than
|
Greater-than comparison on xs:yearMonthDuration values |
op:dayTimeDuration-less-than
|
Less-than comparison on xs:dayTimeDuration values |
op:dayTimeDuration-greater-than
|
Greater-than comparison on xs:dayTimeDuration values |
op:duration-equal
|
Equality comparison on xs:duration values |
op:dateTime-equal
|
Equality comparison on xs:dateTime values |
op:dateTime-less-than
|
Less-than comparison on xs:dateTime values |
op:dateTime-greater-than
|
Greater-than comparison on xs:dateTime values |
op:date-equal
|
Equality comparison on xs:date values |
op:date-less-than
|
Less-than comparison on xs:date values |
op:date-greater-than
|
Greater-than comparison on xs:date values |
op:time-equal
|
Equality comparison on xs:time values |
op:time-less-than
|
Less-than comparison on xs:time values |
op:time-greater-than
|
Greater-than comparison on xs:time values |
op:gYearMonth-equal
|
Equality comparison on xs:gYearMonth values |
op:gYear-equal
|
Equality comparison on xs:gYear values |
op:gMonthDay-equal
|
Equality comparison on xs:gMonthDay values |
op:gMonth-equal
|
Equality comparison on xs:gMonth values |
op:gDay-equal
|
Equality comparison on xs:gDay values |
The following comparison operators are defined on the
date, time and duration datatypes. Each operator takes two operands of the same
type and returns an xs:boolean result. As discussed in , the
order relation on xs:duration is
not a total order but, rather, a partial 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
which do have a total order.
also states that the
order relation on date and time datatypes is
not a total order but a partial order because these
datatypes may or may not have a timezone. This is handled as follows.
If either operand to a comparison function on date or time values does not have
an (explicit) timezone then, for the purpose of the operation, an implicit
timezone, provided by the dynamic context , is assumed to be present as part of
the value. This creates a total order for all date and time values.
An xs:dateTime can be considered to consist of seven components:
year, month, day, hour, minute, second and timezone. For xs:dateTime six components: year, month, day, hour, minute and second are required and timezone is optional. For other date/time values, of the first six components, some are required and others must be absent or missing. Timezone is always optional. For example, for xs:date, the year, month and day components are required and hour, minute and second components must be absent; for xs:time the hour, minute and second components are required and year, month and day are missing; for xs:gDay, day is required and year, month, hour, minute and second are missing.
Values of the date/time datatypes xs:time, xs:gMonthDay, xs:gMonth, and xs:gDay, can be considered to represent a sequence of recurring time instants or time periods. An xs:time occurs every day. An xs:gMonth occurs every year. Comparison operators on these datatypes compare the starting instants of equivalent occurrences in the recurring series. These xs:dateTime values are calculated as described below.
Comparison operators on xs:date, xs:gYearMonth and xs:gYear compare their starting instants. These xs:dateTime values are calculated as described below.
The starting instant of an occurrence of a date/time value is an xs:dateTime calculated by filling in the missing components of the local value from a reference xs:dateTime. If the value filled in for a missing day component exceeds the maximum day value for the month, the last day of the month is used. Suppose, for example, that the reference xs:dateTime is 1972-12-31T00:00:00 and the xs:date value to be compared is 1993-03-31. Filling in the time components from the reference xs:dateTime we get 1993-03-31T00:00:00 which is the starting instant of that day. Similarly, if the xs:time value 12:30:00 is to be compared, we fill in the missing components from the reference xs:dateTime and we get 1972-12-31T12:30:00 which is the time on that day. For an xs:gYearMonth value of 1976-02 we fill in the missing components, adjust for the last day in the month and get 1976-02-29T00:00:00.
If the xs:time value written as
24:00:00 is to be compared, filling in the missing components gives 1972-12-31T00:00:00, because 24:00:00 is an alternative representation of 00:00:00 (the lexical value "24:00:00" is
converted to the time components {0,0,0} before the missing components are filled
in). This has the consequence that when ordering xs:time values,
24:00:00 is
considered to be earlier than 23:59:59. However, when ordering
xs:dateTime
values, a time component of 24:00:00 is considered equivalent to 00:00:00 on the
following day.
Note that the reference xs:dateTime does not have a timezone. The timezone component is never filled in from the reference xs:dateTime. In some cases, if the date/time value does not have a timezone, the implicit timezone from the dynamic context is used as the timezone.
This proposal uses the reference xs:dateTime 1972-12-31T00:00:00 in the description of the comparison operators. Implementations are allowed to use other reference xs:dateTime values as long as they yield the same results. The reference xs:dateTime used must meet the following constraints: when it is used to supply components into xs:gMonthDay values, the year must allow for February 29 and so must be a leap year; when it is used to supply missing components into xs:gDay values, the month must allow for 31 days. Different reference xs:dateTime values may be used for different operators.
op:yearMonthDuration-less-than
Summary: Returns true if and only if $arg1 is less
than $arg2. Returns false otherwise.
This function backs up the "lt" and "le" operators on
xs:yearMonthDuration values.
op:yearMonthDuration-greater-than
Summary: Returns true if and only if $arg1 is
greater than $arg2. Returns false otherwise.
This function backs up the "gt" and "ge" operators on
xs:yearMonthDuration values.
op:dayTimeDuration-less-than
Summary: Returns true if and only if $arg1 is less
than $arg2. Returns false otherwise.
This function backs up the "lt" and "le" operators on
xs:dayTimeDuration values.
op:dayTimeDuration-greater-than
Summary: Returns true if and only if $arg1 is
greater than $arg2. Returns false otherwise.
This function backs up the "gt" and "ge" operators on
xs:dayTimeDuration values.
op:duration-equal
Summary:
Returns true if and only if the
xs:yearMonthDuration and the xs:dayTimeDuration
components of $arg1 and $arg2 compare equal respectively.
Returns false otherwise.
This function backs up the "eq" and "ne" operators on
xs:duration values.
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 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.
Examples
op:duration-equal(xs:duration("P1Y"), xs:duration("P12M")) returns true.
op:duration-equal(xs:duration("PT24H"), xs:duration("P1D")) returns true.
op:duration-equal(xs:duration("P1Y"), xs:duration("P365D")) returns false.
op:duration-equal(xs:yearMonthDuration("P0Y"), xs:dayTimeDuration("PT0D")) returns true.
op:duration-equal(xs:yearMonthDuration("P1Y"), xs:dayTimeDuration("PT365D")) returns false.
op:duration-equal(xs:yearMonthDuration("P2Y"), xs:yearMonthDuration("P24M")) returns true.
op:duration-equal(xs:dayTimeDuration("PT10D"), xs:dayTimeDuration("PT240H")) returns true.
op:duration-equal(xs:duration("P2Y0M0DT0H0M0S"), xs:yearMonthDuration("P24M")) returns true.
op:duration-equal(xs:duration("P0Y0M10D"), xs:dayTimeDuration("PT240H")) returns true.
Summary:
Returns true if and only if the value of
$arg1 is equal to the value of $arg2 according to the algorithm defined in section 3.2.7.4 of Order relation on dateTime
for xs:dateTime values with timezones.
Returns false otherwise.
This function backs up the "eq", "ne", "le" and "ge" operators on
xs:dateTime values.
Examples
Assume that the dynamic context provides an implicit timezone value of -05:00.
-
op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00-01:00"),
xs:dateTime("2002-04-02T17:00:00+04:00")) returns true.
-
op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T23:00:00+06:00")) returns true.
-
op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T17:00:00")) returns false.
-
op:dateTime-equal(xs:dateTime("2002-04-02T12:00:00"),
xs:dateTime("2002-04-02T12:00:00")) returns true.
-
op:dateTime-equal(xs:dateTime("2002-04-02T23:00:00-04:00"),
xs:dateTime("2002-04-03T02:00:00-01:00")) returns true.
-
op:dateTime-equal(xs:dateTime("1999-12-31T24:00:00"),
xs:dateTime("2000-01-01T00:00:00")) returns true.
-
op:dateTime-equal(xs:dateTime("2005-04-04T24:00:00"),
xs:dateTime("2005-04-04T00:00:00")) returns false.
op:dateTime-less-than
Summary: Returns true if and only if the value of
$arg1 is less than the value of $arg2 according to the algorithm defined in section 3.2.7.4 of Order relation on dateTime
for xs:dateTime values with timezones.
Returns false otherwise.
This function backs up the "lt" and "le" operators on
xs:dateTime values.
op:dateTime-greater-than
Summary: Returns true if and only if the value of
$arg1 is greater than the value of $arg2 according to the algorithm defined in section 3.2.7.4 of Order relation on dateTime
for xs:dateTime values with timezones.
Returns false otherwise.
This function backs up the "gt" and "ge" operators on
xs:dateTime values.
op:date-equal
Summary: Returns true if and only if the starting instant of
$arg1 is equal to starting instant of $arg2.
Returns false otherwise.
The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.
The two starting instants are compared using op:dateTime-equal.
This function backs up the "eq", "ne", "le" and "ge" operators on xs:date values.
Examples
-
op:date-equal(xs:date("2004-12-25Z"),
xs:date("2004-12-25+07:00")) returns false. The starting instants are xs:dateTime("2004-12-25T00:00:00Z") and xs:dateTime("2004-12-25T00:00:00+07:00"). These are normalized to xs:dateTime("2004-12-25T00:00:00Z") and xs:dateTime("2004-12-24T17:00:00Z").
-
op:date-equal(xs:date("2004-12-25-12:00"),
xs:date("2004-12-26+12:00")) returns true.
op:date-less-than
Summary: Returns true if and only if the starting instant of
$arg1 is less than the starting instant of $arg2.
Returns false otherwise.
The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.
The two starting instants are compared using op:dateTime-less-than.
This function backs up the "lt" and "le" operators on xs:date values.
Examples
-
op:date-less-than(xs:date("2004-12-25Z"),
xs:date("2004-12-25-05:00")) returns true.
-
op:date-less-than(xs:date("2004-12-25-12:00"),
xs:date("2004-12-26+12:00")) returns false.
op:date-greater-than
Summary: Returns true if and only if the starting instant of
$arg1 is greater than the starting instant of $arg2. Returns false otherwise.
The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.
The two starting instants are compared using op:dateTime-greater-than.
This function backs up the "gt" and "ge" operators on xs:date values.
Examples
-
op:date-greater-than(xs:date("2004-12-25Z"),
xs:date("2004-12-25+07:00")) returns true.
-
op:date-greater-than(xs:date("2004-12-25-12:00"),
xs:date("2004-12-26+12:00")) returns false.
op:time-equal
Summary: Returns true if and only if the value of
$arg1 converted to an xs:dateTime using the date components from the reference xs:dateTime is equal to the value of $arg2 converted to an xs:dateTime using the date components from the same reference xs:dateTime.
Returns false otherwise.
The two xs:dateTime values are compared using op:dateTime-equal.
This function backs up the "eq", "ne", "le" and "ge" operators on xs:time values.
Examples
Assume that the date components from the reference xs:dateTime correspond to 1972-12-31.
-
op:time-equal(xs:time("08:00:00+09:00"),
xs:time("17:00:00-06:00")) returns false. The xs:dateTimes calculated using the reference date components are 1972-12-31T08:00:00+09:00 and 1972-12-31T17:00:00-06:00.
These normalize to 1972-12-30T23:00:00Z and 1972-12-31T23:00:00.
-
op:time-equal(xs:time("21:30:00+10:30"),
xs:time("06:00:00-05:00")) returns true.
-
op:time-equal(xs:time("24:00:00+01:00"), xs:time("00:00:00+01:00")) returns true.
op:time-less-than
Summary: Returns true if and only if the value of
$arg1 converted to an xs:dateTime using the date components from the reference xs:dateTime is less than the normalized value of $arg2 converted to an xs:dateTime using the date components from the same reference xs:dateTime.
Returns false otherwise.
The two xs:dateTime values are compared using op:dateTime-less-than.
This function backs up the "lt" and "le" operators on xs:time values.
Examples
Assume that the dynamic context provides an implicit timezone value of -05:00.
-
op:time-less-than(xs:time("12:00:00"),
xs:time("23:00:00+06:00")) returns false.
-
op:time-less-than(xs:time("11:00:00"),
xs:time("17:00:00Z")) returns true.
-
op:time-less-than(xs:time("23:59:59"), xs:time("24:00:00")) returns false.
op:time-greater-than
Summary: Returns true if and only if the value of
$arg1 converted to an xs:dateTime using the date components from the reference xs:dateTime is greater than the value of
$arg2 converted to an xs:dateTime using the date components from the same reference xs:dateTime. Returns false otherwise.
The two xs:dateTime values are compared using op:dateTime-greater-than.
This function backs up the "gt" and "ge" operators on xs:time values.
Examples
-
op:time-greater-than(xs:time("08:00:00+09:00"),
xs:time("17:00:00-06:00")) returns false.
op:gYearMonth-equal
Summary: Returns true if and only if the xs:dateTimes representing the starting instants of $arg1 and $arg2 compare equal. The starting instants of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from the xs:dateTime template xxxx-xx-ddT00:00:00 where dd represents the last day of the month component in $arg1 or $arg2. Returns false otherwise.
The two xs:dateTime values representing the starting instants of $arg1 and $arg2 are compared using op:dateTime-equal.
This function backs up the "eq" and "ne" operators on
xs:gYearMonth values.
Examples
Assume that the dynamic context provides an implicit timezone value of -05:00.
-
op:gYearMonth-equal(xs:gYearMonth("1976-02"),
xs:gYearMonth("1976-03Z")) returns false. The starting instants are 1972-02-29T00:00:00-05:00 and 1972-03-31T00:00:00Z, respectively.
-
op:gYearMonth-equal(xs:gYearMonth("1976-03"),
xs:gYearMonth("1976-03Z")) returns false.
op:gYear-equal
Summary: Returns true if and only if the xs:dateTimes representing the starting instants of $arg1 and $arg2 compare equal. The starting instants of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from a xs:dateTime template such as xxxx-01-01T00:00:00. Returns false otherwise.
The two xs:dateTime values representing the starting instants of $arg1 and $arg2 are compared using op:dateTime-equal.
This function backs up the "eq" and "ne" operators on xs:gYear values.
Examples
Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is xxxx-01-01T00:00:00.
-
op:gYear-equal(xs:gYear("2005-12:00"),
xs:gYear("2005+12:00")) returns false. The starting instants are 2005-01-01T00:00:00-12:00 and 2005-01-01T00:00:00+12:00, respectively, and normalize to 2005-01-015T12:00:00Z and 2004-12-31T12:00:00Z.
-
op:gYear-equal(xs:gYear("1976-05:00"),
xs:gYear("1976")) returns true.
op:gMonthDay-equal
Summary: Summary: Returns true if and only if the xs:dateTimes representing the starting instants of equivalent occurrences of $arg1 and $arg2 compare equal. The starting instants of equivalent occurrences of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from an xs:dateTime template such as 1972-xx-xxT00:00:00. Returns false otherwise.
The two xs:dateTime values representing the starting instants of equivalent occurrences of $arg1 and $arg2 are compared using op:dateTime-equal.
This function backs up the "eq" and "ne" operators on
xs:gMonthDay values.
Examples
Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is 1976-xx-xxT00:00:00.
-
op:gMonthDay-equal(xs:gMonthDay("--12-25-14:00"),
xs:gMonthDay("--12-26+10:00")) returns true. The starting instants are 1976-12-25T00:00:00-14:00 and 1976-12-26T00:00:00+10:00, respectively, and normalize to 1976-12-25T14:00:00Z and 1976-12-25T14:00:00Z.
-
op:gMonthDay-equal(xs:gMonthDay("--12-25"),
xs:gMonthDay("--12-26Z")) returns false.
op:gMonth-equal
Summary: Returns true if and only if the xs:dateTimes representing the starting instants of equivalent occurrences of $arg1 and $arg2 compare equal. The starting instants of equivalent occurrences of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from an xs:dateTime template such as 1972-xx-ddT00:00:00 where dd represents the last day of the month component in $arg1 or $arg2. Returns false otherwise.
The two xs:dateTime values representing the starting instants of equivalent occurrences of $arg1 and $arg2 are compared using op:dateTime-equal.
This function backs up the "eq" and "ne" operators on xs:gMonth values.
Examples
Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is 1972-xx-29T00:00:00.
-
op:gMonth-equal(xs:gMonth("--12-14:00"),
xs:gMonth("--12+10:00") returns false. The starting instants are 1972-12-29T00:00:00-14:00 and 1972-12-29T00:00:00+10:00, respectively, and normalize to 1972-12-29T14:00:00Z and 1972-12-28T14:00:00Z.
-
op:gMonth-equal(xs:gMonth("--12"),
xs:gMonth("--12Z")) returns false.
op:gDay-equal
Summary: Returns true if and only if the xs:dateTimes representing the starting instants of equivalent occurrences of $arg1 and $arg2 compare equal. The starting instants of equivalent occurrences of $arg1 and $arg2 are calculated by adding the missing components of $arg1 and $arg2 from an xs:dateTime template such as 1972-12-xxT00:00:00. Returns false otherwise.
The two xs:dateTime values representing the starting instants of equivalent occurrences of $arg1 and $arg2 are compared using op:dateTime-equal.
This function backs up the "eq" and "ne" operators on xs:gDay values.
Examples
Assume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the xs:dateTime template is 1976-12-xxT00:00:00.
-
op:gDay-equal(xs:gDay("---25-14:00"),
xs:gDay("---25+10:00")) returns false. The starting instants are 1972-12-25T00:00:00-14:00 and 1972-12-25T00:00:00+10:00, respectively, and normalize to 1972-12-25T14:00:00Z and 1972-12-24T14:00:00Z.
-
op:gDay-equal(xs:gDay("---12"),
xs:gDay("---12Z")) returns false.
Component Extraction Functions on Durations, Dates and Times
The duration, date and time datatypes may be considered to be composite datatypes
in that they contain distinct properties or components. The extraction functions specified
below extract a single component from a duration, date or time value. For
the date/time datatypes the local value is used.
| Function |
Meaning |
fn:years-from-duration
|
Returns the year component of an xs:duration
value. |
fn:months-from-duration
|
Returns the months component of an
xs:duration value. |
fn:days-from-duration
|
Returns the days component of an xs:duration
value. |
fn:hours-from-duration
|
Returns the hours component of an xs:duration
value. |
fn:minutes-from-duration
|
Returns the minutes component of an xs:duration
value. |
fn:seconds-from-duration
|
Returns the seconds component of an xs:duration
value. |
fn:year-from-dateTime
|
Returns the year from an xs:dateTime value. |
fn:month-from-dateTime
|
Returns the month from an xs:dateTime value. |
fn:day-from-dateTime
|
Returns the day from an xs:dateTime value. |
fn:hours-from-dateTime
|
Returns the hours from an xs:dateTime value. |
fn:minutes-from-dateTime
|
Returns the minutes from an xs:dateTime value. |
fn:seconds-from-dateTime
|
Returns the seconds from an xs:dateTime value. |
fn:timezone-from-dateTime
|
Returns the timezone from an xs:dateTime value. |
fn:year-from-date
|
Returns the year from an xs:date value. |
fn:month-from-date
|
Returns the month from an xs:date value. |
fn:day-from-date
|
Returns the day from an xs:date value. |
fn:timezone-from-date
|
Returns the timezone from an xs:date value. |
fn:hours-from-time
|
Returns the hours from an xs:time value. |
fn:minutes-from-time
|
Returns the minutes from an xs:time value. |
fn:seconds-from-time
|
Returns the seconds from an xs:time value. |
fn:timezone-from-time
|
Returns the timezone from an xs:time value. |
fn:years-from-duration
Summary: Returns an xs:integer representing the years component
in the canonical lexical representation of the value of $arg.
The result may be negative.
If $arg is an xs:dayTimeDuration returns 0.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:years-from-duration(xs:yearMonthDuration("P20Y15M"))
returns 21.
-
fn:years-from-duration(xs:yearMonthDuration("-P15M"))
returns -1.
-
fn:years-from-duration(xs:dayTimeDuration("-P2DT15H"))
returns 0.
fn:months-from-duration
Summary: Returns an xs:integer representing the months component
in the canonical lexical representation of the value of $arg.
The result may be negative.
If $arg is an xs:dayTimeDuration returns 0.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:months-from-duration(xs:yearMonthDuration("P20Y15M"))
returns 3.
-
fn:months-from-duration(xs:yearMonthDuration("-P20Y18M"))
returns -6.
-
fn:months-from-duration(xs:dayTimeDuration("-P2DT15H0M0S"))
returns 0.
fn:days-from-duration
Summary: Returns an xs:integer representing the days component
in the canonical lexical representation of the value of $arg.
The result may be negative.
If $arg is an xs:yearMonthDuration returns 0.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:days-from-duration(xs:dayTimeDuration("P3DT10H"))
returns 3.
-
fn:days-from-duration(xs:dayTimeDuration("P3DT55H"))
returns 5.
-
fn:days-from-duration(xs:yearMonthDuration("P3Y5M"))
returns 0.
fn:hours-from-duration
Summary: Returns an xs:integer representing the hours component
in the canonical lexical representation of the value of $arg.
The result may be negative.
If $arg is an xs:yearMonthDuration returns 0.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:hours-from-duration(xs:dayTimeDuration("P3DT10H"))
returns 10.
-
fn:hours-from-duration(xs:dayTimeDuration("P3DT12H32M12S"))
returns 12.
-
fn:hours-from-duration(xs:dayTimeDuration("PT123H"))
returns 3.
-
fn:hours-from-duration(xs:dayTimeDuration("-P3DT10H"))
returns -10.
fn:minutes-from-duration
Summary: Returns an xs:integer representing the minutes
component in the canonical lexical representation of the value of
$arg. The result may be negative.
If $arg is an xs:yearMonthDuration returns 0.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:minutes-from-duration(xs:dayTimeDuration("P3DT10H"))
returns 0.
-
fn:minutes-from-duration(xs:dayTimeDuration("-P5DT12H30M"))
returns -30.
fn:seconds-from-duration
Summary: Returns an xs:decimal representing the seconds
component in the canonical lexical representation of the value of
$arg. The result may be negative.
If $arg is an xs:yearMonthDuration returns 0.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:seconds-from-duration(xs:dayTimeDuration("P3DT10H12.5S"))
returns 12.5.
-
fn:seconds-from-duration(xs:dayTimeDuration("-P256S"))
returns -16.0.
fn:year-from-dateTime
Summary: Returns an xs:integer representing the year component
in the localized value of $arg. The result may be negative.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:year-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 1999.
-
fn:year-from-dateTime(xs:dateTime("1999-05-31T21:30:00-05:00"))
returns 1999.
-
fn:year-from-dateTime(xs:dateTime("1999-12-31T19:20:00"))
returns 1999.
-
fn:year-from-dateTime(xs:dateTime("1999-12-31T24:00:00"))
returns 2000.
fn:month-from-dateTime
Summary: Returns an xs:integer between 1 and 12, both inclusive,
representing the month component in the localized value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:month-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 5.
-
fn:month-from-dateTime(xs:dateTime("1999-12-31T19:20:00-05:00"))
returns 12.
-
fn:month-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T19:20:00-05:00"),
xs:dayTimeDuration("PT0S"))) returns 1.
fn:day-from-dateTime
Summary: Returns an xs:integer between 1 and 31, both inclusive,
representing the day component in the localized value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:day-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 31.
-
fn:day-from-dateTime(xs:dateTime("1999-12-31T20:00:00-05:00"))
returns 31.
-
fn:day-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T19:20:00-05:00"),
xs:dayTimeDuration("PT0S"))) returns 1.
fn:hours-from-dateTime
Summary: Returns an xs:integer between 0 and 23, both inclusive,
representing the hours component in the localized value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:hours-from-dateTime(xs:dateTime("1999-05-31T08:20:00-05:00"))
returns 8.
-
fn:hours-from-dateTime(xs:dateTime("1999-12-31T21:20:00-05:00"))
returns 21.
-
fn:hours-from-dateTime(fn:adjust-dateTime-to-timezone(xs:dateTime("1999-12-31T21:20:00-05:00"),
xs:dayTimeDuration("PT0S"))) returns
2.
-
fn:hours-from-dateTime(xs:dateTime("1999-12-31T12:00:00"))
returns 12.
-
fn:hours-from-dateTime(xs:dateTime("1999-12-31T24:00:00"))
returns 0.
fn:minutes-from-dateTime
Summary: Returns an xs:integer value between 0 and 59, both
inclusive, representing the minute component in the localized value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:minutes-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 20 .
-
fn:minutes-from-dateTime(xs:dateTime("1999-05-31T13:30:00+05:30"))
returns 30 .
fn:seconds-from-dateTime
Summary: Returns an xs:decimal value greater than or equal to zero and less than 60,
representing the seconds and fractional seconds in the
localized value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:seconds-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns 0.
fn:timezone-from-dateTime
Summary: Returns the timezone component of $arg if any. If
$arg has a timezone component, then the result is
an xs:dayTimeDuration that indicates deviation from UTC; its
value may range from +14:00 to -14:00 hours, both inclusive. Otherwise, the
result is the empty sequence.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:timezone-from-dateTime(xs:dateTime("1999-05-31T13:20:00-05:00"))
returns the xs:dayTimeDuration whose value is
-PT5H.
-
fn:timezone-from-dateTime(xs:dateTime("2000-06-12T13:20:00Z"))
returns the xs:dayTimeDuration whose value is
PT0S.
-
fn:timezone-from-dateTime(xs:dateTime("2004-08-27T00:00:00"))
returns ().
fn:year-from-date
Summary: Returns an xs:integer representing the year in the
localized value of $arg. The value may be negative.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:year-from-date(xs:date("1999-05-31")) returns
1999.
-
fn:year-from-date(xs:date("2000-01-01+05:00"))
returns 2000.
fn:month-from-date
Summary: Returns an xs:integer between 1 and 12, both inclusive,
representing the month component in the localized value of
$arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:month-from-date(xs:date("1999-05-31-05:00"))
returns 5 .
-
fn:month-from-date(xs:date("2000-01-01+05:00"))
returns 1.
fn:day-from-date
Summary: Returns an xs:integer between 1 and 31, both inclusive,
representing the day component in the localized value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:day-from-date(xs:date("1999-05-31-05:00"))
returns 31.
-
fn:day-from-date(xs:date("2000-01-01+05:00"))
returns 1.
fn:timezone-from-date
Summary: Returns the timezone component of $arg if any. If
$arg has a timezone component, then the result is
an xs:dayTimeDuration that indicates deviation from UTC; its
value may range from +14:00 to -14:00 hours, both inclusive. Otherwise, the
result is the empty sequence.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:timezone-from-date(xs:date("1999-05-31-05:00"))
returns the xs:dayTimeDuration whose value is
-PT5H.
-
fn:timezone-from-date(xs:date("2000-06-12Z"))
returns the xs:dayTimeDuration with value PT0S.
fn:hours-from-time
Summary: Returns an xs:integer between 0 and 23, both inclusive,
representing the value of the hours component in the localized value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
Assume that the dynamic context provides an implicit timezone value of -05:00.
-
fn:hours-from-time(xs:time("11:23:00")) returns
11.
-
fn:hours-from-time(xs:time("21:23:00")) returns
21.
-
fn:hours-from-time(xs:time("01:23:00+05:00"))
returns 1.
-
fn:hours-from-time(fn:adjust-time-to-timezone(xs:time("01:23:00+05:00"),
xs:dayTimeDuration("PT0S"))) returns 20.
-
fn:hours-from-time(xs:time("24:00:00"))
returns 0.
fn:minutes-from-time
Summary: Returns an xs:integer value between 0 and 59, both
inclusive, representing the value of the minutes component in the localized
value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:minutes-from-time(xs:time("13:00:00Z")) returns
0 .
fn:seconds-from-time
Summary: Returns an xs:decimal value greater than or equal to zero and less than 60, representing the seconds and fractional seconds in the
localized value of $arg.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:seconds-from-time(xs:time("13:20:10.5")) returns
10.5.
fn:timezone-from-time
Summary: Returns the timezone component of $arg if any. If
$arg has a timezone component, then the result is
an xs:dayTimeDuration that indicates deviation from UTC; its
value may range from +14:00 to -14:00 hours, both inclusive. Otherwise, the
result is the empty sequence.
If $arg is the empty sequence, returns the empty sequence.
Examples
-
fn:timezone-from-time(xs:time("13:20:00-05:00"))
returns xs:dayTimeDuration whose value is -PT5H.
-
fn:timezone-from-time(xs:time("13:20:00")) returns ().
Arithmetic Operators on Durations
| Function |
Meaning |
op:add-yearMonthDurations
|
Adds two xs:yearMonthDurations. Returns an xs:yearMonthDuration. |
op:subtract-yearMonthDurations
|
Subtracts one xs:yearMonthDuration from another.
Returns an xs:yearMonthDuration. |
op:multiply-yearMonthDuration
|
Multiplies a xs:yearMonthDuration by an
xs:double. Returns an xs:yearMonthDuration. |
op:divide-yearMonthDuration
|
Divides an xs:yearMonthDuration by an
xs:double. Returns an xs:yearMonthDuration. |
op:divide-yearMonthDuration-by-yearMonthDuration
|
Divides an xs:yearMonthDuration by an
xs:yearMonthDuration. Returns an xs:decimal. |
op:add-dayTimeDurations
|
Adds two xs:dayTimeDurations. Returns an xs:dayTimeDuration. |
op:subtract-dayTimeDurations
|
Subtracts one xs:dayTimeDuration from another. Returns
an xs:dayTimeDuration. |
op:multiply-dayTimeDuration
|
Multiplies an xs:dayTimeDuration by a
xs:double. Returns an xs:dayTimeDuration. |
op:divide-dayTimeDuration
|
Divides an xs:dayTimeDuration by an
xs:double. Returns an xs:dayTimeDuration. |
op:divide-dayTimeDuration-by-dayTimeDuration
|
Divides an xs:dayTimeDuration by an
xs:dayTimeDuration. Returns an xs:decimal. |
op:add-yearMonthDurations
Summary: Returns the result of adding the value of $arg1 to the
value of $arg2. Backs up the "+" operator on
xs:yearMonthDuration values.
Examples
-
op:add-yearMonthDurations(xs:yearMonthDuration("P2Y11M"),
xs:yearMonthDuration("P3Y3M")) returns a
xs:yearMonthDuration value corresponding to 6
years and 2 months.
op:subtract-yearMonthDurations
Summary: Returns the result of subtracting the value of $arg2
from the value of $arg1. Backs up the "-" operator on
xs:yearMonthDuration values.
Examples
-
op:subtract-yearMonthDurations(xs:yearMonthDuration("P2Y11M"),
xs:yearMonthDuration("P3Y3M")) returns a
xs:yearMonthDuration value corresponding to
negative 4 months.
op:multiply-yearMonthDuration
Summary: Returns the result of multiplying the value of $arg1 by
$arg2. The result is rounded to the nearest month. For a value
v, 0 <= v < 0.5 rounds to 0; 0.5
<= v < 1.0 rounds to 1.
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 discussed in . If $arg2 is
NaN an error is raised
Backs up the "*" operator on xs:yearMonthDuration values.
Examples
-
op:multiply-yearMonthDuration(xs:yearMonthDuration("P2Y11M"),
2.3) returns a xs:yearMonthDuration value
corresponding to 6 years and 9 months.
op:divide-yearMonthDuration
Summary: Returns the result of dividing the value of $arg1 by
$arg2. The result is rounded to the nearest month. For a value
v, 0 <= v < 0.5 rounds to 0; 0.5
<= v < 1.0 rounds to 1.
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 discussed in . If $arg2 is
NaN an error is raised
Backs up the "div" operator on xs:yearMonthDuration and numeric values.
Examples
-
op:divide-yearMonthDuration(xs:yearMonthDuration("P2Y11M"),
1.5) returns a xs:yearMonthDuration value
corresponding to 1 year and 11 months.
op:divide-yearMonthDuration-by-yearMonthDuration
Summary: Returns the result of dividing the value of $arg1
by $arg2. Since the values of both operands are integers, the
semantics of the division is identical to op:numeric-divide with
xs:integer operands.
Backs up the "div" operator on xs:yearMonthDuration values.
Examples
-
op:divide-yearMonthDuration-by-yearMonthDuration(xs:yearMonthDuration("P3Y4M"),
xs:yearMonthDuration("-P1Y4M")) returns
-2.5.
op:add-dayTimeDurations
Summary: Returns the result of adding the value of $arg1 to the
value of $arg2. Backs up the "+" operator on
xs:dayTimeDuration values.
Examples
-
op:add-dayTimeDurations(xs:dayTimeDuration("P2DT12H5M"),
xs:dayTimeDuration("P5DT12H")) returns a
xs:dayTimeDuration value corresponding to 8 days
and 5 minutes.
op:subtract-dayTimeDurations
Summary: Returns the result of subtracting the value of $arg2
from the value of $arg1. Backs up the "-" operator on
xs:dayTimeDuration values.
Examples
-
op:subtract-dayTimeDurations(xs:dayTimeDuration("P2DT12H"),
xs:dayTimeDuration("P1DT10H30M")) returns a
xs:dayTimeDuration value corresponding to 1 day, 1
hour and 30 minutes.
op:multiply-dayTimeDuration
Summary: Returns the result of multiplying the value of $arg1 by $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 discussed in . If $arg2 is
NaN an error is raised
Backs up the "*" operator on xs:dayTimeDuration values.
Examples
-
op:multiply-dayTimeDuration(xs:dayTimeDuration("PT2H10M"),
2.1) returns a xs:dayTimeDuration value
corresponding to 4 hours and 33 minutes.
op:divide-dayTimeDuration
Summary: Returns the result of dividing the value of $arg1 by
$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 discussed in . If $arg2 is
NaN an error is raised
Backs up the "div" operator on xs:dayTimeDuration values.
Examples
-
op:divide-dayTimeDuration(xs:yearMonthDuration("P1DT2H30M10.5S"),
1.5) returns a xs:dayTimeDuration value
corresponding to 17 hours, 40 minutes and 7 seconds.
op:divide-dayTimeDuration-by-dayTimeDuration
Summary: Returns the result of dividing the value of $arg1
by $arg2. Since the values of both operands are decimals, the
semantics of the division is identical to op:numeric-divide with
xs:decimal operands.
Backs up the "div" operator on xs:dayTimeDuration values.
Examples
-
op:divide-dayTimeDuration-by-dayTimeDuration(xs:dayTimeDuration("P2DT53M11S"),
xs:dayTimeDuration("P1DT10H)) returns 1.4378349...
Timezone Adjustment Functions on Dates and Time Values
| Function |
Meaning |
fn:adjust-dateTime-to-timezone
|
Adjusts an xs:dateTime value to a specific timezone, or
to no timezone at all. |
fn:adjust-date-to-timezone
|
Adjusts an xs:date value to a specific timezone, or to
no timezone at all. |
fn:adjust-time-to-timezone
|
Adjusts an xs:time value to a specific timezone, or to
no timezone at all. |
These functions adjust the timezone component of an xs:dateTime, xs:date or
xs:time value. The $timezone argument to these functions is defined as an xs:dayTimeDuration but must be a valid timezone value.
fn:adjust-dateTime-to-timezone
Summary: Adjusts an xs:dateTime value to a specific timezone, or
to no timezone at all. If $timezone is the empty sequence,
returns an xs:dateTime without a timezone. Otherwise, returns
an xs:dateTime with a timezone.
If $timezone is not specified, then $timezone is
the value of the implicit timezone in the dynamic context.
If $arg is the empty sequence, then the result is the empty sequence.
A dynamic error is raised if
$timezone is less than -PT14H or greater than PT14H or if does not contain an integral number of minutes.
If $arg does not have a timezone component and
$timezone is the empty sequence, then the result is $arg.
If $arg does not have a timezone component and
$timezone is not the empty sequence, then the result is
$arg with $timezone as the timezone component.
If $arg has a timezone component and $timezone is
the empty sequence, then the result is the localized value of
$arg without its timezone component.
If $arg has a timezone component and $timezone is
not the empty sequence, then the result is an xs:dateTime value
with a timezone component of $timezone that is equal to $arg.
Examples
Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).
let $tz := xs:dayTimeDuration("-PT10H")
-
fn:adjust-dateTime-to-timezone(xs:dateTime("2002-03-07T10:00:00"))
returns 2002-03-07T10:00:00-05:00
-
fn:adjust-dateTime-to-timezone(xs:dateTime("2002-03-07T10:00:00-07:00"))
returns 2002-03-07T12:00:00-05:00
-
fn:adjust-dateTime-to-timezone(xs:dateTime("2002-03-07T10:00:00"),
$tz) returns 2002-03-07T10:00:00-10:00
-
fn:adjust-dateTime-to-timezone(xs:dateTime("2002-03-07T10:00:00-07:00"),
$tz) returns 2002-03-07T07:00:00-10:00
-
fn:adjust-dateTime-to-timezone(xs:dateTime("2002-03-07T10:00:00-07:00"),
xs:dayTimeDuration("PT10H")) returns 2002-03-08T03:00:00+10:00
-
fn:adjust-dateTime-to-timezone(xs:dateTime("2002-03-07T00:00:00+01:00"),
xs:dayTimeDuration("-PT8H")) returns 2002-03-06T15:00:00-08:00
-
fn:adjust-dateTime-to-timezone(xs:dateTime("2002-03-07T10:00:00"),
()) returns 2002-03-07T10:00:00
-
fn:adjust-dateTime-to-timezone(xs:dateTime("2002-03-07T10:00:00-07:00"),
()) returns 2002-03-07T10:00:00
fn:adjust-date-to-timezone
Summary: Adjusts an xs:date value to a specific timezone, or to
no timezone at all. If $timezone is the empty sequence, returns
an xs:date without a timezone. Otherwise, returns an
xs:date with a timezone. For purposes of timezone adjustment,
an xs:date is treated as an xs:dateTime with time 00:00:00.
If $timezone is not specified, then $timezone is
the value of the implicit timezone in the dynamic context.
If $arg is the empty sequence, then the result is the empty sequence.
A dynamic error is raised if
$timezone is less than -PT14H or greater than PT14H or if does not contain an integral number of minutes.
If $arg does not have a timezone component and
$timezone is the empty sequence, then the result is the value
of $arg.
If $arg does not have a timezone component and
$timezone is not the empty sequence, then the result is
$arg with $timezone as the timezone component.
If $arg has a timezone component and $timezone is
the empty sequence, then the result is the localized value of
$arg without its timezone component.
If $arg has a timezone component and $timezone is
not the empty sequence, then:
-
Let $srcdt be an xs:dateTime value, with
00:00:00 for the time component and date and timezone
components that are the same as the date and timezone components of $arg.
-
Let $r be the result of evaluating
fn:adjust-dateTime-to-timezone($srcdt, $timezone)
-
The result of this function will be a date value that has date and
timezone components that are the same as the date and timezone
components of $r.
Examples
Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).
let $tz := xs:dayTimeDuration("-PT10H")
-
fn:adjust-date-to-timezone(xs:date("2002-03-07"))
returns 2002-03-07-05:00.
-
fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00"))
returns 2002-03-07-05:00. $arg is
converted to the xs:dateTime
"2002-03-07T00:00:00-07:00". This is adjusted to the
implicit timezone, giving "2002-03-07T02:00:00-05:00".
-
fn:adjust-date-to-timezone(xs:date("2002-03-07"),
$tz) returns 2002-03-07-10:00.
-
fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00"),
$tz) returns 2002-03-06-10:00.
$arg is converted to the xs:dateTime
"2002-03-07T00:00:00-07:00". This is adjusted to the
given timezone, giving "2002-03-06T21:00:00-10:00".
-
fn:adjust-date-to-timezone(xs:date("2002-03-07"),
()) returns 2002-03-07.
-
fn:adjust-date-to-timezone(xs:date("2002-03-07-07:00"),
()) returns 2002-03-07.
fn:adjust-time-to-timezone
Summary: Adjusts an xs:time value to a specific timezone, or to
no timezone at all. If $timezone is the empty sequence, returns
an xs:time without a timezone. Otherwise, returns an
xs:time with a timezone.
If $timezone is not specified, then $timezone is
the value of the implicit timezone in the dynamic context.
If $arg is the empty sequence, then the result is the empty sequence.
A dynamic error is raised if
$timezone is less than -PT14H or greater than PT14H or if does not contain an integral number of minutes.
If $arg does not have a timezone component and
$timezone is the empty sequence, then the result is $arg.
If $arg does not have a timezone component and
$timezone is not the empty sequence, then the result is
$arg with $timezone as the timezone component.
If $arg has a timezone component and $timezone is
the empty sequence, then the result is the localized value of
$arg without its timezone component.
If $arg has a timezone component and $timezone is
not the empty sequence, then:
-
Let $srcdt be an xs:dateTime value, with
an arbitrary date for the date component and time and timezone
components that are the same as the time and timezone components of $arg.
-
Let $r be the result of evaluating
fn:adjust-dateTime-to-timezone($srcdt, $timezone)
-
The result of this function will be a time value that has time and
timezone components that are the same as the time and timezone
components of $r.
Examples
Assume the dynamic context provides an implicit timezone of -05:00 (-PT5H0M).
let $tz := xs:dayTimeDuration("-PT10H")
-
fn:adjust-time-to-timezone(xs:time("10:00:00"))
returns 10:00:00-05:00
-
fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"))
returns 12:00:00-05:00
-
fn:adjust-time-to-timezone(xs:time("10:00:00"),
$tz) returns 10:00:00-10:00
-
fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"),
$tz) returns 07:00:00-10:00
-
fn:adjust-time-to-timezone(xs:time("10:00:00"), ())
returns 10:00:00
-
fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"),
()) returns 10:00:00
-
fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"),
xs:dayTimeDuration("PT10H")) returns 03:00:00+10:00