# xf:add-timezone-to-dateTime

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

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

### Signatures

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

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

### Arguments

Data Type | Argument | Description
--- | --- | ---
xs:dateTime? | $dateTime-var | Contains a representation of the date and time.
xf:dayTimeDuration | $dayTimeDuration-var | Time zone to add to $dateTime-var. (Optional, if not specified the implicit time zone is used).

### Returns

Returns a dateTime with a time zone.

If $dateTime-var contains a time zone and the 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 dateTime Value

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

Adding the specified time zone to the specified dateTime value, by invoking xf:add-timezone-to-dateTime(xs:dateTime("2002-12-06T12: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 dateTime value: 2002-12-06T12:00:00 resulting in the following internal dateTime value: 2002-12-06T12:00:00-07:00.
2. This new dateTime value: 2002-12-06T19:00:00-07:00 is converted to Universal Coordinated Time (UTC), resulting in the following dateTime value: 2002-12-06T19:00:00Z, as shown in the following example query:

    let $dateTimeWithNoTimezone := xs:dateTime("2002-12-06T12:00:00")
    return
    <result>
    	<dateTimeWithNoTimezone>{$dateTimeWithNoTimezone}</dateTimeWithNoTimezone>
    	<dateTimeWithTimeZoneAdded>{ xf:add-timezone-to-dateTime(xs:dateTime($dateTimeWithNoTimezone),
    	xf:dayTimeDuration("-PT7H")) }</dateTimeWithTimeZoneAdded>
    </result>

The preceding query produces the following result:

    <result>
    	<dateTimeWithNoTimezone>2002-12-06T12:00:00</dateTimeWithNoTimezone>
    	<dateTimeWithTimeZoneAdded>2002-12-06T19:00:00Z</dateTimeWithTimeZoneAdded>
    </result>

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

#### Adding the Implicit Timezone to the dateTime Value

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

1. The implicit time zone: -07:00 is added to the specified dateTime value: 2002-12-06T12:00:00 resulting in the following internal dateTime value: 2002-12-06T12:00:00-07:00.
2. This new dateTime value: 2002-12-06T19:00:00-07:00 is converted to Universal Coordinated Time (UTC), resulting in the following dateTime value: 2002-12-06T19:00:00Z, as shown in the following example query:

    let $dateTimeWithNoTimezone := xs:dateTime("2002-12-06T12:00:00")
    return
    <result>
    	<dateTimeWithNoTimezone>{$dateTimeWithNoTimezone}</dateTimeWithNoTimezone>
    	<dateTimeWithTimeZoneAdded>{ xf:add-timezone-to-dateTime(xs:dateTime($dateTimeWithNoTimezone)) }
    	</dateTimeWithTimeZoneAdded>
    </result>

The preceding query produces the following result:

    <result>
    	<dateTimeWithNoTimezone>2002-12-06T12:00:00</dateTimeWithNoTimezone>
    	<dateTimeWithTimeZoneAdded>2002-12-06T19:00:00Z</dateTimeWithTimeZoneAdded>
    </result>

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

W3C dateTime data type description.

W3C dayTimeDuration operator description.