adjust-time-to-timezone function

The fn:adjust-time-to-timezone function adjusts an xs:time value for a specific time zone or removes the time zone component from the value.

Syntax

time-value: The time value that is to be adjusted.
time-value is of type xs:time, or is an empty sequence.
timezone-value: A duration that represents the time zone to which time-value is to be adjusted.
timezone-value can be an empty sequence or a single value of type xdt:dayTimeDuration between -PT14H and PT14H, inclusive. The value can have an integer number of minutes and must not have a seconds component. If timezone-value is not specified, the default value is PT0H, which represents UTC.

Returned value

The returned value is either a value of type xs:time or an empty sequence depending on the parameters that are specified. If time-value is not an empty sequence, the returned value is of type xs:time. The following table describes the possible returned values:

Table 1. Types of input values and returned value for fn:adjust-time-to-timezone
`date-value`	`timezone-value`	Returned value
`time-value` that contains a timezone component	An explicit value, or no value specified (duration of PT0H)	The `time-value` adjusted for the time zone represented by `timezone-value`. The returned value contains the timezone component represented by `timezone-value`. If the time zone adjustment crosses over midnight, the change in date is ignored.
`time-value` that contains a timezone component	An empty sequence	The `time-value` with no timezone component.
`time-value` that does not contain a timezone component	An explicit value, or no value specified (duration of PT0H)	The `time-value` with a timezone component. The timezone component is the timezone represented by `timezone-value`. The time component is not adjusted for the time zone.
`time-value` that does not contain a timezone component	An empty sequence	The `time-value`.
An empty sequence	An explicit value, empty sequence, or no value specified	An empty sequence.

Examples

In the following examples, the variable $tz is a duration of -10 hours, defined as xdt:dayTimeDuration("-PT10H").

The following function adjusts the time value for 10:00 am in the UTC-7 time zone, and the function specifies a timezone-value of -PT10H.

fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"), $tz)

The returned value is 7:00:00-10:00. The time is adjusted to the time zone represented by the duration -PT10H.

The following function adjusts the time value for 1:00 pm. The time value does not have a timezone component.

fn:adjust-time-to-timezone(xs:time("13:00:00"), $tz)

The returned value is 13:00:00-10:00. The time contains a timezone component represented by the duration -PT10H.

The following function adjusts the time value for 10:00 am in the UTC-7 time zone. The function does not specify a timezone-value and uses the default value of PT0H.

fn:adjust-time-to-timezone(xs:time("10:00:00-07:00"))

The returned value is 17:00:00Z, the time adjusted to UTC.

The following function removes the timezone component from the time value 8:00 am in the UTC-7 time zone. The timezone-value is the empty sequence.

fn:adjust-time-to-timezone(xs:time("08:00:00-07:00"), ())

The returned value is 8:00:00.

The following example compares two times. The time zone adjustment crosses over the midnight and cause a date change. However, fn:adjust-time-to-timezone ignores date changes.

fn:adjust-time-to-timezone(xs:time("01:00:00+14:00"), $tz) 
   eq xs:time("01:00:00-10:00")

The returned value is true.