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-thanSummary: 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-thanSummary: 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-thanSummary: 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-thanSummary: 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-equalSummary:
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("P0D"))
returns true.
op:duration-equal(xs:yearMonthDuration("P1Y"), xs:dayTimeDuration("P365D"))
returns false.
op:duration-equal(xs:yearMonthDuration("P2Y"), xs:yearMonthDuration("P24M")) returns true.
op:duration-equal(xs:dayTimeDuration("P10D"), 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.
ExamplesAssume 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.
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-thanSummary: 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-equalSummary: 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.
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.
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.
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.
ExamplesAssume 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.
This not the result one might expect. For xs:dateTime values, a time of 24:00:00 is equivalent to 00:00:00 on the following day. For xs:time, the normalization from 24:00:00 to 00:00:00 happens before the xs:time is converted into an xs:dateTime for the purpose of the equality comparison. For xs:time, any operation on 24:00:00 produces the same result as the same operation on 00:00:00 because these are two different lexical representations of the same value.
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.
ExamplesAssume 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.
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.
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.
ExamplesAssume 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.
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.
ExamplesAssume 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-01T12:00:00Z and 2004-12-31T12:00:00Z.
op:gYear-equal(xs:gYear("1976-05:00"),
xs:gYear("1976")) returns true.
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.
ExamplesAssume 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.
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.
ExamplesAssume 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.
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.
ExamplesAssume 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.
| 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-yearMonthDurationsSummary: 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.
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.
Summary: Returns the result of multiplying the value of $arg1 by
$arg2. The result is rounded to the nearest month.
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 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.
Summary: Returns the result of dividing the value of $arg1 by
$arg2. The result is rounded to the nearest month.
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 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.
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.
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.
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.
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.
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:dayTimeDuration("P1DT2H30M10.5S"),
1.5) returns an xs:dayTimeDuration value
corresponding to 17 hours, 40 minutes and 7 seconds.
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-timezoneSummary: 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
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.
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.
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.
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
These functions support adding or subtracting a duration value to or from an
xs:dateTime, an xs:date or an xs:time
value. Appendix E of describes an algorithm for
performing such operations.
| Function | Meaning |
|---|
op:subtract-dateTimes
| Returns the difference between two xs:dateTimes as an xs:dayTimeDuration. |
op:subtract-dates
| Returns the difference between two xs:dateTimes as an xs:dayTimeDuration. |
op:subtract-times
| Returns the difference between two xs:times as an xs:dayTimeDuration. |
op:add-yearMonthDuration-to-dateTime
| Returns the end of a time period by adding an
xs:yearMonthDuration to the xs:dateTime
that starts the period. |
op:add-dayTimeDuration-to-dateTime
| Returns the end of a time period by adding an
xs:dayTimeDuration to the xs:dateTime
that starts the period. |
op:subtract-yearMonthDuration-from-dateTime
| Returns the beginning of a time period by subtracting an
xs:yearMonthDuration from the xs:dateTime
that ends the period. |
op:subtract-dayTimeDuration-from-dateTime
| Returns the beginning of a time period by subtracting an
xs:dayTimeDuration from the xs:dateTime
that ends the period. |
op:add-yearMonthDuration-to-date
| Returns the end of a time period by adding an
xs:yearMonthDuration to the xs:date that
starts the period. |
op:add-dayTimeDuration-to-date
| Returns the end of a time period by adding an
xs:dayTimeDuration to the xs:date that
starts the period. |
op:subtract-yearMonthDuration-from-date
| Returns the beginning of a time period by subtracting an
xs:yearMonthDuration from the xs:date
that ends the period. |
op:subtract-dayTimeDuration-from-date
| Returns the beginning of a time period by subtracting an
xs:dayTimeDuration from the xs:date that
ends the period. |
op:add-dayTimeDuration-to-time
| Adds the value of the hours, minutes and seconds components of an
xs:dayTimeDuration to an xs:time value. |
op:subtract-dayTimeDuration-from-time
| Subtracts the value of the hours, minutes and seconds components of
an xs:dayTimeDuration to an xs:time value. |
op:subtract-dateTimes
Summary: Returns the xs:dayTimeDuration that corresponds to the
difference between the normalized value of $arg1 and the
normalized value of $arg2. If either $arg1
or $arg2 do not contain an explicit timezone then, for the
purpose of the operation, the implicit timezone provided by the dynamic
context (See .) is assumed to be present as
part of the value.
If the normalized value of $arg1 precedes in time the normalized
value of $arg2, then the returned value is a negative duration.
Backs up the subtract, "-", operator on xs:dateTime values.
ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00.
op:subtract-dateTimes(xs:dateTime("2000-10-30T06:12:00"),
xs:dateTime("1999-11-28T09:00:00Z")) returns an
xs:dayTimeDuration value corresponding to 337
days, 2 hours and 12 minutes.
Summary: Returns the xs:dayTimeDuration that corresponds to the
difference between the starting instant of $arg1 and the
the starting instant of $arg2. If either $arg1
or $arg2 do not contain an explicit timezone then, for the
purpose of the operation, the implicit timezone provided by the dynamic
context (See .) is assumed to be present as
part of the value.
The starting instant of an xs:date is the xs:dateTime at 00:00:00 on that date.
The result is the result of subtracting the two starting instants using
op:subtract-dateTimes.
If the starting instant of $arg1 precedes in time the starting instant of $arg2, then the returned value is a negative duration.
Backs up the subtract, "-", operator on xs:date values.
ExamplesAssume that the dynamic context provides an implicit timezone value of Z. op:subtract-dates(xs:date("2000-10-30"), xs:date("1999-11-28")) returns an
xs:dayTimeDuration value corresponding to 337 days. The normalized values of the two starting instants are {2000, 10, 30, 0, 0, 0, PT0S} and {1999, 11, 28, 0, 0, 0, PT0S}.
If the dynamic context provides an implicit timezone value
of +05:00,
op:subtract-dates(xs:date("2000-10-30"),
xs:date("1999-11-28Z")) returns an
xs:dayTimeDuration value corresponding to 336 days and 19 hours. The normalized values of the two starting instants are {2000, 10, 29, 19, 0, 0, PT0S} and {1999, 11, 28, 0, 0, 0, PT0S}.
op:subtract-dates(xs:date("2000-10-15-05:00"),
xs:date("2000-10-10+02:00")) returns an
xs:dayTimeDuration value corresponding to lexical form "P5DT7H".
Summary: Returns the xs:dayTimeDuration that corresponds to the
difference between the value of $arg1 converted to an xs:dateTime using the date components from the reference xs:dateTime and the
value of $arg2 converted to an xs:dateTime using the date components from the same reference xs:dateTime . If either $arg1
or $arg2 do not contain an explicit timezone then, for the
purpose of the operation, the implicit timezone provided by the dynamic
context (See .) is assumed to be present as
part of the value.
The result is the result of subtracting the two xs:dateTimes using
op:subtract-dateTimes.
If the value of $arg1 converted to an xs:dateTime using the date components from the reference xs:dateTime precedes in time the
value of $arg2 converted to an xs:dateTime using the date components from the same reference xs:dateTime , then the returned value is a negative duration.
Backs up the subtract, "-", operator on xs:time values.
ExamplesAssume that the dynamic context provides an implicit timezone value of -05:00. Assume, also, that the date components of the reference xs:dateTime correspond to "1972-12-31".
op:subtract-times(xs:time("11:12:00Z"),
xs:time("04:00:00")) returns an
xs:dayTimeDuration value corresponding to 2 hours
and 12 minutes. This is obtained by subtracting from the xs:dateTime value {1972, 12, 31, 11, 12, 0, PT0S} the xs:dateTime value {1972, 12, 31, 9, 0, 0, PT0S}.
op:subtract-times(xs:time("11:00:00-05:00"),
xs:time("21:30:00+05:30")) returns a zero
xs:dayTimeDuration value corresponding to the lexical representation "PT0S". The two xs:dateTime values are {1972, 12, 31, 11, 0, 0, -PT5H} and {1972, 12, 31, 21, 30, 0, PT5H30M}.
These normalize to {1972, 12, 31, 16, 0, 0, PT0S} and {1972, 12, 31, 16, 0, 0, PT0S}.
op:subtract-times(xs:time("17:00:00-06:00"),
xs:time("08:00:00+09:00")) returns an
xs:dayTimeDuration value corresponding to one day or 24 hours. The two normalized xs:dateTime values are {1972, 12, 31, 23, 0, 0, PT0S} and {1972, 12, 30, 23, 0, 0, PT0S}.
op:subtract-times(xs:time("24:00:00"), xs:time("23:59:59")) returns an
xs:dayTimeDuration value corresponding to "-PT23H59M59S". The two normalized xs:dateTime values are {1972, 12, 31, 0, 0, 0, ()} and {1972, 12, 31, 23, 59, 59.0, ()}.
Summary: Returns the xs:dateTime computed by adding
$arg2 to the value of $arg1 using the
algorithm described in Appendix E of disregarding the rule about leap seconds. If
$arg2 is negative, then the result xs:dateTime
precedes $arg1.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "+" operator on xs:dateTime and
xs:yearMonthDuration values.
Examples
op:add-yearMonthDuration-to-dateTime(xs:dateTime("2000-10-30T11:12:00"),
xs:yearMonthDuration("P1Y2M")) returns an
xs:dateTime value corresponding to the lexical
representation "2001-12-30T11:12:00".
Summary: Returns the xs:dateTime computed by adding
$arg2 to the value of $arg1 using the
algorithm described in Appendix E of disregarding the rule about leap seconds. If
$arg2 is negative, then the result xs:dateTime
precedes $arg1.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "+" operator on xs:dateTime and
xs:dayTimeDuration values.
Examples
op:add-dayTimeDuration-to-dateTime(xs:dateTime("2000-10-30T11:12:00"),
xs:dayTimeDuration("P3DT1H15M")) returns an
xs:dateTime value corresponding to the lexical
representation "2000-11-02T12:27:00".
Summary: Returns the xs:dateTime computed by negating
$arg2 and adding the result to the value of
$arg1 using the algorithm described in Appendix E of disregarding the rule about leap seconds. If $arg2 is negative, then the
xs:dateTime returned follows $arg1.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "-" operator on xs:dateTime and
xs:yearMonthDuration values.
Examples
op:subtract-yearMonthDuration-from-dateTime(xs:dateTime("2000-10-30T11:12:00"),
xs:yearMonthDuration("P1Y2M")) returns an
xs:dateTime value corresponding to the lexical
representation "1999-08-30T11:12:00".
Summary: Returns the xs:dateTime computed by negating
$arg2 and adding the result to the value of
$arg1 using the algorithm described in Appendix E of disregarding the rule about leap seconds. If $arg2 is negative, then the
xs:dateTime returned follows $arg1.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "-" operator on xs:dateTime and
xs:dayTimeDuration values.
Examples
op:subtract-dayTimeDuration-from-dateTime(xs:dateTime("2000-10-30T11:12:00"),
xs:dayTimeDuration("P3DT1H15M")) returns an
xs:dateTime value corresponding to the lexical
representation "2000-10-27T09:57:00".
Summary: Returns the xs:date computed by adding
$arg2 to the starting instant of $arg1 using the
algorithm described in Appendix E of and discarding the time components from the resulting xs:dateTime. If
$arg2 is negative, then the xs:date returned
precedes $arg1.
The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "+" operator on xs:date and
xs:yearMonthDuration values.
Examples
op:add-yearMonthDuration-to-date(xs:date("2000-10-30"),
xs:yearMonthDuration("P1Y2M")) returns
the xs:date corresponding to December 30, 2001.
Summary: Returns the xs:date computed by adding
$arg2 to the starting instant of $arg1 using the
algorithm described in Appendix E of and discarding the time components from the resulting xs:dateTime. If
$arg2 is negative, then the xs:date returned
precedes $arg1.
The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "+" operator on xs:date and
xs:dayTimeDuration values.
Examples
op:add-dayTimeDuration-to-date(xs:date("2004-10-30Z"),
xs:dayTimeDuration("P2DT2H30M0S")) returns the
xs:date November 1, 2004. The starting instant of the first argument is the xs:dateTime value {2004, 10, 30, 0, 0, 0, PT0S}. Adding the second argument to this, gives the xs:dateTime value {2004, 11, 1, 2, 30, 0, PT0S}. The time components are then discarded.
Summary: Returns the xs:date computed by negating
$arg2 and adding the result to the starting instant of
$arg1 using the algorithm described in Appendix E of and discarding the time components from the resulting xs:dateTime. If $arg2 is positive, then the
xs:date returned precedes $arg1.
The starting instant of an xs:date is the xs:dateTime at 00:00:00 on that date.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "-" operator on xs:date and
xs:yearMonthDuration values.
Examples
op:subtract-yearMonthDuration-from-date(xs:date("2000-10-30"),
xs:yearMonthDuration("P1Y2M")) returns the
xs:date August 30, 1999.
op:subtract-yearMonthDuration-from-date(xs:date("2000-02-29Z"),
xs:yearMonthDuration("P1Y")) returns the
xs:date February 28,
1999 in timezone Z.
op:subtract-yearMonthDuration-from-date(xs:date("2000-10-31-05:00"),
xs:yearMonthDuration("P1Y1M")) returns the
xs:date September 30,
1999 in timezone -05:00.
Summary: Returns the xs:date computed by negating
$arg2 and adding the result to the starting instant of
$arg1 using the algorithm described in Appendix E of and discarding the time components from the resulting xs:dateTime. If $arg2 is positive, then the
xs:date returned precedes $arg1.
The starting instant of an xs:date is the xs:dateTime at 00:00:00 on that date.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "-" operator on xs:date and
xs:dayTimeDuration values.
Examples
op:subtract-dayTimeDuration-from-date(xs:date("2000-10-30"),
xs:dayTimeDuration("P3DT1H15M")) returns the
xs:date October 26, 2000.
Summary: First, the days component in the canonical lexical representation of
$arg2 is set to zero (0) and the value of the resulting
xs:dayTimeDuration is calculated. Alternatively, the value of $arg2
modulus 86,400 is used as the second argument. This value is added to the value of
$arg1 converted to an xs:dateTime using a reference date such as 1972-12-31 and the time components of the result returned. Note that the
xs:time returned may occur in a following or preceding day and
may be less than $arg1.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "+" operator on xs:time and
xs:dayTimeDuration values.
Examples
op:add-dayTimeDuration-to-time(xs:time("11:12:00"),
xs:dayTimeDuration("P3DT1H15M")) returns the
xs:time value corresponding to the lexical
representation "12:27:00".
op:add-dayTimeDuration-to-time(xs:time("23:12:00+03:00"),
xs:dayTimeDuration("P1DT3H15M")) returns the
xs:time value corresponding to the lexical
representation "02:27:00+03:00", i.e. {0, 0, 0, 2, 27, 0, PT3H}.
Summary: The result is calculated by first setting the day component in the
canonical lexical representation of $arg2 to zero (0) and
calculating the value of the resulting xs:dayTimeDuration.
Alternatively, the value of $arg2 modulus 86,400 is used as the second argument. This
value is subtracted from the value of $arg1 converted to an xs:dateTime using a reference date such as 1972-12-31 and the time components of the
result are returned. Note that the xs:time returned may occur in
a preceding or following day and may be greater than $arg1.
The result has the same timezone as $arg1. If $arg1
has no timezone, the result has no timezone.
This functions backs up the "-" operator on xs:time and
xs:dayTimeDuration values.
Examples
op:subtract-dayTimeDuration-from-time(xs:time("11:12:00"),
xs:dayTimeDuration("P3DT1H15M")) returns an
xs:time value corresponding to the lexical
representation "09:57:00".
op:subtract-dayTimeDuration-from-time(xs:time("08:20:00-05:00"),
xs:dayTimeDuration("P23DT10H10M")) returns the
xs:time value corresponding to the lexical
representation "22:10:00-05:00" i.e. {0, 0, 0, 22, 10, 0, -PT5H}