xf:add-timezone-to-date

Adds a time zone to a date value. The timezone added to the date 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 date value by invoking the following steps:

  1. If the specified date value already has a time zone value, that time zone is removed from the date value. Since the purpose of the add-timezone-to-date function is to add a timezone to a date value without a timezone, in most cases the passed in date value (argument: $date-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 date value (argument: $date-var).
  3. Converts the new date value generated by the previous step to a Universal Coordinated Time (UTC) time zone value.

Signatures

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

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

Arguments

Data Type
Argument
Description

xs:date?

$date-var

Contains a representation of the date.

xf:dayTimeDuration

$dayTimeDuration-var

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

Returns

Returns a date with a time zone.

If $date-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 date Value

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

Adding the specified time zone to the specified date value, by invoking xf:add-timezone-to-date(xs:date("2002-12-06", 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 date value: 2002-12-06 resulting in the following internal date value: 2002-12-06-07:00.
  2. This new date value: 2002-12-06-07:00 is converted to Universal Coordinated Time (UTC), resulting in the following date value: 2002-12-06Z, as shown in the following example query:
let $dateWithNoTimezone := xs:date("2002-12-06")
return
<result>
	<dateWithNoTimezone>{$dateWithNoTimezone}</dateWithNoTimezone>
	<dateWithTimeZoneAdded>{ xf:add-timezone-to-date(xs:date($dateWithNoTimezone), 
	xf:dayTimeDuration("-PT7H")) }</dateWithTimeZoneAdded>
</result> 

The preceding query produces the following result:

<result>
	<dateWithNoTimezone>2002-12-06</dateWithNoTimezone>
	<dateWithTimeZoneAdded>2002-12-06Z</dateWithTimeZoneAdded>
</result> 

Note: The Z at the end of the 2002-12-06Z value specifies that the date value is in UTC time.

Adding the Implicit Timezone to the date Value

The following example adds the implicit time zone to the specified date value. In this example, the specified date value: 2002-12-06, 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 date value, by invoking xf:add-timezone-to-date(xs:date("2002-12-06")), causes the following internal conversion steps:

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

The preceding query produces the following result:

<result>
	<dateWithNoTimezone>2002-12-06</dateWithNoTimezone>
	<dateWithTimeZoneAdded>2002-12-06Z</dateWithTimeZoneAdded>
</result> 

Note: The Z at the end of the 2002-12-06Z value specifies that the date 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-date function description.

W3C date data type description.

W3C dayTimeDuration operator description.