xf:add-timezone-to-time

Adds a time zone to a time value. The timezone added to the time value is either the implicit time zone or passed in with the optional argument: $dayTimeDuration-var.

Note: The implicit time zone is obtained from the current environment. For example, if the time zone specified on your machine is the PSD (Pacific Daylight Savings), the implicit time zone would be -07:00.

Adds a time zone to a time value by invoking the following steps:

  1. If the specified time value already has a time zone value, that time zone is removed from the time value. Since the purpose of the add-timezone-to-time function is to add a timezone to a time value without a timezone, in most cases the passed in time value (argument: $time-var) will have not have a time zone, so this step will be ignored as shown in the preceding examples.
  2. Adds the time zone, specified by either the optional argument $dayTimeDuration-var or the implicit time, to the time value (argument: $time-var).
  3. Converts the new time value generated by the previous step to a Universal Coordinated Time (UTC) time zone value.

Signatures

xf:add-timezone-to-time(xs:time $time-var) —> xs:time

xf:add-timezone-to-time(xs:time $time-var, xf:dayTimeDuration, $dayTimeDuration-var) —> xs:time

Arguments

Data Type
Argument
Description

xs:time

$time-var

Contains a representation of the time.

xf:dayTimeDuration

$dayTimeDuration-var

Time zone to remove to $time-var. (Optional, if not specified the implicit time zone is used).

Returns

Returns a time with a time zone.

If $time-var contains a time zone and optional argument $dayTimeDuration-var is not specified, the passed in date and time are returned with no conversion.

Examples

Adding the Specified Timezone to the time Value

The following example adds the specified time zone to the specified time value. In this example, the specified time value: 12:00:00, initially does not have a timezone zone associated with it.

Adding the specified time zone to the specified time value, by invoking xf:date-timezone-to-time(xs:time("12:00:00", dayTimeDuration("-PT7H"))), causes the following internal conversion steps:

  1. In this example, the time zone is specified with the dayTimeDuration string: -PT7H, which is the Pacific Daylight Savings Time (PST) time zone (-07:00). This specified time zone: -07:00 is added to the specified time value: 12:00:00 resulting in the following internal time value: 12:00:00-07:00.
  2. This new time value: 19:00:00-07:00 is converted to Universal Coordinated Time (UTC), resulting in the following time value: 19:00:00Z, as shown in the following example query:
let $timeWithNoTimezone := xs:time("12:00:00")
return
<result>
	<timeWithNoTimezone>{$timeWithNoTimezone}</timeWithNoTimezone>
	<timeWithTimeZoneAdded>{ xf:add-timezone-to-time(xs:time($timeWithNoTimezone), 
	xf:dayTimeDuration("-PT7H")) }</timeWithTimeZoneAdded>
</result> 

The preceding query produces the following result:

<result>
	<timeWithNoTimezone>12:00:00</timeWithNoTimezone>
	<timeWithTimeZoneAdded>19:00:00Z</timeWithTimeZoneAdded>
</result> 

Note: The Z at the end of the 19:00:00Z value specifies that the time value is in UTC time.

Adding the Implicit Timezone to the time Value

The following example adds the implicit time zone to the specified time value. In this example, the specified time value: 12:00:00, initially does not have a timezone zone associated with it.

In this example, the implicit time zone is assumed to be -07:00, the Pacific Daylight Savings Time (PST) time zone. (The implicit time zone is the default time zone for the current machine.)

Adding the implicit time zone to the specified time value, by invoking xf:add-timezone-to-time(xs:time("12:00:00")), causes the following internal conversion steps:

  1. The implicit time zone: -07:00 is added to the specified time value: 12:00:00 resulting in the following internal time value: 12:00:00-07:00.
  2. This new time value: 19:00:00-07:00 is converted to Universal Coordinated Time (UTC), resulting in the following time value: 19:00:00Z, as shown in the following example query:
let $timeWithNoTimezone := xs:time("12:00:00")
return
<result>
	<timeWithNoTimezone>{$timeWithNoTimezone}</timeWithNoTimezone>
	<timeWithTimeZoneAdded>{ xf:add-timezone-to-time(xs:time($timeWithNoTimezone)) }
	</timeWithTimeZoneAdded>
</result> 

The preceding query produces the following result:

<result>
	<timeWithNoTimezone>12:00:00</timeWithNoTimezone>
	<timeWithTimeZoneAdded>19:00:00Z</timeWithTimeZoneAdded>
</result> 

Note: The Z at the end of the 19:00:00Z value specifies that the time value is in UTC time.

Note: The results of this query maybe be different for your machine because the implicit time zone may be different.

Related Topics

W3C add-timezone-to-time function description.

W3C time data type description.

W3C dayTimeDuration operator description.